Orange Pi5 kernel

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