1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: MC 2 .. c:namespace:: MC
3 3
4 .. _media_ioc_g_topology: 4 .. _media_ioc_g_topology:
5 5
6 ************************** 6 **************************
7 ioctl MEDIA_IOC_G_TOPOLOGY 7 ioctl MEDIA_IOC_G_TOPOLOGY
8 ************************** 8 **************************
9 9
10 Name 10 Name
11 ==== 11 ====
12 12
13 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph top 13 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
14 14
15 Synopsis 15 Synopsis
16 ======== 16 ========
17 17
18 .. c:macro:: MEDIA_IOC_G_TOPOLOGY 18 .. c:macro:: MEDIA_IOC_G_TOPOLOGY
19 19
20 ``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, stru 20 ``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
21 21
22 Arguments 22 Arguments
23 ========= 23 =========
24 24
25 ``fd`` 25 ``fd``
26 File descriptor returned by :c:func:`open( 26 File descriptor returned by :c:func:`open()`.
27 27
28 ``argp`` 28 ``argp``
29 Pointer to struct :c:type:`media_v2_topolo 29 Pointer to struct :c:type:`media_v2_topology`.
30 30
31 Description 31 Description
32 =========== 32 ===========
33 33
34 The typical usage of this ioctl is to call it 34 The typical usage of this ioctl is to call it twice. On the first call,
35 the structure defined at struct 35 the structure defined at struct
36 :c:type:`media_v2_topology` should be zeroed. 36 :c:type:`media_v2_topology` should be zeroed. At
37 return, if no errors happen, this ioctl will r 37 return, if no errors happen, this ioctl will return the
38 ``topology_version`` and the total number of e 38 ``topology_version`` and the total number of entities, interfaces, pads
39 and links. 39 and links.
40 40
41 Before the second call, the userspace should a 41 Before the second call, the userspace should allocate arrays to store
42 the graph elements that are desired, putting t 42 the graph elements that are desired, putting the pointers to them at the
43 ptr_entities, ptr_interfaces, ptr_links and/or 43 ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
44 other values untouched. 44 other values untouched.
45 45
46 If the ``topology_version`` remains the same, 46 If the ``topology_version`` remains the same, the ioctl should fill the
47 desired arrays with the media graph elements. 47 desired arrays with the media graph elements.
48 48
49 .. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3c 49 .. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}|
50 50
51 .. c:type:: media_v2_topology 51 .. c:type:: media_v2_topology
52 52
53 .. flat-table:: struct media_v2_topology 53 .. flat-table:: struct media_v2_topology
54 :header-rows: 0 54 :header-rows: 0
55 :stub-columns: 0 55 :stub-columns: 0
56 :widths: 1 2 8 56 :widths: 1 2 8
57 57
58 * - __u64 58 * - __u64
59 - ``topology_version`` 59 - ``topology_version``
60 - Version of the media graph topology. 60 - Version of the media graph topology. When the graph is created,
61 this field starts with zero. Every t 61 this field starts with zero. Every time a graph element is added
62 or removed, this field is incremente 62 or removed, this field is incremented.
63 63
64 * - __u32 64 * - __u32
65 - ``num_entities`` 65 - ``num_entities``
66 - Number of entities in the graph 66 - Number of entities in the graph
67 67
68 * - __u32 68 * - __u32
69 - ``reserved1`` 69 - ``reserved1``
70 - Applications and drivers shall set t 70 - Applications and drivers shall set this to 0.
71 71
72 * - __u64 72 * - __u64
73 - ``ptr_entities`` 73 - ``ptr_entities``
74 - A pointer to a memory area where the 74 - A pointer to a memory area where the entities array will be
75 stored, converted to a 64-bits integ 75 stored, converted to a 64-bits integer. It can be zero. if zero,
76 the ioctl won't store the entities. 76 the ioctl won't store the entities. It will just update
77 ``num_entities`` 77 ``num_entities``
78 78
79 * - __u32 79 * - __u32
80 - ``num_interfaces`` 80 - ``num_interfaces``
81 - Number of interfaces in the graph 81 - Number of interfaces in the graph
82 82
83 * - __u32 83 * - __u32
84 - ``reserved2`` 84 - ``reserved2``
85 - Applications and drivers shall set t 85 - Applications and drivers shall set this to 0.
86 86
87 * - __u64 87 * - __u64
88 - ``ptr_interfaces`` 88 - ``ptr_interfaces``
89 - A pointer to a memory area where the 89 - A pointer to a memory area where the interfaces array will be
90 stored, converted to a 64-bits integ 90 stored, converted to a 64-bits integer. It can be zero. if zero,
91 the ioctl won't store the interfaces 91 the ioctl won't store the interfaces. It will just update
92 ``num_interfaces`` 92 ``num_interfaces``
93 93
94 * - __u32 94 * - __u32
95 - ``num_pads`` 95 - ``num_pads``
96 - Total number of pads in the graph 96 - Total number of pads in the graph
97 97
98 * - __u32 98 * - __u32
99 - ``reserved3`` 99 - ``reserved3``
100 - Applications and drivers shall set t 100 - Applications and drivers shall set this to 0.
101 101
102 * - __u64 102 * - __u64
103 - ``ptr_pads`` 103 - ``ptr_pads``
104 - A pointer to a memory area where the 104 - A pointer to a memory area where the pads array will be stored,
105 converted to a 64-bits integer. It c 105 converted to a 64-bits integer. It can be zero. if zero, the ioctl
106 won't store the pads. It will just u 106 won't store the pads. It will just update ``num_pads``
107 107
108 * - __u32 108 * - __u32
109 - ``num_links`` 109 - ``num_links``
110 - Total number of data and interface l 110 - Total number of data and interface links in the graph
111 111
112 * - __u32 112 * - __u32
113 - ``reserved4`` 113 - ``reserved4``
114 - Applications and drivers shall set t 114 - Applications and drivers shall set this to 0.
115 115
116 * - __u64 116 * - __u64
117 - ``ptr_links`` 117 - ``ptr_links``
118 - A pointer to a memory area where the 118 - A pointer to a memory area where the links array will be stored,
119 converted to a 64-bits integer. It c 119 converted to a 64-bits integer. It can be zero. if zero, the ioctl
120 won't store the links. It will just 120 won't store the links. It will just update ``num_links``
121 121
122 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5c 122 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
123 123
124 .. c:type:: media_v2_entity 124 .. c:type:: media_v2_entity
125 125
126 .. flat-table:: struct media_v2_entity 126 .. flat-table:: struct media_v2_entity
127 :header-rows: 0 127 :header-rows: 0
128 :stub-columns: 0 128 :stub-columns: 0
129 :widths: 1 2 8 129 :widths: 1 2 8
130 130
131 * - __u32 131 * - __u32
132 - ``id`` 132 - ``id``
133 - Unique ID for the entity. Do not exp 133 - Unique ID for the entity. Do not expect that the ID will
134 always be the same for each instance 134 always be the same for each instance of the device. In other words,
135 do not hardcode entity IDs in an app 135 do not hardcode entity IDs in an application.
136 136
137 * - char 137 * - char
138 - ``name``\ [64] 138 - ``name``\ [64]
139 - Entity name as an UTF-8 NULL-termina 139 - Entity name as an UTF-8 NULL-terminated string. This name must be unique
140 within the media topology. 140 within the media topology.
141 141
142 * - __u32 142 * - __u32
143 - ``function`` 143 - ``function``
144 - Entity main function, see :ref:`medi 144 - Entity main function, see :ref:`media-entity-functions` for details.
145 145
146 * - __u32 146 * - __u32
147 - ``flags`` 147 - ``flags``
148 - Entity flags, see :ref:`media-entity 148 - Entity flags, see :ref:`media-entity-flag` for details.
149 Only valid if ``MEDIA_V2_ENTITY_HAS_ 149 Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
150 returns true. The ``media_version`` 150 returns true. The ``media_version`` is defined in struct
151 :c:type:`media_device_info` and can 151 :c:type:`media_device_info` and can be retrieved using
152 :ref:`MEDIA_IOC_DEVICE_INFO`. 152 :ref:`MEDIA_IOC_DEVICE_INFO`.
153 153
154 * - __u32 154 * - __u32
155 - ``reserved``\ [5] 155 - ``reserved``\ [5]
156 - Reserved for future extensions. Driv 156 - Reserved for future extensions. Drivers and applications must set
157 this array to zero. 157 this array to zero.
158 158
159 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5c 159 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
160 160
161 .. c:type:: media_v2_interface 161 .. c:type:: media_v2_interface
162 162
163 .. flat-table:: struct media_v2_interface 163 .. flat-table:: struct media_v2_interface
164 :header-rows: 0 164 :header-rows: 0
165 :stub-columns: 0 165 :stub-columns: 0
166 :widths: 1 2 8 166 :widths: 1 2 8
167 167
168 * - __u32 168 * - __u32
169 - ``id`` 169 - ``id``
170 - Unique ID for the interface. Do not 170 - Unique ID for the interface. Do not expect that the ID will
171 always be the same for each instance 171 always be the same for each instance of the device. In other words,
172 do not hardcode interface IDs in an 172 do not hardcode interface IDs in an application.
173 173
174 * - __u32 174 * - __u32
175 - ``intf_type`` 175 - ``intf_type``
176 - Interface type, see :ref:`media-intf 176 - Interface type, see :ref:`media-intf-type` for details.
177 177
178 * - __u32 178 * - __u32
179 - ``flags`` 179 - ``flags``
180 - Interface flags. Currently unused. 180 - Interface flags. Currently unused.
181 181
182 * - __u32 182 * - __u32
183 - ``reserved``\ [9] 183 - ``reserved``\ [9]
184 - Reserved for future extensions. Driv 184 - Reserved for future extensions. Drivers and applications must set
185 this array to zero. 185 this array to zero.
186 186
187 * - struct media_v2_intf_devnode 187 * - struct media_v2_intf_devnode
188 - ``devnode`` 188 - ``devnode``
189 - Used only for device node interfaces 189 - Used only for device node interfaces. See
190 :c:type:`media_v2_intf_devnode` for 190 :c:type:`media_v2_intf_devnode` for details.
191 191
192 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5c 192 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
193 193
194 .. c:type:: media_v2_intf_devnode 194 .. c:type:: media_v2_intf_devnode
195 195
196 .. flat-table:: struct media_v2_intf_devnode 196 .. flat-table:: struct media_v2_intf_devnode
197 :header-rows: 0 197 :header-rows: 0
198 :stub-columns: 0 198 :stub-columns: 0
199 :widths: 1 2 8 199 :widths: 1 2 8
200 200
201 * - __u32 201 * - __u32
202 - ``major`` 202 - ``major``
203 - Device node major number. 203 - Device node major number.
204 204
205 * - __u32 205 * - __u32
206 - ``minor`` 206 - ``minor``
207 - Device node minor number. 207 - Device node minor number.
208 208
209 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5c 209 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
210 210
211 .. c:type:: media_v2_pad 211 .. c:type:: media_v2_pad
212 212
213 .. flat-table:: struct media_v2_pad 213 .. flat-table:: struct media_v2_pad
214 :header-rows: 0 214 :header-rows: 0
215 :stub-columns: 0 215 :stub-columns: 0
216 :widths: 1 2 8 216 :widths: 1 2 8
217 217
218 * - __u32 218 * - __u32
219 - ``id`` 219 - ``id``
220 - Unique ID for the pad. Do not expect 220 - Unique ID for the pad. Do not expect that the ID will
221 always be the same for each instance 221 always be the same for each instance of the device. In other words,
222 do not hardcode pad IDs in an applic 222 do not hardcode pad IDs in an application.
223 223
224 * - __u32 224 * - __u32
225 - ``entity_id`` 225 - ``entity_id``
226 - Unique ID for the entity where this 226 - Unique ID for the entity where this pad belongs.
227 227
228 * - __u32 228 * - __u32
229 - ``flags`` 229 - ``flags``
230 - Pad flags, see :ref:`media-pad-flag` 230 - Pad flags, see :ref:`media-pad-flag` for more details.
231 231
232 * - __u32 232 * - __u32
233 - ``index`` 233 - ``index``
234 - Pad index, starts at 0. Only valid i 234 - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
235 returns true. The ``media_version`` 235 returns true. The ``media_version`` is defined in struct
236 :c:type:`media_device_info` and can 236 :c:type:`media_device_info` and can be retrieved using
237 :ref:`MEDIA_IOC_DEVICE_INFO`. 237 :ref:`MEDIA_IOC_DEVICE_INFO`.
238 238
239 * - __u32 239 * - __u32
240 - ``reserved``\ [4] 240 - ``reserved``\ [4]
241 - Reserved for future extensions. Driv 241 - Reserved for future extensions. Drivers and applications must set
242 this array to zero. 242 this array to zero.
243 243
244 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5c 244 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
245 245
246 .. c:type:: media_v2_link 246 .. c:type:: media_v2_link
247 247
248 .. flat-table:: struct media_v2_link 248 .. flat-table:: struct media_v2_link
249 :header-rows: 0 249 :header-rows: 0
250 :stub-columns: 0 250 :stub-columns: 0
251 :widths: 1 2 8 251 :widths: 1 2 8
252 252
253 * - __u32 253 * - __u32
254 - ``id`` 254 - ``id``
255 - Unique ID for the link. Do not expec 255 - Unique ID for the link. Do not expect that the ID will
256 always be the same for each instance 256 always be the same for each instance of the device. In other words,
257 do not hardcode link IDs in an appli 257 do not hardcode link IDs in an application.
258 258
259 * - __u32 259 * - __u32
260 - ``source_id`` 260 - ``source_id``
261 - On pad to pad links: unique ID for t 261 - On pad to pad links: unique ID for the source pad.
262 262
263 On interface to entity links: unique 263 On interface to entity links: unique ID for the interface.
264 264
265 * - __u32 265 * - __u32
266 - ``sink_id`` 266 - ``sink_id``
267 - On pad to pad links: unique ID for t 267 - On pad to pad links: unique ID for the sink pad.
268 268
269 On interface to entity links: unique 269 On interface to entity links: unique ID for the entity.
270 270
271 * - __u32 271 * - __u32
272 - ``flags`` 272 - ``flags``
273 - Link flags, see :ref:`media-link-fla 273 - Link flags, see :ref:`media-link-flag` for more details.
274 274
275 * - __u32 275 * - __u32
276 - ``reserved``\ [6] 276 - ``reserved``\ [6]
277 - Reserved for future extensions. Driv 277 - Reserved for future extensions. Drivers and applications must set
278 this array to zero. 278 this array to zero.
279 279
280 Return Value 280 Return Value
281 ============ 281 ============
282 282
283 On success 0 is returned, on error -1 and the 283 On success 0 is returned, on error -1 and the ``errno`` variable is set
284 appropriately. The generic error codes are des 284 appropriately. The generic error codes are described at the
285 :ref:`Generic Error Codes <gen-errors>` chapte 285 :ref:`Generic Error Codes <gen-errors>` chapter.
286 286
287 ENOSPC 287 ENOSPC
288 This is returned when either one or more o 288 This is returned when either one or more of the num_entities,
289 num_interfaces, num_links or num_pads are 289 num_interfaces, num_links or num_pads are non-zero and are
290 smaller than the actual number of elements 290 smaller than the actual number of elements inside the graph. This
291 may happen if the ``topology_version`` cha 291 may happen if the ``topology_version`` changed when compared to the
292 last time this ioctl was called. Userspace 292 last time this ioctl was called. Userspace should usually free the
293 area for the pointers, zero the struct ele 293 area for the pointers, zero the struct elements and call this ioctl
294 again. 294 again.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.