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
47 :c:type:`v4l2_subdev_route`. Similarly to ``VI !! 47 struct :c:type:`v4l2_subdev_route`.
48 ``VIDIOC_SUBDEV_S_ROUTING`` returns the routes <<
49 <<
50 All stream configurations are reset when ``VID <<
51 This means that the userspace must reconfigure <<
52 after calling the ioctl with e.g. ``VIDIOC_SUB <<
53 48
54 Only subdevices which have both sink and sourc !! 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``.
55 52
56 The ``len_routes`` field indicates the number !! 53 Only subdevices which have both sink and source pads can support routing.
57 ``routes`` array allocated by userspace. It is <<
58 ioctls to indicate how many routes the kernel <<
59 by the kernel. <<
60 <<
61 The ``num_routes`` field indicates the number <<
62 table. For ``VIDIOC_SUBDEV_S_ROUTING``, it is <<
63 routes that the application stored in the ``ro <<
64 is returned by the kernel and indicates how ma <<
65 subdevice routing table. This may be smaller o <<
66 ``num_routes`` set by the application for ``VI <<
67 drivers may adjust the requested routing table <<
68 <<
69 The kernel can return a ``num_routes`` value l <<
70 both ioctls. This indicates thare are more rou <<
71 the ``routes`` array. In this case, the ``rout <<
72 with the first ``len_routes`` entries of the s <<
73 not considered to be an error, and the ioctl c <<
74 wants to retrieve the missing routes, it can i <<
75 ``VIDIOC_SUBDEV_G_ROUTING`` call with a large <<
76 54
77 ``VIDIOC_SUBDEV_S_ROUTING`` may return more ro !! 55 When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application
78 ``num_routes`` field due to e.g. hardware prop !! 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.
79 60
80 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm 61 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
81 62
82 .. c:type:: v4l2_subdev_routing 63 .. c:type:: v4l2_subdev_routing
83 64
84 .. flat-table:: struct v4l2_subdev_routing 65 .. flat-table:: struct v4l2_subdev_routing
85 :header-rows: 0 66 :header-rows: 0
86 :stub-columns: 0 67 :stub-columns: 0
87 :widths: 1 1 2 68 :widths: 1 1 2
88 69
89 * - __u32 70 * - __u32
90 - ``which`` 71 - ``which``
91 - Routing table to be accessed, from enu !! 72 - Format to modified, from enum
92 :ref:`v4l2_subdev_format_whence <v4l2- 73 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
93 * - __u32 <<
94 - ``len_routes`` <<
95 - The length of the array (as in memory <<
96 * - struct :c:type:`v4l2_subdev_route` 74 * - struct :c:type:`v4l2_subdev_route`
97 - ``routes[]`` 75 - ``routes[]``
98 - Array of struct :c:type:`v4l2_subdev_r 76 - Array of struct :c:type:`v4l2_subdev_route` entries
99 * - __u32 77 * - __u32
100 - ``num_routes`` 78 - ``num_routes``
101 - Number of entries of the routes array 79 - Number of entries of the routes array
102 * - __u32 80 * - __u32
103 - ``reserved``\ [11] !! 81 - ``reserved``\ [5]
104 - Reserved for future extensions. Applic 82 - Reserved for future extensions. Applications and drivers must set
105 the array to zero. 83 the array to zero.
106 84
107 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm 85 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
108 86
109 .. c:type:: v4l2_subdev_route 87 .. c:type:: v4l2_subdev_route
110 88
111 .. flat-table:: struct v4l2_subdev_route 89 .. flat-table:: struct v4l2_subdev_route
112 :header-rows: 0 90 :header-rows: 0
113 :stub-columns: 0 91 :stub-columns: 0
114 :widths: 1 1 2 92 :widths: 1 1 2
115 93
116 * - __u32 94 * - __u32
117 - ``sink_pad`` 95 - ``sink_pad``
118 - Sink pad number. 96 - Sink pad number.
119 * - __u32 97 * - __u32
120 - ``sink_stream`` 98 - ``sink_stream``
121 - Sink pad stream number. 99 - Sink pad stream number.
122 * - __u32 100 * - __u32
123 - ``source_pad`` 101 - ``source_pad``
124 - Source pad number. 102 - Source pad number.
125 * - __u32 103 * - __u32
126 - ``source_stream`` 104 - ``source_stream``
127 - Source pad stream number. 105 - Source pad stream number.
128 * - __u32 106 * - __u32
129 - ``flags`` 107 - ``flags``
130 - Route enable/disable flags 108 - Route enable/disable flags
131 :ref:`v4l2_subdev_routing_flags <v4l2- 109 :ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
132 * - __u32 110 * - __u32
133 - ``reserved``\ [5] 111 - ``reserved``\ [5]
134 - Reserved for future extensions. Applic 112 - Reserved for future extensions. Applications and drivers must set
135 the array to zero. 113 the array to zero.
136 114
137 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm 115 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
138 116
139 .. _v4l2-subdev-routing-flags: 117 .. _v4l2-subdev-routing-flags:
140 118
141 .. flat-table:: enum v4l2_subdev_routing_flags 119 .. flat-table:: enum v4l2_subdev_routing_flags
142 :header-rows: 0 120 :header-rows: 0
143 :stub-columns: 0 121 :stub-columns: 0
144 :widths: 3 1 4 122 :widths: 3 1 4
145 123
146 * - V4L2_SUBDEV_ROUTE_FL_ACTIVE 124 * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
147 - 0x0001 !! 125 - 0
148 - The route is enabled. Set by applicati 126 - The route is enabled. Set by applications.
149 127
150 Return Value 128 Return Value
151 ============ 129 ============
152 130
153 On success 0 is returned, on error -1 and the 131 On success 0 is returned, on error -1 and the ``errno`` variable is set
154 appropriately. The generic error codes are des 132 appropriately. The generic error codes are described at the
155 :ref:`Generic Error Codes <gen-errors>` chapte 133 :ref:`Generic Error Codes <gen-errors>` chapter.
156 134
>> 135 ENOSPC
>> 136 The application provided ``num_routes`` is not big enough to contain
>> 137 all the available routes the subdevice exposes.
>> 138
157 EINVAL 139 EINVAL
158 The sink or source pad identifiers referenc !! 140 The sink or source pad identifiers reference a non-existing pad, or reference
159 pads of different types (ie. the sink_pad i !! 141 pads of different types (ie. the sink_pad identifiers refers to a source pad)
160 pad), or the ``which`` field has an unsuppo !! 142 or the sink or source stream identifiers reference a non-existing stream on
>> 143 the sink or source pad.
161 144
162 E2BIG 145 E2BIG
163 The application provided ``num_routes`` for 146 The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
164 larger than the number of routes the driver 147 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.