| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
Introduction |
| 4 |
------------ |
| 5 |
|
| 6 |
The V4L2 drivers tend to be very complex due to the complexity of the |
| 7 |
hardware: most devices have multiple ICs, export multiple device nodes in |
| 8 |
/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input |
| 9 |
(IR) devices. |
| 10 |
|
| 11 |
Especially the fact that V4L2 drivers have to setup supporting ICs to |
| 12 |
do audio/video muxing/encoding/decoding makes it more complex than most. |
| 13 |
Usually these ICs are connected to the main bridge driver through one or |
| 14 |
more I2C buses, but other buses can also be used. Such devices are |
| 15 |
called 'sub-devices'. |
| 16 |
|
| 17 |
For a long time the framework was limited to the video_device struct for |
| 18 |
creating V4L device nodes and video_buf for handling the video buffers |
| 19 |
(note that this document does not discuss the video_buf framework). |
| 20 |
|
| 21 |
This meant that all drivers had to do the setup of device instances and |
| 22 |
connecting to sub-devices themselves. Some of this is quite complicated |
| 23 |
to do right and many drivers never did do it correctly. |
| 24 |
|
| 25 |
There is also a lot of common code that could never be refactored due to |
| 26 |
the lack of a framework. |
| 27 |
|
| 28 |
So this framework sets up the basic building blocks that all drivers |
| 29 |
need and this same framework should make it much easier to refactor |
| 30 |
common code into utility functions shared by all drivers. |
| 31 |
|
| 32 |
A good example to look at as a reference is the v4l2-pci-skeleton.c |
| 33 |
source that is available in samples/v4l/. It is a skeleton driver for |
| 34 |
a PCI capture card, and demonstrates how to use the V4L2 driver |
| 35 |
framework. It can be used as a template for real PCI video capture driver. |
| 36 |
|
| 37 |
Structure of a V4L driver |
| 38 |
------------------------- |
| 39 |
|
| 40 |
All drivers have the following structure: |
| 41 |
|
| 42 |
1) A struct for each device instance containing the device state. |
| 43 |
|
| 44 |
2) A way of initializing and commanding sub-devices (if any). |
| 45 |
|
| 46 |
3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX) |
| 47 |
and keeping track of device-node specific data. |
| 48 |
|
| 49 |
4) Filehandle-specific structs containing per-filehandle data; |
| 50 |
|
| 51 |
5) video buffer handling. |
| 52 |
|
| 53 |
This is a rough schematic of how it all relates: |
| 54 |
|
| 55 |
.. code-block:: none |
| 56 |
|
| 57 |
device instances |
| 58 |
| |
| 59 |
+-sub-device instances |
| 60 |
| |
| 61 |
\-V4L2 device nodes |
| 62 |
| |
| 63 |
\-filehandle instances |
| 64 |
|
| 65 |
|
| 66 |
Structure of the V4L2 framework |
| 67 |
------------------------------- |
| 68 |
|
| 69 |
The framework closely resembles the driver structure: it has a v4l2_device |
| 70 |
struct for the device instance data, a v4l2_subdev struct to refer to |
| 71 |
sub-device instances, the video_device struct stores V4L2 device node data |
| 72 |
and the v4l2_fh struct keeps track of filehandle instances. |
| 73 |
|
| 74 |
The V4L2 framework also optionally integrates with the media framework. If a |
| 75 |
driver sets the struct v4l2_device mdev field, sub-devices and video nodes |
| 76 |
will automatically appear in the media framework as entities. |