vidioc-subdev-g-routing.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _VIDIOC_SUBDEV_G_ROUTING:
  5
  6******************************************************
  7ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING
  8******************************************************
  9
 10Name
 11====
 12
 13VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity.
 14
 15
 16Synopsis
 17========
 18
 19.. c:macro:: VIDIOC_SUBDEV_G_ROUTING
 20
 21``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)``
 22
 23.. c:macro:: VIDIOC_SUBDEV_S_ROUTING
 24
 25``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)``
 26
 27Arguments
 28=========
 29
 30``fd``
 31    File descriptor returned by :ref:`open() <func-open>`.
 32
 33``argp``
 34    Pointer to struct :c:type:`v4l2_subdev_routing`.
 35
 36
 37Description
 38===========
 39
 40These ioctls are used to get and set the routing in a media entity.
 41The routing configuration determines the flows of data inside an entity.
 42
 43Drivers report their current routing tables using the
 44``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes
 45with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and
 46setting or clearing flags of the ``flags`` field of a struct
 47:c:type:`v4l2_subdev_route`. Similarly to ``VIDIOC_SUBDEV_G_ROUTING``, also
 48``VIDIOC_SUBDEV_S_ROUTING`` returns the routes back to the user.
 49
 50All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called.
 51This means that the userspace must reconfigure all stream formats and selections
 52after calling the ioctl with e.g. ``VIDIOC_SUBDEV_S_FMT``.
 53
 54Only subdevices which have both sink and source pads can support routing.
 55
 56The ``len_routes`` field indicates the number of routes that can fit in the
 57``routes`` array allocated by userspace. It is set by applications for both
 58ioctls to indicate how many routes the kernel can return, and is never modified
 59by the kernel.
 60
 61The ``num_routes`` field indicates the number of routes in the routing
 62table. For ``VIDIOC_SUBDEV_S_ROUTING``, it is set by userspace to the number of
 63routes that the application stored in the ``routes`` array. For both ioctls, it
 64is returned by the kernel and indicates how many routes are stored in the
 65subdevice routing table. This may be smaller or larger than the value of
 66``num_routes`` set by the application for ``VIDIOC_SUBDEV_S_ROUTING``, as
 67drivers may adjust the requested routing table.
 68
 69The kernel can return a ``num_routes`` value larger than ``len_routes`` from
 70both ioctls. This indicates thare are more routes in the routing table than fits
 71the ``routes`` array. In this case, the ``routes`` array is filled by the kernel
 72with the first ``len_routes`` entries of the subdevice routing table. This is
 73not considered to be an error, and the ioctl call succeeds. If the applications
 74wants to retrieve the missing routes, it can issue a new
 75``VIDIOC_SUBDEV_G_ROUTING`` call with a large enough ``routes`` array.
 76
 77``VIDIOC_SUBDEV_S_ROUTING`` may return more routes than the user provided in
 78``num_routes`` field due to e.g. hardware properties.
 79
 80.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 81
 82.. c:type:: v4l2_subdev_routing
 83
 84.. flat-table:: struct v4l2_subdev_routing
 85    :header-rows:  0
 86    :stub-columns: 0
 87    :widths:       1 1 2
 88
 89    * - __u32
 90      - ``which``
 91      - Routing table to be accessed, from enum
 92        :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
 93    * - __u32
 94      - ``len_routes``
 95      - The length of the array (as in memory reserved for the array)
 96    * - struct :c:type:`v4l2_subdev_route`
 97      - ``routes[]``
 98      - Array of struct :c:type:`v4l2_subdev_route` entries
 99    * - __u32
100      - ``num_routes``
101      - Number of entries of the routes array
102    * - __u32
103      - ``reserved``\ [11]
104      - Reserved for future extensions. Applications and drivers must set
105	the array to zero.
106
107.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
108
109.. c:type:: v4l2_subdev_route
110
111.. flat-table:: struct v4l2_subdev_route
112    :header-rows:  0
113    :stub-columns: 0
114    :widths:       1 1 2
115
116    * - __u32
117      - ``sink_pad``
118      - Sink pad number.
119    * - __u32
120      - ``sink_stream``
121      - Sink pad stream number.
122    * - __u32
123      - ``source_pad``
124      - Source pad number.
125    * - __u32
126      - ``source_stream``
127      - Source pad stream number.
128    * - __u32
129      - ``flags``
130      - Route enable/disable flags
131	:ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
132    * - __u32
133      - ``reserved``\ [5]
134      - Reserved for future extensions. Applications and drivers must set
135	the array to zero.
136
137.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
138
139.. _v4l2-subdev-routing-flags:
140
141.. flat-table:: enum v4l2_subdev_routing_flags
142    :header-rows:  0
143    :stub-columns: 0
144    :widths:       3 1 4
145
146    * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
147      - 0x0001
148      - The route is enabled. Set by applications.
149
150Return Value
151============
152
153On success 0 is returned, on error -1 and the ``errno`` variable is set
154appropriately. The generic error codes are described at the
155:ref:`Generic Error Codes <gen-errors>` chapter.
156
157EINVAL
158   The sink or source pad identifiers reference a non-existing pad or reference
159   pads of different types (ie. the sink_pad identifiers refers to a source
160   pad), or the ``which`` field has an unsupported value.
161
162E2BIG
163   The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
164   larger than the number of routes the driver can handle.