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