Sub-device 인터페이스

Sub-device 모델과 read-only node

복잡한 V4L2 hardware는 제어된 방식으로 상호작용해야 하는 여러 integrated circuit으로 구성됩니다. Driver는 이 hardware model을 software에 반영하고 각 구성요소를 sub-device라는 software block으로 모델링합니다.

V4L2 sub-device는 보통 kernel 전용 객체입니다. Driver가 media device API를 구현하면 sub-device가 자동으로 media entity를 상속하고, 애플리케이션은 entity, pad, link 열거 API로 sub-device와 hardware topology를 탐색할 수 있습니다.

Sub-device driver와 상위 V4L2 device driver가 모두 지원하면 애플리케이션이 직접 ioctl을 호출할 character device node를 만들 수 있습니다. 이 node에서는 sub-device control 조회·읽기·쓰기, event 구독·해지·수신, pad별 image format 협상, entity 내부 pad 간 data routing 조회·변경을 수행합니다.

Sub-device node는 관례적으로 `/dev/v4l-subdev*` 이름과 major 81을 사용합니다. Driver는 device state를 바꾸지 않는 operation만 노출하는 read-only node를 선택할 수 있으며, 각 ioctl 문서가 이 모드의 제한을 정의합니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _subdev:

********************
Sub-device Interface
********************

The complex nature of V4L2 devices, where hardware is often made of
several integrated circuits that need to interact with each other in a
controlled way, leads to complex V4L2 drivers. The drivers usually
reflect the hardware model in software, and model the different hardware
components as software blocks called sub-devices.

V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
implements the media device API, they will automatically inherit from
media entities. Applications will be able to enumerate the sub-devices
and discover the hardware topology using the media entities, pads and
links enumeration API.

In addition to make sub-devices discoverable, drivers can also choose to
make them directly configurable by applications. When both the
sub-device driver and the V4L2 device driver support this, sub-devices
will feature a character device node on which ioctls can be called to

-  query, read and write sub-devices controls

-  subscribe and unsubscribe to events and retrieve them

-  negotiate image formats on individual pads

-  inspect and modify internal data routing between pads of the same entity

Sub-device character device nodes, conventionally named
``/dev/v4l-subdev*``, use major number 81.

Drivers may opt to limit the sub-device character devices to only expose
operations that do not modify the device state. In such a case the sub-devices
are referred to as ``read-only`` in the rest of this documentation, and the
related restrictions are documented in individual ioctls.

Control 병합과 sub-device event

대부분의 V4L2 control은 sub-device hardware가 구현하지만 driver는 보통 모두 병합해 video device node 하나로 노출합니다. 그래서 애플리케이션은 하나의 interface로 전체 pipeline을 제어할 수 있습니다.

Embedded platform에서는 sensor와 image processor가 contrast, white balance, faulty pixel correction 같은 동일 기능을 모두 구현할 수 있습니다. V4L2 controls API는 한 device에 같은 control 여러 개를 표현하지 못하므로 동일 control 중 하나만 남기고 나머지는 숨깁니다.

숨겨진 control은 해당 sub-device node에서 일반 V4L2 control API로 접근할 수 있습니다. Ioctl 동작은 video node와 같지만 그 sub-device가 구현한 control만 다룹니다. Driver에 따라 같은 control이 하나 이상의 V4L2 video node에도 노출될 수 있습니다.

Sub-device event API도 일반 V4L2 device node와 같지만 해당 sub-device가 생성한 event만 다룹니다. Driver가 같은 event를 하나 이상의 video node에 함께 보고할 수도 있습니다.

Controls
========

Most V4L2 controls are implemented by sub-device hardware. Drivers
usually merge all controls and expose them through video device nodes.
Applications can control all sub-devices through a single interface.

Complex devices sometimes implement the same control in different pieces
of hardware. This situation is common in embedded platforms, where both
sensors and image processing hardware implement identical functions,
such as contrast adjustment, white balance or faulty pixels correction.
As the V4L2 controls API doesn't support several identical controls in a
single device, all but one of the identical controls are hidden.

Applications can access those hidden controls through the sub-device
node with the V4L2 control API described in :ref:`control`. The ioctls
behave identically as when issued on V4L2 device nodes, with the
exception that they deal only with controls implemented in the
sub-device.

Depending on the driver, those controls might also be exposed through
one (or several) V4L2 device nodes.


Events
======

V4L2 sub-devices can notify applications of events as described in
:ref:`event`. The API behaves identically as when used on V4L2 device
nodes, with the exception that it only deals with events generated by
the sub-device. Depending on the driver, those events might also be
reported on one (or several) V4L2 device nodes.


.. _pad-level-formats:

Pad-level format과 pipeline 책임

Pad-level format API는 low-level format 설정을 user space에 노출해야 하는 매우 복잡한 장치용입니다. 일반 V4L2 애플리케이션은 이 API를 사용할 필요가 없습니다. 여기서 format은 media bus data format, frame width, frame height의 조합입니다.

일반 장치에서는 capture/output format과 selection ioctl을 요청하면 driver가 pipeline의 모든 block을 구성합니다. 복잡한 embedded pipeline은 같은 output size를 sensor scaler 또는 host image processor 등 서로 다른 구성으로 만들 수 있어 quality와 frame rate trade-off를 애플리케이션이 결정해야 합니다.

Sensor scaler는 보통 host scaler보다 품질이 낮지만 높은 frame rate를 얻으려면 sensor에서 먼저 줄여야 할 수 있습니다. 따라서 애플리케이션은 pipeline의 모든 지점 format을 명시적으로 구성합니다.

Media API driver는 `VIDIOC_SUBDEV_G_FMT`와 `VIDIOC_SUBDEV_S_FMT`로 pad별 format을 노출할 수 있습니다. 애플리케이션은 전체 pipeline의 매개변수를 일관되게 구성하고 연결된 pad 양끝의 format이 호환되는지 보장해야 합니다.

Pipeline은 `VIDIOC_STREAMON` 때 format mismatch를 검사하고 invalid configuration이면 `EPIPE`를 반환합니다. Pad 0에 `VIDIOC_SUBDEV_G_FMT`를 호출했을 때 `EINVAL`이면 해당 sub-device는 pad-level format 설정을 지원하지 않습니다.

Pad-level Formats
=================

.. warning::

    Pad-level formats are only applicable to very complex devices that
    need to expose low-level format configuration to user space. Generic
    V4L2 applications do *not* need to use the API described in this
    section.

.. note::

    For the purpose of this section, the term *format* means the
    combination of media bus data format, frame width and frame height.

Image formats are typically negotiated on video capture and output
devices using the format and
:ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is
responsible for configuring every block in the video pipeline according
to the requested format at the pipeline input and/or output.

For complex devices, such as often found in embedded systems, identical
image sizes at the output of a pipeline can be achieved using different
hardware configurations. One such example is shown on
:ref:`pipeline-scaling`, where image scaling can be performed on both
the video sensor and the host image processing hardware.


.. _pipeline-scaling:

.. kernel-figure:: pipeline.dot
    :alt:   pipeline.dot
    :align: center

    Image Format Negotiation on Pipelines

    High quality and high speed pipeline configuration



The sensor scaler is usually of less quality than the host scaler, but
scaling on the sensor is required to achieve higher frame rates.
Depending on the use case (quality vs. speed), the pipeline must be
configured differently. Applications need to configure the formats at
every point in the pipeline explicitly.

Drivers that implement the :ref:`media API <media-controller-intro>`
can expose pad-level image format configuration to applications. When
they do, applications can use the
:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to
negotiate formats on a per-pad basis.

Applications are responsible for configuring coherent parameters on the
whole pipeline and making sure that connected pads have compatible
formats. The pipeline is checked for formats mismatch at
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error
code is then returned if the configuration is invalid.

Pad-level image format configuration support can be tested by calling
the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad
0. If the driver returns an ``EINVAL`` error code pad-level format
configuration is not supported by the sub-device.

TRY/ACTIVE format 협상과 전파

Pad에서 허용되는 format은 다른 pad의 format, active link, control 같은 외부 매개변수에 의존할 수 있으므로 format 열거만으로 전체 pipeline 조합을 찾을 수 없습니다. Get/set format을 반복하는 협상 과정이 필요합니다.

`which = V4L2_SUBDEV_FORMAT_TRY`로 `VIDIOC_SUBDEV_G_FMT`와 `VIDIOC_SUBDEV_S_FMT`를 호출하면 hardware와 driver의 active state에 연결되지 않은 try format을 다룹니다. Try format 변경은 software state와 device hardware state를 모두 건드리지 않습니다.

Try format은 device state가 아니라 sub-device file handle에 저장됩니다. G_FMT는 같은 file handle에 마지막으로 설정한 try 값을 반환하므로 여러 애플리케이션이 같은 sub-device를 동시에 협상해도 서로 간섭하지 않습니다.

S_FMT는 요청 format을 device 요구에 따라 검증·수정하고 지원 가능한 값을 반환합니다. 외부 pad format이나 link 구성이 바뀌지 않는 한, driver가 반환한 format을 그대로 다시 S_FMT에 넣으면 더 이상 변경되지 않음이 보장됩니다.

Driver는 sub-device 내부에서 sink pad에서 source pad 방향으로 format을 자동 전파합니다. Source pad format 변경이 sink pad를 바꾸면 안 됩니다. Variable scaling 장치는 sink format이 바뀌면 scale factor를 default로 reset하고, 1:1을 지원하면 source format을 sink format으로 되돌리는 것이 원칙입니다.

Format은 media link를 넘어 자동 전파되지 않습니다. File handle 경계를 건너야 하기 때문입니다. 애플리케이션은 모든 link 양끝을 호환되는 format으로 명시적으로 설정해야 합니다. 동일 format은 항상 호환되고, device가 허용하면 서로 다른 format도 호환될 수 있습니다.

Format Negotiation
------------------

Acceptable formats on pads can (and usually do) depend on a number of
external parameters, such as formats on other pads, active links, or
even controls. Finding a combination of formats on all pads in a video
pipeline, acceptable to both application and driver, can't rely on
formats enumeration only. A format negotiation mechanism is required.

Central to the format negotiation mechanism are the get/set format
operations. When called with the ``which`` argument set to
:ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the
:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on
a set of formats parameters that are not connected to the hardware
configuration. Modifying those 'try' formats leaves the device state
untouched (this applies to both the software state stored in the driver
and the hardware state stored in the device itself).

While not kept as part of the device state, try formats are stored in
the sub-device file handles. A
:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return
the last try format set *on the same sub-device file handle*. Several
applications querying the same sub-device at the same time will thus not
interact with each other.

To find out whether a particular format is supported by the device,
applications use the
:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers
verify and, if needed, change the requested ``format`` based on device
requirements and return the possibly modified value. Applications can
then choose to try a different format or accept the returned value and
continue.

Formats returned by the driver during a negotiation iteration are
guaranteed to be supported by the device. In particular, drivers
guarantee that a returned format will not be further changed if passed
to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
(as long as external parameters, such as formats on other pads or links'
configuration are not changed).

Drivers automatically propagate formats inside sub-devices. When a try
or active format is set on a pad, corresponding formats on other pads of
the same sub-device can be modified by the driver. Drivers are free to
modify formats as required by the device. However, they should comply
with the following rules when possible:

-  Formats should be propagated from sink pads to source pads. Modifying
   a format on a source pad should not modify the format on any sink
   pad.

-  Sub-devices that scale frames using variable scaling factors should
   reset the scale factors to default values when sink pads formats are
   modified. If the 1:1 scaling ratio is supported, this means that
   source pads formats should be reset to the sink pads formats.

Formats are not propagated across links, as that would involve
propagating them from one sub-device file handle to another.
Applications must then take care to configure both ends of every link
explicitly with compatible formats. Identical formats on the two ends of
a link are guaranteed to be compatible. Drivers are free to accept
different formats matching device requirements as being compatible.

:ref:`sample-pipeline-config` shows a sample configuration sequence
for the pipeline described in :ref:`pipeline-scaling` (table columns
list entity names and pad numbers).

Sensor·frontend·scaler 협상 예

예제 pipeline은 Sensor/0, Frontend sink/source pad, Scaler sink pad의 format과 compose rectangle, Scaler source format을 순서대로 구성합니다. 초기 sensor native format은 2048x1536 `V4L2_MBUS_FMT_SGRBG8_1X8`이고 나머지는 default입니다.

Frontend sink를 2048x1536 SGRBG8로 설정하면 driver가 source에 전파하면서 hardware 경계 때문에 2046x1534로 조정할 수 있습니다.

애플리케이션은 Scaler sink를 frontend source와 같은 2046x1534 SGRBG8로 맞춥니다. Driver는 이 크기를 sink compose rectangle의 0,0/2046x1534와 scaler source format에 전파합니다.

마지막으로 scaler sink의 compose rectangle을 0,0/1280x960으로 설정하면 source pad format이 1280x960으로 바뀝니다. Try 협상 결과에 만족하면 `which = V4L2_SUBDEV_FORMAT_ACTIVE`로 같은 값을 적용합니다.

Hardware state를 협상 중에 반복 변경하지 않도록 먼저 TRY format 전체를 맞추고 마지막 iteration의 반환값을 ACTIVE에 사용해야 합니다. 외부 조건이 바뀌지 않았다면 driver가 그 값을 다시 조정하지 않는다는 보장을 활용합니다.

.. raw:: latex

    \begingroup
    \scriptsize
    \setlength{\tabcolsep}{2pt}

.. tabularcolumns:: |p{2.0cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|p{2.1cm}|

.. _sample-pipeline-config:

.. flat-table:: Sample Pipeline Configuration
    :header-rows:  1
    :stub-columns: 0
    :widths: 5 5 5 5 5 5 5

    * -
      - Sensor/0

        format
      - Frontend/0

        format
      - Frontend/1

        format
      - Scaler/0

        format
      - Scaler/0

        compose selection rectangle
      - Scaler/1

        format
    * - Initial state
      - 2048x1536

        SGRBG8_1X8
      - (default)
      - (default)
      - (default)
      - (default)
      - (default)
    * - Configure frontend sink format
      - 2048x1536

        SGRBG8_1X8
      - *2048x1536*

        *SGRBG8_1X8*
      - *2046x1534*

        *SGRBG8_1X8*
      - (default)
      - (default)
      - (default)
    * - Configure scaler sink format
      - 2048x1536

        SGRBG8_1X8
      - 2048x1536

        SGRBG8_1X8
      - 2046x1534

        SGRBG8_1X8
      - *2046x1534*

        *SGRBG8_1X8*
      - *0,0/2046x1534*
      - *2046x1534*

        *SGRBG8_1X8*
    * - Configure scaler sink compose selection
      - 2048x1536

        SGRBG8_1X8
      - 2048x1536

        SGRBG8_1X8
      - 2046x1534

        SGRBG8_1X8
      - 2046x1534

        SGRBG8_1X8
      - *0,0/1280x960*
      - *1280x960*

        *SGRBG8_1X8*

.. raw:: latex

    \endgroup

1. Initial state. The sensor source pad format is set to its native 3MP
   size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
   host frontend and scaler sink and source pads have the default
   values, as well as the compose rectangle on the scaler's sink pad.

2. The application configures the frontend sink pad format's size to
   2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
   driver propagates the format to the frontend source pad.

3. The application configures the scaler sink pad format's size to
   2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
   match the frontend source size and media bus code. The media bus code
   on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
   propagates the size to the compose selection rectangle on the
   scaler's sink pad, and the format to the scaler source pad.

4. The application configures the size of the compose selection
   rectangle of the scaler's sink pad 1280x960. The driver propagates
   the size to the scaler's source pad format.

When satisfied with the try results, applications can set the active
formats by setting the ``which`` argument to
``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
formats by drivers. To avoid modifying the hardware state during format
negotiation, applications should negotiate try formats first and then
modify the active settings using the try formats returned during the
last negotiation iteration. This guarantees that the active format will
be applied as-is by the driver without being modified.


.. _v4l2-subdev-selections:

Crop, scale, compose와 selection target

많은 sub-device는 input 또는 output pad에서 crop을 지원합니다. Crop은 sensor나 decoder image의 관심 영역을 고르며 digital zoom에서 확대할 부분을 선택하는 데도 사용됩니다. `struct v4l2_rect`의 왼쪽 위 좌표와 pixel 단위 크기로 표현합니다.

`VIDIOC_SUBDEV_G_SELECTION`과 `VIDIOC_SUBDEV_S_SELECTION`으로 selection rectangle을 조회하고 설정합니다. Pad format과 마찬가지로 driver는 selection target별 TRY rectangle과 ACTIVE rectangle을 저장합니다. Sink pad의 crop은 현재 pad format을 기준으로 하고, pipeline 이전 block에서 받은 image 중 sub-device 내부 처리로 보낼 sub-image를 나타냅니다.

Scaling ratio는 직접 지정하지 않고 원본 crop rectangle과 scaled compose rectangle의 크기에서 암시적으로 정해집니다. Scaling을 지원하면 sink crop을 같은 pad의 `V4L2_SEL_TGT_COMPOSE` 크기로 scale합니다. Composition 없이 scaling만 지원하면 compose의 top과 left는 사용하지 않으며 항상 0입니다.

Source pad crop의 원본은 sink pad COMPOSE rectangle입니다. Sink와 source crop 모두 원본 image 크기 안에 완전히 포함되어야 합니다. Driver는 가능한 한 요청에 가까운 rectangle을 사용하고 `V4L2_SEL_FLAG_GE` 또는 `V4L2_SEL_FLAG_LE`로 size를 위나 아래 방향으로 round할 수 있습니다.

Postfix가 없는 actual target은 현재 hardware configuration을 나타냅니다. 각 actual target에는 대응 BOUNDS target이 있고, BOUNDS는 모든 valid actual rectangle을 포함하는 가장 작은 rectangle입니다. Sensor pixel array가 십자형이나 원형이면 BOUNDS 전체를 actual rectangle로 설정할 수 없고 maximum size도 더 작을 수 있습니다.

Selections: cropping, scaling and composition
---------------------------------------------

Many sub-devices support cropping frames on their input or output pads
(or possible even on both). Cropping is used to select the area of
interest in an image, typically on an image sensor or a video decoder.
It can also be used as part of digital zoom implementations to select
the area of the image that will be scaled up.

Crop settings are defined by a crop rectangle and represented in a
struct :c:type:`v4l2_rect` by the coordinates of the top
left corner and the rectangle size. Both the coordinates and sizes are
expressed in pixels.

As for pad formats, drivers store try and active rectangles for the
selection targets :ref:`v4l2-selections-common`.

On sink pads, cropping is applied relative to the current pad format.
The pad format represents the image size as received by the sub-device
from the previous block in the pipeline, and the crop rectangle
represents the sub-image that will be transmitted further inside the
sub-device for processing.

The scaling operation changes the size of the image by scaling it to new
dimensions. The scaling ratio isn't specified explicitly, but is implied
from the original and scaled image sizes. Both sizes are represented by
struct :c:type:`v4l2_rect`.

Scaling support is optional. When supported by a subdev, the crop
rectangle on the subdev's sink pad is scaled to the size configured
using the
:ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL
using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
subdev supports scaling but not composing, the top and left values are
not used and must always be set to zero.

On source pads, cropping is similar to sink pads, with the exception
that the source size from which the cropping is performed, is the
COMPOSE rectangle on the sink pad. In both sink and source pads, the
crop rectangle must be entirely contained inside the source image size
for the crop operation.

The drivers should always use the closest possible rectangle the user
requests on all selection targets, unless specifically told otherwise.
``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
the image size either up or down. :ref:`v4l2-selection-flags`


Types of selection targets
--------------------------


Actual targets
^^^^^^^^^^^^^^

Actual targets (without a postfix) reflect the actual hardware
configuration at any point of time. There is a BOUNDS target
corresponding to every actual target.


BOUNDS targets
^^^^^^^^^^^^^^

BOUNDS targets is the smallest rectangle that contains all valid actual
rectangles. It may not be possible to set the actual rectangle as large
as the BOUNDS rectangle, however. This may be because e.g. a sensor's
pixel array is not rectangular but cross-shaped or round. The maximum
size may also be smaller than the BOUNDS rectangle.


.. _format-propagation:

설정 순서와 geometry 전파

Sub-device 내부 image processing은 항상 sink pad에서 source pad 방향으로 진행하므로 user configuration도 같은 순서로 해야 합니다. 앞 단계 변경은 뒤 stage로 전파됩니다. 이를 원하지 않으면 `V4L2_SEL_FLAG_KEEP_CONFIG`를 설정해 어떤 상황에서도 전파를 막습니다. Hardware 특성에 따라 요청 rectangle 자체가 조정될 수 있습니다.

각 단계 좌표는 바로 이전 stage의 actual size를 기준으로 합니다. 예외는 hardware가 지원하는 sink compose rectangle으로, sink compose bounds rectangle을 기준으로 합니다.

구성 순서는 sink format, sink actual crop, sink actual compose, source actual crop, source format입니다. Source format의 pixel format 등은 직접 설정하지만 width와 height는 source actual crop 크기가 결정합니다.

지원하지 않는 rectangle에 접근하면 `EINVAL`입니다. 뒤 stage가 지원되지 않는 이전 rectangle의 좌표를 참조해야 하면 그보다 앞의 지원되는 rectangle을 기준으로 삼습니다. 예를 들어 sink crop이 없으면 compose는 sink format dimension을 참조합니다.

단순 crop 예에서는 sink format 안에서 sink crop을 지정하고 그 crop 크기가 source format 크기가 됩니다. Multi-source scaling 예에서는 sink crop을 scale한 뒤 각 source pad가 scaled image에서 독립적으로 crop합니다.

전체 composition 예에서는 두 sink image를 각각 crop하고 scale해 compose bounds에 배치한 뒤, 두 source stream이 composition 결과에서 각자 crop해 나갑니다.

Order of configuration and format propagation
---------------------------------------------

Inside subdevs, the order of image processing steps will always be from
the sink pad towards the source pad. This is also reflected in the order
in which the configuration must be performed by the user: the changes
made will be propagated to any subsequent stages. If this behaviour is
not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
flag causes no propagation of the changes are allowed in any
circumstances. This may also cause the accessed rectangle to be adjusted
by the driver, depending on the properties of the underlying hardware.

The coordinates to a step always refer to the actual size of the
previous step. The exception to this rule is the sink compose
rectangle, which refers to the sink compose bounds rectangle --- if it
is supported by the hardware.

1. Sink pad format. The user configures the sink pad format. This format
   defines the parameters of the image the entity receives through the
   pad for further processing.

2. Sink pad actual crop selection. The sink pad crop defines the crop
   performed to the sink pad format.

3. Sink pad actual compose selection. The size of the sink pad compose
   rectangle defines the scaling ratio compared to the size of the sink
   pad crop rectangle. The location of the compose rectangle specifies
   the location of the actual sink compose rectangle in the sink compose
   bounds rectangle.

4. Source pad actual crop selection. Crop on the source pad defines crop
   performed to the image in the sink compose bounds rectangle.

5. Source pad format. The source pad format defines the output pixel
   format of the subdev, as well as the other parameters with the
   exception of the image width and height. Width and height are defined
   by the size of the source pad actual crop selection.

Accessing any of the above rectangles not supported by the subdev will
return ``EINVAL``. Any rectangle referring to a previous unsupported
rectangle coordinates will instead refer to the previous supported
rectangle. For example, if sink crop is not supported, the compose
selection will refer to the sink pad format dimensions instead.


.. _subdev-image-processing-crop:

.. kernel-figure:: subdev-image-processing-crop.svg
    :alt:   subdev-image-processing-crop.svg
    :align: center

    **Figure 4.5. Image processing in subdevs: simple crop example**

In the above example, the subdev supports cropping on its sink pad. To
configure it, the user sets the media bus format on the subdev's sink
pad. Now the actual crop rectangle can be set on the sink pad --- the
location and size of this rectangle reflect the location and size of a
rectangle to be cropped from the sink format. The size of the sink crop
rectangle will also be the size of the format of the subdev's source
pad.


.. _subdev-image-processing-scaling-multi-source:

.. kernel-figure:: subdev-image-processing-scaling-multi-source.svg
    :alt:   subdev-image-processing-scaling-multi-source.svg
    :align: center

    **Figure 4.6. Image processing in subdevs: scaling with multiple sources**

In this example, the subdev is capable of first cropping, then scaling
and finally cropping for two source pads individually from the resulting
scaled image. The location of the scaled image in the cropped image is
ignored in sink compose target. Both of the locations of the source crop
rectangles refer to the sink scaling rectangle, independently cropping
an area at location specified by the source crop rectangle from it.


.. _subdev-image-processing-full:

.. kernel-figure:: subdev-image-processing-full.svg
    :alt:    subdev-image-processing-full.svg
    :align:  center

    **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**

The subdev driver supports two sink pads and two source pads. The images
from both of the sink pads are individually cropped, then scaled and
further composed on the composition bounds rectangle. From that, two
independent streams are cropped and sent out of the subdev from the
source pads.

Multiplexed media pad와 stream

단순 sub-device는 서로 무관한 여러 video stream을 지원하지 않고 media link와 pad 하나에 stream 하나만 전달합니다. Sub-device가 stream을 split하거나 두 stream을 합성하더라도 pad의 input/output은 각각 single stream입니다.

MIPI CSI-2 같은 hardware는 한 bus에 여러 data stream을 multiplex합니다. 예를 들어 camera sensor의 pixel stream과 metadata stream이 하나의 source pad와 link를 통해 receiver sink pad로 전달되고, stream-aware receiver가 이를 demultiplex해 각 source pad로 route합니다.

Multiplexed stream driver는 non-multiplexed subdev driver와 호환됩니다. 다만 link의 sink 쪽 driver가 stream을 지원하지 않으면 source 쪽 stream 0만 capture할 수 있고 sink device별 추가 제한이 있을 수 있습니다.

.. toctree::
    :maxdepth: 1

    subdev-formats

.. _subdev-routing:

Streams, multiplexed media pads and internal routing
====================================================

Simple V4L2 sub-devices do not support multiple, unrelated video streams,
and only a single stream can pass through a media link and a media pad.
Thus each pad contains a format and selection configuration for that
single stream. A subdev can do stream processing and split a stream into
two or compose two streams into one, but the inputs and outputs for the
subdev are still a single stream per pad.

Some hardware, e.g. MIPI CSI-2, support multiplexed streams, that is, multiple
data streams are transmitted on the same bus, which is represented by a media
link connecting a transmitter source pad with a sink pad on the receiver. For
example, a camera sensor can produce two distinct streams, a pixel stream and a
metadata stream, which are transmitted on the multiplexed data bus, represented
by a media link which connects the single sensor's source pad with the receiver
sink pad. The stream-aware receiver will de-multiplex the streams received on
the its sink pad and allows to route them individually to one of its source
pads.

Subdevice drivers that support multiplexed streams are compatible with
non-multiplexed subdev drivers. However, if the driver at the sink end of a link
does not support streams, then only stream 0 of source end may be captured.
There may be additional limitations specific to the sink device.

Stream ID, route와 독립 configuration

Stream은 sensor 같은 source에서 SoC receiver/demultiplexer 같은 최종 sink로 흐르는 pixel data 또는 metadata content입니다. Media link는 enabled stream 전체를 양끝 사이에 전달하고 sub-device routing table이 sink pad의 incoming stream을 source pad로 보내는 방법을 정의합니다.

Stream ID는 media pad-local identifier입니다. 같은 link 양끝에서 같은 stream은 동일 ID를 사용해야 하지만 sub-device 반대편에서는 같은 stream에 다른 ID를 쓸 수 있습니다. Pipeline의 특정 지점은 sub-device와 `(pad, stream)` pair로 식별하며 multiplexing 미지원 sub-device의 stream은 항상 0입니다.

Stream 확장으로 format과 selection은 pad가 아니라 `(pad, stream)`별 설정이 됩니다. 각 route의 data flow는 다른 route와 분리되고 driver가 지원하는 범위에서 여러 sink stream→source stream route를 만들 수 있습니다. 하지만 source pad의 특정 stream에는 route 하나만 허용됩니다.

한 pad 안에서도 stream별 format과 selection은 다른 stream과 독립적입니다. 이 독립성 규칙은 향후 변경될 수 있습니다.

Understanding streams
---------------------

A stream is a stream of content (e.g. pixel data or metadata) flowing through
the media pipeline from a source (e.g. a sensor) towards the final sink (e.g. a
receiver and demultiplexer in a SoC). Each media link carries all the enabled
streams from one end of the link to the other, and sub-devices have routing
tables which describe how the incoming streams from sink pads are routed to the
source pads.

A stream ID is a media pad-local identifier for a stream. Streams IDs of
the same stream must be equal on both ends of a link. In other words,
a particular stream ID must exist on both sides of a media
link, but another stream ID can be used for the same stream at the other side
of the sub-device.

A stream at a specific point in the media pipeline is identified by the
sub-device and a (pad, stream) pair. For sub-devices that do not support
multiplexed streams the 'stream' field is always 0.

Interaction between routes, streams, formats and selections
-----------------------------------------------------------

The addition of streams to the V4L2 sub-device interface moves the sub-device
formats and selections from pads to (pad, stream) pairs. Besides the
usual pad, also the stream ID needs to be provided for setting formats and
selections. The order of configuring formats and selections along a stream is
the same as without streams (see :ref:`format-propagation`).

Instead of the sub-device wide merging of streams from all sink pads
towards all source pads, data flows for each route are separate from each
other. Any number of routes from streams on sink pads towards streams on
source pads is allowed, to the extent supported by drivers. For every
stream on a source pad, however, only a single route is allowed.

Any configurations of a stream within a pad, such as format or selections,
are independent of similar configurations on other streams. This is
subject to change in the future.

Device 유형과 stream 구성 3단계

Sub-device 유형에 따라 route activation 방식은 다르지만 `V4L2_SUBDEV_STREAM_FL_ACTIVE` flag가 설정된 route만 active입니다.

Stream 생성 장치는 일부 route를 enable/disable하거나 fixed routing을 가질 수 있습니다. Disable 가능한 route를 `VIDIOC_SUBDEV_S_ROUTING` 입력에서 생략하거나 ACTIVE flag 없이 선언하면 비활성화합니다. Ioctl 반환 route 배열에는 해당 route가 ACTIVE flag가 해제된 상태로 다시 포함됩니다.

Stream transport 장치는 보통 sink와 source pad 사이에 여러 route를 자유롭게 만들고 제한된 수만큼 동시에 active로 둘 수 있습니다. Driver가 기본 route를 만들지 않는 유형에서는 `VIDIOC_SUBDEV_S_ROUTING` 호출이 user-created route 전체를 교체하며 새 route의 format과 selection은 device default로 초기화됩니다.

Stream 구성은 sub-device별로 수행하고 sub-device 사이의 유효성은 pipeline 시작 때 검증합니다. 순서는 Media Controller API로 link 연결, `VIDIOC_SUBDEV_S_ROUTING`으로 stream과 route 선언, 각 `(pad, stream)`의 format과 selection 설정입니다.

Routing table을 설정하면 sub-device의 format과 selection이 default로 reset됩니다. 따라서 routing을 먼저 확정하고 그 뒤 format/selection을 구성해야 합니다. Format ioctl의 stream field는 route의 sink 또는 source pad에 연결된 stream ID와 같아야 합니다.

Device types and routing setup
------------------------------

Different kinds of sub-devices have differing behaviour for route activation,
depending on the hardware. In all cases, however, only routes that have the
``V4L2_SUBDEV_STREAM_FL_ACTIVE`` flag set are active.

Devices generating the streams may allow enabling and disabling some of the
routes or have a fixed routing configuration. If the routes can be disabled, not
declaring the routes (or declaring them without
``V4L2_SUBDEV_STREAM_FL_ACTIVE`` flag set) in ``VIDIOC_SUBDEV_S_ROUTING`` will
disable the routes. ``VIDIOC_SUBDEV_S_ROUTING`` will still return such routes
back to the user in the routes array, with the ``V4L2_SUBDEV_STREAM_FL_ACTIVE``
flag unset.

Devices transporting the streams almost always have more configurability with
respect to routing. Typically any route between the sub-device's sink and source
pads is possible, and multiple routes (usually up to certain limited number) may
be active simultaneously. For such devices, no routes are created by the driver
and user-created routes are fully replaced when ``VIDIOC_SUBDEV_S_ROUTING`` is
called on the sub-device. Such newly created routes have the device's default
configuration for format and selection rectangles.

Configuring streams
-------------------

The configuration of the streams is done individually for each sub-device and
the validity of the streams between sub-devices is validated when the pipeline
is started.

There are three steps in configuring the streams:

1. Set up links. Connect the pads between sub-devices using the
   :ref:`Media Controller API <media_controller>`

2. Streams. Streams are declared and their routing is configured by setting the
   routing table for the sub-device using :ref:`VIDIOC_SUBDEV_S_ROUTING
   <VIDIOC_SUBDEV_G_ROUTING>` ioctl. Note that setting the routing table will
   reset formats and selections in the sub-device to default values.

3. Configure formats and selections. Formats and selections of each stream are
   configured separately as documented for plain sub-devices in
   :ref:`format-propagation`. The stream ID is set to the same stream ID
   associated with either sink or source pads of routes configured using the
   :ref:`VIDIOC_SUBDEV_S_ROUTING <VIDIOC_SUBDEV_G_ROUTING>` ioctl.

두 sensor multiplexed routing 예

예제는 source pad 0에서 pixel stream을 내는 동일 sensor A/B 두 개, sensor와 연결된 sink pad 0/1 및 multiplexed source pad 2를 가진 bridge, sink pad 0에서 두 stream을 받아 source pad 1/2로 demultiplex하는 SoC receiver, stream별 DMA engine으로 구성됩니다.

Sensor, bridge, receiver는 `/dev/v4l-subdevX` V4L2 sub-device이고 DMA engine은 `/dev/videoX` V4L2 device입니다. 먼저 sensor→bridge, bridge→receiver, receiver→DMA media link를 일반 media controller 절차로 연결합니다.

Bridge routing은 Sensor A의 sink 0/stream 0을 source 2/stream 0으로, Sensor B의 sink 1/stream 0을 source 2/stream 1로 `V4L2_SUBDEV_ROUTE_FL_ACTIVE` 연결합니다.

Receiver routing은 sink 0/stream 0을 source 1/stream 0으로, sink 0/stream 1을 source 2/stream 0으로 active 연결합니다. Bridge link에서는 stream ID 0/1이 유지되지만 receiver source pad별로는 다시 stream 0을 사용할 수 있음을 보여 줍니다.

Routing 뒤 각 stream의 format과 selection을 구성합니다. Non-stream 방식과 차이는 ioctl의 `stream` field에 route에 연결된 stream ID를 넣는 점입니다. 보통 sensor에서 시작해 receiver 방향으로 각 endpoint의 `VIDIOC_SUBDEV_S_FMT`를 차례로 적용합니다.

Multiplexed streams setup example
---------------------------------

A simple example of a multiplexed stream setup might be as follows:

- Two identical sensors (Sensor A and Sensor B). Each sensor has a single source
  pad (pad 0) which carries a pixel data stream.

- Multiplexer bridge (Bridge). The bridge has two sink pads, connected to the
  sensors (pads 0, 1), and one source pad (pad 2), which outputs two streams.

- Receiver in the SoC (Receiver). The receiver has a single sink pad (pad 0),
  connected to the bridge, and two source pads (pads 1-2), going to the DMA
  engine. The receiver demultiplexes the incoming streams to the source pads.

- DMA Engines in the SoC (DMA Engine), one for each stream. Each DMA engine is
  connected to a single source pad in the receiver.

The sensors, the bridge and the receiver are modeled as V4L2 sub-devices,
exposed to userspace via /dev/v4l-subdevX device nodes. The DMA engines are
modeled as V4L2 devices, exposed to userspace via /dev/videoX nodes.

To configure this pipeline, the userspace must take the following steps:

1. Set up media links between entities: connect the sensors to the bridge,
   bridge to the receiver, and the receiver to the DMA engines. This step does
   not differ from normal non-multiplexed media controller setup.

2. Configure routing

.. flat-table:: Bridge routing table
    :header-rows:  1

    * - Sink Pad/Stream
      - Source Pad/Stream
      - Routing Flags
      - Comments
    * - 0/0
      - 2/0
      - V4L2_SUBDEV_ROUTE_FL_ACTIVE
      - Pixel data stream from Sensor A
    * - 1/0
      - 2/1
      - V4L2_SUBDEV_ROUTE_FL_ACTIVE
      - Pixel data stream from Sensor B

.. flat-table:: Receiver routing table
    :header-rows:  1

    * - Sink Pad/Stream
      - Source Pad/Stream
      - Routing Flags
      - Comments
    * - 0/0
      - 1/0
      - V4L2_SUBDEV_ROUTE_FL_ACTIVE
      - Pixel data stream from Sensor A
    * - 0/1
      - 2/0
      - V4L2_SUBDEV_ROUTE_FL_ACTIVE
      - Pixel data stream from Sensor B

3. Configure formats and selections

   After configuring routing, the next step is configuring the formats and
   selections for the streams. This is similar to performing this step without
   streams, with just one exception: the ``stream`` field needs to be assigned
   to the value of the stream ID.

   A common way to accomplish this is to start from the sensors and propagate
   the configurations along the stream towards the receiver, using
   :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls to configure each
   stream endpoint in each sub-device.