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. 165