Add documentation for VIDIOC_SUBDEV_G/S_ROUTING ioctl and add description of multiplexed media pads and internal routing to the V4L2-subdev documentation section.
Showing the changes to Documentation/userspace-api (3 of 3 files). Show all
Unified · Split
| @@ -29,6 +29,8 @@ will feature a character device node on which ioctls can be called to · 28 unmodified lines | |||
| 29 | 29 | ||
| 30 | - negotiate image formats on individual pads | 30 | - negotiate image formats on individual pads |
| 31 | 31 | ||
| 32 | - inspect and modify internal data routing between pads of the same entity | ||
| 33 | |||
| 32 | Sub-device character device nodes, conventionally named | 34 | Sub-device character device nodes, conventionally named |
| 33 | ``/dev/v4l-subdev*``, use major number 81. | 35 | ``/dev/v4l-subdev*``, use major number 81. |
| 34 | 36 | ||
| @@ -70,6 +70,7 @@ Function Reference · 69 unmodified lines | |||
| 70 | vidioc-subdev-g-crop | 70 | vidioc-subdev-g-crop |
| 71 | vidioc-subdev-g-fmt | 71 | vidioc-subdev-g-fmt |
| 72 | vidioc-subdev-g-frame-interval | 72 | vidioc-subdev-g-frame-interval |
| 73 | vidioc-subdev-g-routing | ||
| 73 | vidioc-subdev-g-selection | 74 | vidioc-subdev-g-selection |
| 74 | vidioc-subdev-querycap | 75 | vidioc-subdev-querycap |
| 75 | vidioc-subscribe-event | 76 | vidioc-subscribe-event |
| @@ -0,0 +1,147 @@ | |||
| 1 | .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later | ||
| 2 | .. c:namespace:: V4L | ||
| 3 | |||
| 4 | .. _VIDIOC_SUBDEV_G_ROUTING: | ||
| 5 | |||
| 6 | ****************************************************** | ||
| 7 | ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING | ||
| 8 | ****************************************************** | ||
| 9 | |||
| 10 | Name | ||
| 11 | ==== | ||
| 12 | |||
| 13 | VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity. | ||
| 14 | |||
| 15 | |||
| 16 | Synopsis | ||
| 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 | |||
| 27 | Arguments | ||
| 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 | |||
| 37 | Description | ||
| 38 | =========== | ||
| 39 | |||
| 40 | These ioctls are used to get and set the routing in a media entity. | ||
| 41 | The routing configuration determines the flows of data inside an entity. | ||
| 42 | |||
| 43 | Drivers report their current routing tables using the | ||
| 44 | ``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes | ||
| 45 | with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and | ||
| 46 | setting or clearing flags of the ``flags`` field of a | ||
| 47 | struct :c:type:`v4l2_subdev_route`. | ||
| 48 | |||
| 49 | All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. This | ||
| 50 | means that the userspace must reconfigure all streams after calling the ioctl | ||
| 51 | with e.g. ``VIDIOC_SUBDEV_S_FMT``. | ||
| 52 | |||
| 53 | Only subdevices which have both sink and source pads can support routing. | ||
| 54 | |||
| 55 | When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application | ||
| 56 | provided ``num_routes`` is not big enough to contain all the available routes | ||
| 57 | the subdevice exposes, drivers return the ENOSPC error code and adjust the | ||
| 58 | value of the ``num_routes`` field. Application should then reserve enough memory | ||
| 59 | for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again. | ||
| 60 | |||
| 61 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| | ||
| 62 | |||
| 63 | .. c:type:: v4l2_subdev_routing | ||
| 64 | |||
| 65 | .. flat-table:: struct v4l2_subdev_routing | ||
| 66 | :header-rows: 0 | ||
| 67 | :stub-columns: 0 | ||
| 68 | :widths: 1 1 2 | ||
| 69 | |||
| 70 | * - __u32 | ||
| 71 | - ``which`` | ||
| 72 | - Format to modified, from enum | ||
| 73 | :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. | ||
| 74 | * - struct :c:type:`v4l2_subdev_route` | ||
| 75 | - ``routes[]`` | ||
| 76 | - Array of struct :c:type:`v4l2_subdev_route` entries | ||
| 77 | * - __u32 | ||
| 78 | - ``num_routes`` | ||
| 79 | - Number of entries of the routes array | ||
| 80 | * - __u32 | ||
| 81 | - ``reserved``\ [5] | ||
| 82 | - Reserved for future extensions. Applications and drivers must set | ||
| 83 | the array to zero. | ||
| 84 | |||
| 85 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| | ||
| 86 | |||
| 87 | .. c:type:: v4l2_subdev_route | ||
| 88 | |||
| 89 | .. flat-table:: struct v4l2_subdev_route | ||
| 90 | :header-rows: 0 | ||
| 91 | :stub-columns: 0 | ||
| 92 | :widths: 1 1 2 | ||
| 93 | |||
| 94 | * - __u32 | ||
| 95 | - ``sink_pad`` | ||
| 96 | - Sink pad number. | ||
| 97 | * - __u32 | ||
| 98 | - ``sink_stream`` | ||
| 99 | - Sink pad stream number. | ||
| 100 | * - __u32 | ||
| 101 | - ``source_pad`` | ||
| 102 | - Source pad number. | ||
| 103 | * - __u32 | ||
| 104 | - ``source_stream`` | ||
| 105 | - Source pad stream number. | ||
| 106 | * - __u32 | ||
| 107 | - ``flags`` | ||
| 108 | - Route enable/disable flags | ||
| 109 | :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`. | ||
| 110 | * - __u32 | ||
| 111 | - ``reserved``\ [5] | ||
| 112 | - Reserved for future extensions. Applications and drivers must set | ||
| 113 | the array to zero. | ||
| 114 | |||
| 115 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| | ||
| 116 | |||
| 117 | .. _v4l2-subdev-routing-flags: | ||
| 118 | |||
| 119 | .. flat-table:: enum v4l2_subdev_routing_flags | ||
| 120 | :header-rows: 0 | ||
| 121 | :stub-columns: 0 | ||
| 122 | :widths: 3 1 4 | ||
| 123 | |||
| 124 | * - V4L2_SUBDEV_ROUTE_FL_ACTIVE | ||
| 125 | - 0 | ||
| 126 | - The route is enabled. Set by applications. | ||
| 127 | |||
| 128 | Return Value | ||
| 129 | ============ | ||
| 130 | |||
| 131 | On success 0 is returned, on error -1 and the ``errno`` variable is set | ||
| 132 | appropriately. The generic error codes are described at the | ||
| 133 | :ref:`Generic Error Codes <gen-errors>` chapter. | ||
| 134 | |||
| 135 | ENOSPC | ||
| 136 | The application provided ``num_routes`` is not big enough to contain | ||
| 137 | all the available routes the subdevice exposes. | ||
| 138 | |||
| 139 | EINVAL | ||
| 140 | The sink or source pad identifiers reference a non-existing pad, or reference | ||
| 141 | pads of different types (ie. the sink_pad identifiers refers to a source pad) | ||
| 142 | or the sink or source stream identifiers reference a non-existing stream on | ||
| 143 | the sink or source pad. | ||
| 144 | |||
| 145 | E2BIG | ||
| 146 | The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is | ||
| 147 | larger than the number of routes the driver can handle. | ||