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