1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_SUBDEV_G_ROUTING:
5
6******************************************************
7ioctl VIDIOC_SUBDEV_G_ROUTING, VIDIOC_SUBDEV_S_ROUTING
8******************************************************
9
10Name
11====
12
13VIDIOC_SUBDEV_G_ROUTING - VIDIOC_SUBDEV_S_ROUTING - Get or set routing between streams of media pads in a media entity.
14
15
16Synopsis
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
27Arguments
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
37Description
38===========
39
40These ioctls are used to get and set the routing in a media entity.
41The routing configuration determines the flows of data inside an entity.
42
43Drivers report their current routing tables using the
44``VIDIOC_SUBDEV_G_ROUTING`` ioctl and application may enable or disable routes
45with the ``VIDIOC_SUBDEV_S_ROUTING`` ioctl, by adding or removing routes and
46setting or clearing flags of the  ``flags`` field of a
47struct :c:type:`v4l2_subdev_route`.
48
49All stream configurations are reset when ``VIDIOC_SUBDEV_S_ROUTING`` is called. This
50means that the userspace must reconfigure all streams after calling the ioctl
51with e.g. ``VIDIOC_SUBDEV_S_FMT``.
52
53Only subdevices which have both sink and source pads can support routing.
54
55When inspecting routes through ``VIDIOC_SUBDEV_G_ROUTING`` and the application
56provided ``num_routes`` is not big enough to contain all the available routes
57the subdevice exposes, drivers return the ENOSPC error code and adjust the
58value of the ``num_routes`` field. Application should then reserve enough memory
59for all the route entries and call ``VIDIOC_SUBDEV_G_ROUTING`` again.
60
61On a successful ``VIDIOC_SUBDEV_G_ROUTING`` call the driver updates the
62``num_routes`` field to reflect the actual number of routes returned.
63
64.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
65
66.. c:type:: v4l2_subdev_routing
67
68.. flat-table:: struct v4l2_subdev_routing
69    :header-rows:  0
70    :stub-columns: 0
71    :widths:       1 1 2
72
73    * - __u32
74      - ``which``
75      - Format to modified, from enum
76        :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
77    * - struct :c:type:`v4l2_subdev_route`
78      - ``routes[]``
79      - Array of struct :c:type:`v4l2_subdev_route` entries
80    * - __u32
81      - ``num_routes``
82      - Number of entries of the routes array
83    * - __u32
84      - ``reserved``\ [5]
85      - Reserved for future extensions. Applications and drivers must set
86	the array to zero.
87
88.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
89
90.. c:type:: v4l2_subdev_route
91
92.. flat-table:: struct v4l2_subdev_route
93    :header-rows:  0
94    :stub-columns: 0
95    :widths:       1 1 2
96
97    * - __u32
98      - ``sink_pad``
99      - Sink pad number.
100    * - __u32
101      - ``sink_stream``
102      - Sink pad stream number.
103    * - __u32
104      - ``source_pad``
105      - Source pad number.
106    * - __u32
107      - ``source_stream``
108      - Source pad stream number.
109    * - __u32
110      - ``flags``
111      - Route enable/disable flags
112	:ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
113    * - __u32
114      - ``reserved``\ [5]
115      - Reserved for future extensions. Applications and drivers must set
116	the array to zero.
117
118.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
119
120.. _v4l2-subdev-routing-flags:
121
122.. flat-table:: enum v4l2_subdev_routing_flags
123    :header-rows:  0
124    :stub-columns: 0
125    :widths:       3 1 4
126
127    * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
128      - 0x0001
129      - The route is enabled. Set by applications.
130
131Return Value
132============
133
134On success 0 is returned, on error -1 and the ``errno`` variable is set
135appropriately. The generic error codes are described at the
136:ref:`Generic Error Codes <gen-errors>` chapter.
137
138ENOSPC
139   The application provided ``num_routes`` is not big enough to contain
140   all the available routes the subdevice exposes.
141
142EINVAL
143   The sink or source pad identifiers reference a non-existing pad, or reference
144   pads of different types (ie. the sink_pad identifiers refers to a source pad).
145
146E2BIG
147   The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
148   larger than the number of routes the driver can handle.
149