165 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_SUBDEV_G_ROUTING:5 6******************************************************7ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING8******************************************************9 10Name11====12 13VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity.14 15 16Synopsis17========18 19.. c:macro:: VIDIOC_SUBDEV_G_ROUTING20 21``int ioctl(int fd, VIDIOC_SUBDEV_G_ROUTING, struct v4l2_subdev_routing *argp)``22 23.. c:macro:: VIDIOC_SUBDEV_S_ROUTING24 25``int ioctl(int fd, VIDIOC_SUBDEV_S_ROUTING, struct v4l2_subdev_routing *argp)``26 27Arguments28=========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 37Description38===========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 the44``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes45with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and46setting or clearing flags of the ``flags`` field of a struct47:c:type:`v4l2_subdev_route`. Similarly to ``VIDIOC_SUBDEV_G_ROUTING``, also48``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 selections52after 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 the57``routes`` array allocated by userspace. It is set by applications for both58ioctls to indicate how many routes the kernel can return, and is never modified59by the kernel.60 61The ``num_routes`` field indicates the number of routes in the routing62table. For ``VIDIOC_SUBDEV_S_ROUTING``, it is set by userspace to the number of63routes that the application stored in the ``routes`` array. For both ioctls, it64is returned by the kernel and indicates how many routes are stored in the65subdevice routing table. This may be smaller or larger than the value of66``num_routes`` set by the application for ``VIDIOC_SUBDEV_S_ROUTING``, as67drivers may adjust the requested routing table.68 69The kernel can return a ``num_routes`` value larger than ``len_routes`` from70both ioctls. This indicates thare are more routes in the routing table than fits71the ``routes`` array. In this case, the ``routes`` array is filled by the kernel72with the first ``len_routes`` entries of the subdevice routing table. This is73not considered to be an error, and the ioctl call succeeds. If the applications74wants to retrieve the missing routes, it can issue a new75``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 in78``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_routing83 84.. flat-table:: struct v4l2_subdev_routing85 :header-rows: 086 :stub-columns: 087 :widths: 1 1 288 89 * - __u3290 - ``which``91 - Routing table to be accessed, from enum92 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.93 * - __u3294 - ``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` entries99 * - __u32100 - ``num_routes``101 - Number of entries of the routes array102 * - __u32103 - ``reserved``\ [11]104 - Reserved for future extensions. Applications and drivers must set105 the array to zero.106 107.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|108 109.. c:type:: v4l2_subdev_route110 111.. flat-table:: struct v4l2_subdev_route112 :header-rows: 0113 :stub-columns: 0114 :widths: 1 1 2115 116 * - __u32117 - ``sink_pad``118 - Sink pad number.119 * - __u32120 - ``sink_stream``121 - Sink pad stream number.122 * - __u32123 - ``source_pad``124 - Source pad number.125 * - __u32126 - ``source_stream``127 - Source pad stream number.128 * - __u32129 - ``flags``130 - Route enable/disable flags131 :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.132 * - __u32133 - ``reserved``\ [5]134 - Reserved for future extensions. Applications and drivers must set135 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_flags142 :header-rows: 0143 :stub-columns: 0144 :widths: 3 1 4145 146 * - V4L2_SUBDEV_ROUTE_FL_ACTIVE147 - 0x0001148 - The route is enabled. Set by applications.149 150Return Value151============152 153On success 0 is returned, on error -1 and the ``errno`` variable is set154appropriately. The generic error codes are described at the155:ref:`Generic Error Codes <gen-errors>` chapter.156 157EINVAL158 The sink or source pad identifiers reference a non-existing pad or reference159 pads of different types (ie. the sink_pad identifiers refers to a source160 pad), or the ``which`` field has an unsupported value.161 162E2BIG163 The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is164 larger than the number of routes the driver can handle.165