0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Introduction
0004 ------------
0005
0006 The V4L2 drivers tend to be very complex due to the complexity of the
0007 hardware: most devices have multiple ICs, export multiple device nodes in
0008 /dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input
0009 (IR) devices.
0010
0011 Especially the fact that V4L2 drivers have to setup supporting ICs to
0012 do audio/video muxing/encoding/decoding makes it more complex than most.
0013 Usually these ICs are connected to the main bridge driver through one or
0014 more I2C buses, but other buses can also be used. Such devices are
0015 called 'sub-devices'.
0016
0017 For a long time the framework was limited to the video_device struct for
0018 creating V4L device nodes and video_buf for handling the video buffers
0019 (note that this document does not discuss the video_buf framework).
0020
0021 This meant that all drivers had to do the setup of device instances and
0022 connecting to sub-devices themselves. Some of this is quite complicated
0023 to do right and many drivers never did do it correctly.
0024
0025 There is also a lot of common code that could never be refactored due to
0026 the lack of a framework.
0027
0028 So this framework sets up the basic building blocks that all drivers
0029 need and this same framework should make it much easier to refactor
0030 common code into utility functions shared by all drivers.
0031
0032 A good example to look at as a reference is the v4l2-pci-skeleton.c
0033 source that is available in samples/v4l/. It is a skeleton driver for
0034 a PCI capture card, and demonstrates how to use the V4L2 driver
0035 framework. It can be used as a template for real PCI video capture driver.
0036
0037 Structure of a V4L driver
0038 -------------------------
0039
0040 All drivers have the following structure:
0041
0042 1) A struct for each device instance containing the device state.
0043
0044 2) A way of initializing and commanding sub-devices (if any).
0045
0046 3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX)
0047 and keeping track of device-node specific data.
0048
0049 4) Filehandle-specific structs containing per-filehandle data;
0050
0051 5) video buffer handling.
0052
0053 This is a rough schematic of how it all relates:
0054
0055 .. code-block:: none
0056
0057 device instances
0058 |
0059 +-sub-device instances
0060 |
0061 \-V4L2 device nodes
0062 |
0063 \-filehandle instances
0064
0065
0066 Structure of the V4L2 framework
0067 -------------------------------
0068
0069 The framework closely resembles the driver structure: it has a v4l2_device
0070 struct for the device instance data, a v4l2_subdev struct to refer to
0071 sub-device instances, the video_device struct stores V4L2 device node data
0072 and the v4l2_fh struct keeps track of filehandle instances.
0073
0074 The V4L2 framework also optionally integrates with the media framework. If a
0075 driver sets the struct v4l2_device mdev field, sub-devices and video nodes
0076 will automatically appear in the media framework as entities.
