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