VIDIOC_SUBDEV_G_ROUTING 및 VIDIOC_SUBDEV_S_ROUTING ioctl

목적, 호출 형식과 인자

`VIDIOC_SUBDEV_G_ROUTING`과 `VIDIOC_SUBDEV_S_ROUTING`은 미디어 엔티티의 pad stream 사이 라우팅을 조회하거나 설정합니다. 라우팅 구성은 엔티티 내부 데이터 흐름을 결정하며 `argp`는 `struct v4l2_subdev_routing`을 가리킵니다.

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

.. _VIDIOC_SUBDEV_G_ROUTING:

******************************************************
ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING
******************************************************

Name
====

VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity.


Synopsis
========

.. c:macro:: VIDIOC_SUBDEV_G_ROUTING

``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_ROUTING

``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)``

Arguments
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``argp``
    Pointer to struct :c:type:`v4l2_subdev_routing`.

라우팅 설정, 초기화와 배열 크기

G_ROUTING은 현재 라우팅 테이블을 보고합니다. S_ROUTING은 `struct v4l2_subdev_route` 항목을 추가·제거하고 `flags` 비트를 설정하거나 지워 route를 활성화·비활성화하며, 적용 뒤의 route 목록을 다시 사용자 공간에 반환합니다.

S_ROUTING을 호출하면 모든 stream 구성이 초기화됩니다. 사용자 공간은 호출 뒤 `VIDIOC_SUBDEV_S_FMT` 등을 사용해 모든 stream format과 selection을 다시 구성해야 합니다.

sink pad와 source pad를 모두 가진 서브디바이스만 routing을 지원할 수 있습니다.

`len_routes`는 사용자 공간이 할당한 `routes` 배열에 들어갈 항목 수입니다. 두 ioctl 모두 응용 프로그램이 설정하며 커널은 이 필드를 변경하지 않습니다.

`num_routes`는 라우팅 테이블의 실제 route 수입니다. S_ROUTING 입력에서는 배열에 넣은 요청 항목 수이고, 두 ioctl의 출력에서는 드라이버가 조정한 뒤 서브디바이스 테이블에 저장된 route 수입니다. 하드웨어 제약 때문에 입력보다 작거나 클 수 있습니다.

커널이 `len_routes`보다 큰 `num_routes`를 반환해도 오류가 아닙니다. 배열에는 앞의 `len_routes`개만 채워지고 ioctl은 성공합니다. 나머지를 얻으려면 더 큰 배열로 G_ROUTING을 다시 호출해야 합니다.

Description
===========

These ioctls are used to get and set the routing in a media entity.
The routing configuration determines the flows of data inside an entity.

Drivers report their current routing tables using the
``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes
with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and
setting or clearing flags of the ``flags`` field of a struct
:c:type:`v4l2_subdev_route`. Similarly to ``VIDIOC_SUBDEV_G_ROUTING``, also
``VIDIOC_SUBDEV_S_ROUTING`` returns the routes back to the user.

All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called.
This means that the userspace must reconfigure all stream formats and selections
after calling the ioctl with e.g. ``VIDIOC_SUBDEV_S_FMT``.

Only subdevices which have both sink and source pads can support routing.

The ``len_routes`` field indicates the number of routes that can fit in the
``routes`` array allocated by userspace. It is set by applications for both
ioctls to indicate how many routes the kernel can return, and is never modified
by the kernel.

The ``num_routes`` field indicates the number of routes in the routing
table. For ``VIDIOC_SUBDEV_S_ROUTING``, it is set by userspace to the number of
routes that the application stored in the ``routes`` array. For both ioctls, it
is returned by the kernel and indicates how many routes are stored in the
subdevice routing table. This may be smaller or larger than the value of
``num_routes`` set by the application for ``VIDIOC_SUBDEV_S_ROUTING``, as
drivers may adjust the requested routing table.

The kernel can return a ``num_routes`` value larger than ``len_routes`` from
both ioctls. This indicates thare are more routes in the routing table than fits
the ``routes`` array. In this case, the ``routes`` array is filled by the kernel
with the first ``len_routes`` entries of the subdevice routing table. This is
not considered to be an error, and the ioctl call succeeds. If the applications
wants to retrieve the missing routes, it can issue a new
``VIDIOC_SUBDEV_G_ROUTING`` call with a large enough ``routes`` array.

``VIDIOC_SUBDEV_S_ROUTING`` may return more routes than the user provided in
``num_routes`` field due to e.g. hardware properties.

라우팅과 route 구조체

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|

.. c:type:: v4l2_subdev_routing

.. flat-table:: struct v4l2_subdev_routing
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``which``
      - Routing table to be accessed, from enum
        :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
    * - __u32
      - ``len_routes``
      - The length of the array (as in memory reserved for the array)
    * - struct :c:type:`v4l2_subdev_route`
      - ``routes[]``
      - Array of struct :c:type:`v4l2_subdev_route` entries
    * - __u32
      - ``num_routes``
      - Number of entries of the routes array
    * - __u32
      - ``reserved``\ [11]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|

.. c:type:: v4l2_subdev_route

.. flat-table:: struct v4l2_subdev_route
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``sink_pad``
      - Sink pad number.
    * - __u32
      - ``sink_stream``
      - Sink pad stream number.
    * - __u32
      - ``source_pad``
      - Source pad number.
    * - __u32
      - ``source_stream``
      - Source pad stream number.
    * - __u32
      - ``flags``
      - Route enable/disable flags
	:ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
    * - __u32
      - ``reserved``\ [5]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|

.. _v4l2-subdev-routing-flags:

.. flat-table:: enum v4l2_subdev_routing_flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
      - 0x0001
      - The route is enabled. Set by applications.

반환값과 오류

성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
   The sink or source pad identifiers reference a non-existing pad or reference
   pads of different types (ie. the sink_pad identifiers refers to a source
   pad), or the ``which`` field has an unsupported value.

E2BIG
   The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
   larger than the number of routes the driver can handle.