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