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