Finishing the Conversion of Linux Media Documentation to ReST

This article is part of a series on improvements being made 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 Documentation/video4linux, and
  • a set of files that document some DVB drivers, under Documentation/dvb.

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 (/scripts/kernel-doc).

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:

struct v4l2_device
main struct to for V4L2 device drivers

Definition

struct v4l2_device {
  struct device * dev;
#if defined(CONFIG_MEDIA_CONTROLLER)
  struct media_device * mdev;
#endif
  struct list_head subdevs;
  spinlock_t lock;
  char name[V4L2_DEVICE_NAME_SIZE];
  void (* notify) (struct v4l2_subdev *sd,unsigned int notification, void *arg);
  struct v4l2_ctrl_handler * ctrl_handler;
  struct v4l2_prio_state prio;
  struct kref ref;
  void (* release) (struct v4l2_device *v4l2_dev);
};

Members

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[V4L2_DEVICE_NAME_SIZE]
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.

Description

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

  1. dev->driver_data points to this struct.
  2. dev might be NULL if there is no parent device

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.

Author: Mauro Carvalho Chehab

Mauro is the maintainer of the Linux kernel media and EDAC subsystems and Tizen on Yocto. He's also a major contributor to the Reliability Availability and Serviceability (RAS) subsystems.