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
61.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
62
63.. c:type:: v4l2_subdev_routing
64
65.. flat-table:: struct v4l2_subdev_routing
66    :header-rows:  0
67    :stub-columns: 0
68    :widths:       1 1 2
69
70    * - __u32
71      - ``which``
72      - Format to modified, from enum
73        :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
74    * - struct :c:type:`v4l2_subdev_route`
75      - ``routes[]``
76      - Array of struct :c:type:`v4l2_subdev_route` entries
77    * - __u32
78      - ``num_routes``
79      - Number of entries of the routes array
80    * - __u32
81      - ``reserved``\ [5]
82      - Reserved for future extensions. Applications and drivers must set
83	the array to zero.
84
85.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
86
87.. c:type:: v4l2_subdev_route
88
89.. flat-table:: struct v4l2_subdev_route
90    :header-rows:  0
91    :stub-columns: 0
92    :widths:       1 1 2
93
94    * - __u32
95      - ``sink_pad``
96      - Sink pad number.
97    * - __u32
98      - ``sink_stream``
99      - Sink pad stream number.
100    * - __u32
101      - ``source_pad``
102      - Source pad number.
103    * - __u32
104      - ``source_stream``
105      - Source pad stream number.
106    * - __u32
107      - ``flags``
108      - Route enable/disable flags
109	:ref:`v4l2_subdev_routing_flags <v4l2-subdev-routing-flags>`.
110    * - __u32
111      - ``reserved``\ [5]
112      - Reserved for future extensions. Applications and drivers must set
113	the array to zero.
114
115.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
116
117.. _v4l2-subdev-routing-flags:
118
119.. flat-table:: enum v4l2_subdev_routing_flags
120    :header-rows:  0
121    :stub-columns: 0
122    :widths:       3 1 4
123
124    * - V4L2_SUBDEV_ROUTE_FL_ACTIVE
125      - 0
126      - The route is enabled. Set by applications.
127
128Return Value
129============
130
131On success 0 is returned, on error -1 and the ``errno`` variable is set
132appropriately. The generic error codes are described at the
133:ref:`Generic Error Codes <gen-errors>` chapter.
134
135ENOSPC
136   The application provided ``num_routes`` is not big enough to contain
137   all the available routes the subdevice exposes.
138
139EINVAL
140   The sink or source pad identifiers reference a non-existing pad, or reference
141   pads of different types (ie. the sink_pad identifiers refers to a source pad)
142   or the sink or source stream identifiers reference a non-existing stream on
143   the sink or source pad.
144
145E2BIG
146   The application provided ``num_routes`` for ``VIDIOC_SUBDEV_S_ROUTING`` is
147   larger than the number of routes the driver can handle.
148