Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) .. _subdev:
^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) Sub-device Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) ********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) The complex nature of V4L2 devices, where hardware is often made of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) several integrated circuits that need to interact with each other in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) controlled way, leads to complex V4L2 drivers. The drivers usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) reflect the hardware model in software, and model the different hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) components as software blocks called sub-devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) implements the media device API, they will automatically inherit from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) media entities. Applications will be able to enumerate the sub-devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) and discover the hardware topology using the media entities, pads and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) links enumeration API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) In addition to make sub-devices discoverable, drivers can also choose to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) make them directly configurable by applications. When both the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) sub-device driver and the V4L2 device driver support this, sub-devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) will feature a character device node on which ioctls can be called to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) -  query, read and write sub-devices controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) -  subscribe and unsubscribe to events and retrieve them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) -  negotiate image formats on individual pads
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) Sub-device character device nodes, conventionally named
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ``/dev/v4l-subdev*``, use major number 81.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) Drivers may opt to limit the sub-device character devices to only expose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) operations that do not modify the device state. In such a case the sub-devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) are referred to as ``read-only`` in the rest of this documentation, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) related restrictions are documented in individual ioctls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) Most V4L2 controls are implemented by sub-device hardware. Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) usually merge all controls and expose them through video device nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) Applications can control all sub-devices through a single interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) Complex devices sometimes implement the same control in different pieces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) of hardware. This situation is common in embedded platforms, where both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) sensors and image processing hardware implement identical functions,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) such as contrast adjustment, white balance or faulty pixels correction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) As the V4L2 controls API doesn't support several identical controls in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) single device, all but one of the identical controls are hidden.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) Applications can access those hidden controls through the sub-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) node with the V4L2 control API described in :ref:`control`. The ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) behave identically as when issued on V4L2 device nodes, with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) exception that they deal only with controls implemented in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) sub-device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) Depending on the driver, those controls might also be exposed through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) one (or several) V4L2 device nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) Events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) ======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) V4L2 sub-devices can notify applications of events as described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) :ref:`event`. The API behaves identically as when used on V4L2 device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) nodes, with the exception that it only deals with events generated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) the sub-device. Depending on the driver, those events might also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) reported on one (or several) V4L2 device nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) .. _pad-level-formats:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) Pad-level Formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82)     Pad-level formats are only applicable to very complex devices that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)     need to expose low-level format configuration to user space. Generic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)     V4L2 applications do *not* need to use the API described in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85)     section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89)     For the purpose of this section, the term *format* means the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)     combination of media bus data format, frame width and frame height.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) Image formats are typically negotiated on video capture and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) devices using the format and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) :ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) responsible for configuring every block in the video pipeline according
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) to the requested format at the pipeline input and/or output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) For complex devices, such as often found in embedded systems, identical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) image sizes at the output of a pipeline can be achieved using different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) hardware configurations. One such example is shown on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) :ref:`pipeline-scaling`, where image scaling can be performed on both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) the video sensor and the host image processing hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) .. _pipeline-scaling:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) .. kernel-figure:: pipeline.dot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)     :alt:   pipeline.dot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)     :align: center
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)     Image Format Negotiation on Pipelines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)     High quality and high speed pipeline configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) The sensor scaler is usually of less quality than the host scaler, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) scaling on the sensor is required to achieve higher frame rates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Depending on the use case (quality vs. speed), the pipeline must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) configured differently. Applications need to configure the formats at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) every point in the pipeline explicitly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Drivers that implement the :ref:`media API <media-controller-intro>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) can expose pad-level image format configuration to applications. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) they do, applications can use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) :ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) negotiate formats on a per-pad basis.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Applications are responsible for configuring coherent parameters on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) whole pipeline and making sure that connected pads have compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) formats. The pipeline is checked for formats mismatch at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) code is then returned if the configuration is invalid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Pad-level image format configuration support can be tested by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 0. If the driver returns an ``EINVAL`` error code pad-level format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) configuration is not supported by the sub-device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Format Negotiation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) Acceptable formats on pads can (and usually do) depend on a number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) external parameters, such as formats on other pads, active links, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) even controls. Finding a combination of formats on all pads in a video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) pipeline, acceptable to both application and driver, can't rely on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) formats enumeration only. A format negotiation mechanism is required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Central to the format negotiation mechanism are the get/set format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) operations. When called with the ``which`` argument set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) :ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) :ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) a set of formats parameters that are not connected to the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) configuration. Modifying those 'try' formats leaves the device state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) untouched (this applies to both the software state stored in the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) and the hardware state stored in the device itself).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) While not kept as part of the device state, try formats are stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) the sub-device file handles. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) :ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) the last try format set *on the same sub-device file handle*. Several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) applications querying the same sub-device at the same time will thus not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) interact with each other.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) To find out whether a particular format is supported by the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) applications use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) verify and, if needed, change the requested ``format`` based on device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) requirements and return the possibly modified value. Applications can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) then choose to try a different format or accept the returned value and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) continue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) Formats returned by the driver during a negotiation iteration are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) guaranteed to be supported by the device. In particular, drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) guarantee that a returned format will not be further changed if passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) (as long as external parameters, such as formats on other pads or links'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) configuration are not changed).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Drivers automatically propagate formats inside sub-devices. When a try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) or active format is set on a pad, corresponding formats on other pads of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) the same sub-device can be modified by the driver. Drivers are free to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) modify formats as required by the device. However, they should comply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) with the following rules when possible:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) -  Formats should be propagated from sink pads to source pads. Modifying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)    a format on a source pad should not modify the format on any sink
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)    pad.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) -  Sub-devices that scale frames using variable scaling factors should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)    reset the scale factors to default values when sink pads formats are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)    modified. If the 1:1 scaling ratio is supported, this means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)    source pads formats should be reset to the sink pads formats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Formats are not propagated across links, as that would involve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) propagating them from one sub-device file handle to another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) Applications must then take care to configure both ends of every link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) explicitly with compatible formats. Identical formats on the two ends of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) a link are guaranteed to be compatible. Drivers are free to accept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) different formats matching device requirements as being compatible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) :ref:`sample-pipeline-config` shows a sample configuration sequence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) for the pipeline described in :ref:`pipeline-scaling` (table columns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) list entity names and pad numbers).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) .. raw:: latex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)     \scriptsize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) .. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) .. _sample-pipeline-config:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) .. flat-table:: Sample Pipeline Configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)     :header-rows:  1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)     :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)     :widths: 5 5 5 5 5 5 5
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)     * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)       - Sensor/0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)         format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)       - Frontend/0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)         format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)       - Frontend/1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)         format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)       - Scaler/0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)         format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)       - Scaler/0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)         compose selection rectangle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)       - Scaler/1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)         format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)     * - Initial state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)     * - Configure frontend sink format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)       - *2048x1536*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)         *SGRBG8_1X8*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)       - *2046x1534*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)         *SGRBG8_1X8*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)       - (default)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)     * - Configure scaler sink format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)       - 2046x1534
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)       - *2046x1534*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)         *SGRBG8_1X8*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)       - *0,0/2046x1534*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)       - *2046x1534*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)         *SGRBG8_1X8*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)     * - Configure scaler sink compose selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)       - 2048x1536
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)       - 2046x1534
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)       - 2046x1534
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)         SGRBG8_1X8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)       - *0,0/1280x960*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)       - *1280x960*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)         *SGRBG8_1X8*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) .. raw:: latex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)     \normalsize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) 1. Initial state. The sensor source pad format is set to its native 3MP
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)    size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)    host frontend and scaler sink and source pads have the default
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)    values, as well as the compose rectangle on the scaler's sink pad.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) 2. The application configures the frontend sink pad format's size to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)    2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)    driver propagates the format to the frontend source pad.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) 3. The application configures the scaler sink pad format's size to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)    2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)    match the frontend source size and media bus code. The media bus code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)    on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)    propagates the size to the compose selection rectangle on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)    scaler's sink pad, and the format to the scaler source pad.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) 4. The application configures the size of the compose selection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)    rectangle of the scaler's sink pad 1280x960. The driver propagates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)    the size to the scaler's source pad format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) When satisfied with the try results, applications can set the active
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) formats by setting the ``which`` argument to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) formats by drivers. To avoid modifying the hardware state during format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) negotiation, applications should negotiate try formats first and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) modify the active settings using the try formats returned during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) last negotiation iteration. This guarantees that the active format will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) be applied as-is by the driver without being modified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) .. _v4l2-subdev-selections:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) Selections: cropping, scaling and composition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) ---------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) Many sub-devices support cropping frames on their input or output pads
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) (or possible even on both). Cropping is used to select the area of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) interest in an image, typically on an image sensor or a video decoder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) It can also be used as part of digital zoom implementations to select
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) the area of the image that will be scaled up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) Crop settings are defined by a crop rectangle and represented in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) struct :c:type:`v4l2_rect` by the coordinates of the top
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) left corner and the rectangle size. Both the coordinates and sizes are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) expressed in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) As for pad formats, drivers store try and active rectangles for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) selection targets :ref:`v4l2-selections-common`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) On sink pads, cropping is applied relative to the current pad format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) The pad format represents the image size as received by the sub-device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) from the previous block in the pipeline, and the crop rectangle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) represents the sub-image that will be transmitted further inside the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) sub-device for processing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) The scaling operation changes the size of the image by scaling it to new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) dimensions. The scaling ratio isn't specified explicitly, but is implied
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) from the original and scaled image sizes. Both sizes are represented by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) struct :c:type:`v4l2_rect`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Scaling support is optional. When supported by a subdev, the crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) rectangle on the subdev's sink pad is scaled to the size configured
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) subdev supports scaling but not composing, the top and left values are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) not used and must always be set to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) On source pads, cropping is similar to sink pads, with the exception
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) that the source size from which the cropping is performed, is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) COMPOSE rectangle on the sink pad. In both sink and source pads, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) crop rectangle must be entirely contained inside the source image size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) for the crop operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) The drivers should always use the closest possible rectangle the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) requests on all selection targets, unless specifically told otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) ``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) the image size either up or down. :ref:`v4l2-selection-flags`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) Types of selection targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) Actual targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) ^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) Actual targets (without a postfix) reflect the actual hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) configuration at any point of time. There is a BOUNDS target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) corresponding to every actual target.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) BOUNDS targets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) ^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) BOUNDS targets is the smallest rectangle that contains all valid actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) rectangles. It may not be possible to set the actual rectangle as large
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) as the BOUNDS rectangle, however. This may be because e.g. a sensor's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) pixel array is not rectangular but cross-shaped or round. The maximum
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) size may also be smaller than the BOUNDS rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) Order of configuration and format propagation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) ---------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) Inside subdevs, the order of image processing steps will always be from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) the sink pad towards the source pad. This is also reflected in the order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) in which the configuration must be performed by the user: the changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) made will be propagated to any subsequent stages. If this behaviour is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) flag causes no propagation of the changes are allowed in any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) circumstances. This may also cause the accessed rectangle to be adjusted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) by the driver, depending on the properties of the underlying hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) The coordinates to a step always refer to the actual size of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) previous step. The exception to this rule is the sink compose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) rectangle, which refers to the sink compose bounds rectangle --- if it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) is supported by the hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) 1. Sink pad format. The user configures the sink pad format. This format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)    defines the parameters of the image the entity receives through the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424)    pad for further processing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) 2. Sink pad actual crop selection. The sink pad crop defines the crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)    performed to the sink pad format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) 3. Sink pad actual compose selection. The size of the sink pad compose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)    rectangle defines the scaling ratio compared to the size of the sink
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)    pad crop rectangle. The location of the compose rectangle specifies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)    the location of the actual sink compose rectangle in the sink compose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)    bounds rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) 4. Source pad actual crop selection. Crop on the source pad defines crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)    performed to the image in the sink compose bounds rectangle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) 5. Source pad format. The source pad format defines the output pixel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)    format of the subdev, as well as the other parameters with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)    exception of the image width and height. Width and height are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)    by the size of the source pad actual crop selection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) Accessing any of the above rectangles not supported by the subdev will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) return ``EINVAL``. Any rectangle referring to a previous unsupported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) rectangle coordinates will instead refer to the previous supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) rectangle. For example, if sink crop is not supported, the compose
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) selection will refer to the sink pad format dimensions instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) .. _subdev-image-processing-crop:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) .. kernel-figure:: subdev-image-processing-crop.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)     :alt:   subdev-image-processing-crop.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)     :align: center
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456)     **Figure 4.5. Image processing in subdevs: simple crop example**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) In the above example, the subdev supports cropping on its sink pad. To
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) configure it, the user sets the media bus format on the subdev's sink
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) pad. Now the actual crop rectangle can be set on the sink pad --- the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) location and size of this rectangle reflect the location and size of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) rectangle to be cropped from the sink format. The size of the sink crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) rectangle will also be the size of the format of the subdev's source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) pad.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) .. _subdev-image-processing-scaling-multi-source:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) .. kernel-figure:: subdev-image-processing-scaling-multi-source.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)     :alt:   subdev-image-processing-scaling-multi-source.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)     :align: center
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)     **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) In this example, the subdev is capable of first cropping, then scaling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) and finally cropping for two source pads individually from the resulting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) scaled image. The location of the scaled image in the cropped image is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) ignored in sink compose target. Both of the locations of the source crop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) rectangles refer to the sink scaling rectangle, independently cropping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) an area at location specified by the source crop rectangle from it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) .. _subdev-image-processing-full:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) .. kernel-figure:: subdev-image-processing-full.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)     :alt:    subdev-image-processing-full.svg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)     :align:  center
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)     **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) The subdev driver supports two sink pads and two source pads. The images
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) from both of the sink pads are individually cropped, then scaled and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) further composed on the composition bounds rectangle. From that, two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) independent streams are cropped and sent out of the subdev from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) source pads.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) .. toctree::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)     :maxdepth: 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)     subdev-formats