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