October 13, 2016 - Mauro Carvalho Chehab
Finishing the Conversion of Linux Media Documentation to ReST
This article is part of a series on improvements to Linux Kernel documentation; this article will describe the effort to convert the remaining Linux Media subsystem documentation.
The Linux Media Subsystem Documentation
Before Kernel 4.8, the Linux Media documentation was splt into
- the Linux Media Infrastructure userspace API (uAPI), which described the system calls and sysfs devices the media subsystem uses. The conversion of this book was already explained in a previous article from this series,
- the Media subsystem kernel internal API (kAPI), which described the functions and data structures a media driver should use to implement drivers,
- some text files describing how to use the kAPI, these are spread inside the
Documentation/directory at the Kernel tree,
- a set of files that document some V4L drivers under
- a set of files that document some DVB drivers, under
Converting the kAPI Book
The kAPI book is actually produced from special comments inside the media header files that are parsed via a perl script (
Such tags look like this:
* struct v4l2_device - main struct to for V4L2 device drivers
* @dev: pointer to struct device.
* @mdev: pointer to struct media_device
* @subdevs: used to keep track of the registered subdevs
* @lock: lock this struct; can be used by the driver as well
* if this struct is embedded into a larger struct.
* @name: unique device name, by default the driver name + bus ID
* @notify: notify callback called by some sub-devices.
* @ctrl_handler: The control handler. May be NULL.
* @prio: Device's priority state
* @ref: Keep track of the references to this struct.
* @release: Release function that is called when the ref count
* goes to 0.
* Each instance of a V4L2 device should create the v4l2_device struct,
* either stand-alone or embedded in a larger struct.
* It allows easy access to sub-devices (see v4l2-subdev.h) and provides
* basic V4L2 device-level support.
* .. note::
* #) dev->driver_data points to this struct.
* #) dev might be NULL if there is no parent device
Once converted, this above will appear as this:
Each instance of a V4L2 device should create the v4l2_device struct, either stand-alone or embedded in a larger struct.
It allows easy access to sub-devices (see v4l2-subdev.h) and provides basic V4L2 device-level support.
There is a DocBook file that provides the skeleton for the document output and specifies which headers should be included in the production of the documentation.
Due to its simplicity, converting this book was not hard. Most of the work was handled by using pandoc to convert the DocBook to ReST, and used the ReST support that was added in the
scripts/kernel-doc. However, several cross-references were broken and required fixes; additionally, the kernel-doc tags required changes to escape special characters Sphinx uses. Finally, since Sphinx has special requirements with regards to indentation, we had to add or remove white spaces and blank lines on some kernel-doc tags.
There were also some kAPI text files at
Documentation/video4linux that required some extra work required during the conversion. The most important was a file describing the V4L2 framework document; this file was split into smaller parts and regrouped. What came by surprise is that we found several other files that describe other random APIs inside the V4L2 core, like videobuffer. Since these files either described or cross-referenced other kAPI functions, it took some work to fix the cross-references.
The V4L and DVB Driver-Specific Books
The V4L and DVB driver-specific documentation was spread into a large number of small text files that weren’t organized or indexed; thus, the biggest challenge with those books was to organize them. Some files described an entire driver; other files described subsets of drivers, and a few other files actually described a core kernel API.
So, besides the file conversion (with was trivial on several cases), they needed to be classified and grouped, per driver. The files that described a kAPI used by multiple drivers needed to be moved to the kAPI book.
The conversion here was direct, each file was individually converted, classified, and grouped together into two different books: one for the V4L2 drivers, and the other one for the Digital TV drivers.
This concludes the articles that outline the process of converting the Linux Media subsystem documentation. Be sure to check out the rest of the articles in this series to learn more about changes to the Linux Kernel documentation.
About Mauro Carvalho Chehab
Mauro is the upstream maintainer of the Linux kernel media and EDAC subsystems, and also a major contributor for the Reliability Availability and Serviceability (RAS) subsystems. Mauro also maintains Tizen on Yocto packages upstream. He works for the Samsung Open Source Group since 2013. Has worked during 5 years at the Red Hat RHEL Kernel team, having broad experience in telecommunications due to his work at some of the Brazilian largest wired and wireless carriers.