1. Samsung Open Source Group 1
API and kABI Documentation and
Improvements
Mauro Carvalho Chehab
Samsung Open Source Group
Linux Kernel Summit
Seoul, South Korea: Oct.26-28, 2015
2. Samsung Open Source Group 2
API Documentation Status
● Documentation is at:
– Documentation/DocBook/media_api.tmpl; and
– Documentation/DocBook/media/*
● Broken into 4 parts:
– Part I: The V4L2 API
● Status: documentation is comprehensive – OK
– Part II: The Linux DVB API
● Status: Frontend/Net – OK, DVR/demux/CA – Outdated
– Part III: The Remote Controller API
● Status: documentation is simple, but OK
– Part IV: The Media Controller API
● Status: documentation is simple, but OK
(Need updates for MC next gen)
● Efforts are needed to make the Doc style coherent
3. Samsung Open Source Group 3
Kernel device-drivers.tmpl
● Most subsystems use DocBook/device-drivers.tmpl
– Documentation generated via kernel-doc nano format;
– Generates man-pages and have other interesting usages
<chapter id="mediadev">
<title>Media Devices</title>
<sect1><title>Video2Linux devices</title>
!Iinclude/media/tuner.h
!Iinclude/media/tuner-types.h
!Iinclude/media/tveeprom.h
!Iinclude/media/v4l2-async.h
!Iinclude/media/v4l2-ctrls.h
!Iinclude/media/v4l2-dv-timings.h
!Iinclude/media/v4l2-event.h
!Iinclude/media/v4l2-flash-led-class.h
!Iinclude/media/v4l2-mediabus.h
!Iinclude/media/v4l2-mem2mem.h
!Iinclude/media/v4l2-of.h
!Iinclude/media/v4l2-subdev.h
!Iinclude/media/videobuf2-core.h
!Iinclude/media/videobuf2-v4l2.h
!Iinclude/media/videobuf2-memops.h
..
4. Samsung Open Source Group 4
kABI Documentation Status
● Documentation is at:
– Documentation/{video4linux,dvb},
– Documentation/media-framework.txt
– Documentation/DocBook/device-drivers.tmpl
●
Also broken into 5 parts
● Patches sent for 4.3 and 4.4
●
Several headers from include/media are missing docs:
– some v4l2-*.h, part of VB2, VB1; non-core headers; soc_camera*.h,
some things like i2c_addr.h, ir-kbd-i2c.h, etc.
● Open question:
– What should be moved from Documentation/{video4linux,dvb} to the
DocBook?
● v4l2-controls.txt, v4l2-framework.txt and media-framework.txt seem to
be good canditates.
5. Samsung Open Source Group 5
kABI Documentation Status
● Media chapter at device-drivers has also 4 parts:
– Part I: The V4L2 API
● Status: not all core struct/functions are documented;
– Part II: The Linux DVB API
● Status: Demux and CA – OK, Remaining stuff incomplete;
– Part III: The Remote Controller API
● Status: not all core struct/functions are documented;
– Part IV: The Media Controller API
● Status: not all core struct/functions are documented;
● I did some effort to improve it at MC next gen
● All parts need review and improvements
– I didn't care a lot to review, as an outdated/incomplete documentation
is better than no documentation at all