From f4a6bdd1f36f940411b20fb3f615faa4127174a2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 22 Jul 2016 09:43:28 -0300 Subject: [media] rename v4l2-framework.rst to v4l2-intro.rst Now that the only remaining chapters at v4l2-framework are the introduction ones, let' s rename the file. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-core.rst | 2 +- Documentation/media/kapi/v4l2-framework.rst | 81 ----------------------------- Documentation/media/kapi/v4l2-intro.rst | 81 +++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+), 82 deletions(-) delete mode 100644 Documentation/media/kapi/v4l2-framework.rst create mode 100644 Documentation/media/kapi/v4l2-intro.rst diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index c69d167bce7a..6285c18978d1 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -4,7 +4,7 @@ Video2Linux devices .. toctree:: :maxdepth: 1 - v4l2-framework + v4l2-intro v4l2-dev v4l2-controls v4l2-device diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst deleted file mode 100644 index 7f4f26e666a2..000000000000 --- a/Documentation/media/kapi/v4l2-framework.rst +++ /dev/null @@ -1,81 +0,0 @@ -Overview of the V4L2 driver framework -===================================== - -This text documents the various structures provided by the V4L2 framework and -their relationships. - - -Introduction ------------- - -The V4L2 drivers tend to be very complex due to the complexity of the -hardware: most devices have multiple ICs, export multiple device nodes in -/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input -(IR) devices. - -Especially the fact that V4L2 drivers have to setup supporting ICs to -do audio/video muxing/encoding/decoding makes it more complex than most. -Usually these ICs are connected to the main bridge driver through one or -more I2C busses, but other busses can also be used. Such devices are -called 'sub-devices'. - -For a long time the framework was limited to the video_device struct for -creating V4L device nodes and video_buf for handling the video buffers -(note that this document does not discuss the video_buf framework). - -This meant that all drivers had to do the setup of device instances and -connecting to sub-devices themselves. Some of this is quite complicated -to do right and many drivers never did do it correctly. - -There is also a lot of common code that could never be refactored due to -the lack of a framework. - -So this framework sets up the basic building blocks that all drivers -need and this same framework should make it much easier to refactor -common code into utility functions shared by all drivers. - -A good example to look at as a reference is the v4l2-pci-skeleton.c -source that is available in samples/v4l/. It is a skeleton driver for -a PCI capture card, and demonstrates how to use the V4L2 driver -framework. It can be used as a template for real PCI video capture driver. - -Structure of a driver ---------------------- - -All drivers have the following structure: - -1) A struct for each device instance containing the device state. - -2) A way of initializing and commanding sub-devices (if any). - -3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX) - and keeping track of device-node specific data. - -4) Filehandle-specific structs containing per-filehandle data; - -5) video buffer handling. - -This is a rough schematic of how it all relates: - -.. code-block:: none - - device instances - | - +-sub-device instances - | - \-V4L2 device nodes - | - \-filehandle instances - - -Structure of the framework --------------------------- - -The framework closely resembles the driver structure: it has a v4l2_device -struct for the device instance data, a v4l2_subdev struct to refer to -sub-device instances, the video_device struct stores V4L2 device node data -and the v4l2_fh struct keeps track of filehandle instances. - -The V4L2 framework also optionally integrates with the media framework. If a -driver sets the struct v4l2_device mdev field, sub-devices and video nodes -will automatically appear in the media framework as entities. diff --git a/Documentation/media/kapi/v4l2-intro.rst b/Documentation/media/kapi/v4l2-intro.rst new file mode 100644 index 000000000000..7f4f26e666a2 --- /dev/null +++ b/Documentation/media/kapi/v4l2-intro.rst @@ -0,0 +1,81 @@ +Overview of the V4L2 driver framework +===================================== + +This text documents the various structures provided by the V4L2 framework and +their relationships. + + +Introduction +------------ + +The V4L2 drivers tend to be very complex due to the complexity of the +hardware: most devices have multiple ICs, export multiple device nodes in +/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input +(IR) devices. + +Especially the fact that V4L2 drivers have to setup supporting ICs to +do audio/video muxing/encoding/decoding makes it more complex than most. +Usually these ICs are connected to the main bridge driver through one or +more I2C busses, but other busses can also be used. Such devices are +called 'sub-devices'. + +For a long time the framework was limited to the video_device struct for +creating V4L device nodes and video_buf for handling the video buffers +(note that this document does not discuss the video_buf framework). + +This meant that all drivers had to do the setup of device instances and +connecting to sub-devices themselves. Some of this is quite complicated +to do right and many drivers never did do it correctly. + +There is also a lot of common code that could never be refactored due to +the lack of a framework. + +So this framework sets up the basic building blocks that all drivers +need and this same framework should make it much easier to refactor +common code into utility functions shared by all drivers. + +A good example to look at as a reference is the v4l2-pci-skeleton.c +source that is available in samples/v4l/. It is a skeleton driver for +a PCI capture card, and demonstrates how to use the V4L2 driver +framework. It can be used as a template for real PCI video capture driver. + +Structure of a driver +--------------------- + +All drivers have the following structure: + +1) A struct for each device instance containing the device state. + +2) A way of initializing and commanding sub-devices (if any). + +3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX) + and keeping track of device-node specific data. + +4) Filehandle-specific structs containing per-filehandle data; + +5) video buffer handling. + +This is a rough schematic of how it all relates: + +.. code-block:: none + + device instances + | + +-sub-device instances + | + \-V4L2 device nodes + | + \-filehandle instances + + +Structure of the framework +-------------------------- + +The framework closely resembles the driver structure: it has a v4l2_device +struct for the device instance data, a v4l2_subdev struct to refer to +sub-device instances, the video_device struct stores V4L2 device node data +and the v4l2_fh struct keeps track of filehandle instances. + +The V4L2 framework also optionally integrates with the media framework. If a +driver sets the struct v4l2_device mdev field, sub-devices and video nodes +will automatically appear in the media framework as entities. -- cgit v1.2.3