API and kABI Documentation and Improvements
0 likes3,890 views
Mauro Carvalho Chehab from Samsung Open Source Group presented on the status of API and kABI documentation for media devices in the Linux kernel. The documentation is split across several files and locations. For some parts like V4L2 and DVB, the documentation is comprehensive or mostly complete, but other areas need updates and improvements. Efforts are needed to make the documentation style consistent and move some documents from separate files into the main device-drivers documentation. Not all core media structures and functions are currently documented.
API and kABI Documentation and Improvements
- 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
- 6. Samsung Open Source Group 6 Thank You!
- 7. Samsung Open Source Group 6 Thank You!