Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
d2c68150 | 3 | .. _media_ioc_g_topology: |
5377d91f MH |
4 | |
5 | ************************** | |
6 | ioctl MEDIA_IOC_G_TOPOLOGY | |
7 | ************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
5ccbb182 MCC |
18 | .. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) |
19 | :name: MEDIA_IOC_G_TOPOLOGY | |
5377d91f | 20 | |
586027ce | 21 | |
15e7d615 | 22 | Arguments |
5377d91f MH |
23 | ========= |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <media-func-open>`. | |
27 | ||
5377d91f MH |
28 | ``argp`` |
29 | ||
30 | ||
15e7d615 | 31 | Description |
5377d91f MH |
32 | =========== |
33 | ||
34 | The typical usage of this ioctl is to call it twice. On the first call, | |
35 | the structure defined at struct | |
e8be7e97 | 36 | :c:type:`media_v2_topology` should be zeroed. At |
5377d91f MH |
37 | return, if no errors happen, this ioctl will return the |
38 | ``topology_version`` and the total number of entities, interfaces, pads | |
39 | and links. | |
40 | ||
41 | Before the second call, the userspace should allocate arrays to store | |
42 | the graph elements that are desired, putting the pointers to them at the | |
43 | ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the | |
44 | other values untouched. | |
45 | ||
46 | If the ``topology_version`` remains the same, the ioctl should fill the | |
47 | desired arrays with the media graph elements. | |
48 | ||
fa92b04d | 49 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 50 | |
e8be7e97 | 51 | .. c:type:: media_v2_topology |
5377d91f MH |
52 | |
53 | .. flat-table:: struct media_v2_topology | |
54 | :header-rows: 0 | |
55 | :stub-columns: 0 | |
8926814e | 56 | :widths: 1 2 8 |
5377d91f MH |
57 | |
58 | ||
59 | - .. row 1 | |
60 | ||
61 | - __u64 | |
62 | ||
63 | - ``topology_version`` | |
64 | ||
5377d91f | 65 | - Version of the media graph topology. When the graph is created, |
0579e6e3 MCC |
66 | this field starts with zero. Every time a graph element is added |
67 | or removed, this field is incremented. | |
5377d91f MH |
68 | |
69 | - .. row 2 | |
70 | ||
71 | - __u64 | |
72 | ||
73 | - ``num_entities`` | |
74 | ||
5377d91f MH |
75 | - Number of entities in the graph |
76 | ||
77 | - .. row 3 | |
78 | ||
79 | - __u64 | |
80 | ||
81 | - ``ptr_entities`` | |
82 | ||
5377d91f | 83 | - A pointer to a memory area where the entities array will be |
0579e6e3 MCC |
84 | stored, converted to a 64-bits integer. It can be zero. if zero, |
85 | the ioctl won't store the entities. It will just update | |
86 | ``num_entities`` | |
5377d91f MH |
87 | |
88 | - .. row 4 | |
89 | ||
90 | - __u64 | |
91 | ||
92 | - ``num_interfaces`` | |
93 | ||
5377d91f MH |
94 | - Number of interfaces in the graph |
95 | ||
96 | - .. row 5 | |
97 | ||
98 | - __u64 | |
99 | ||
100 | - ``ptr_interfaces`` | |
101 | ||
5377d91f | 102 | - A pointer to a memory area where the interfaces array will be |
0579e6e3 MCC |
103 | stored, converted to a 64-bits integer. It can be zero. if zero, |
104 | the ioctl won't store the interfaces. It will just update | |
105 | ``num_interfaces`` | |
5377d91f MH |
106 | |
107 | - .. row 6 | |
108 | ||
109 | - __u64 | |
110 | ||
111 | - ``num_pads`` | |
112 | ||
5377d91f MH |
113 | - Total number of pads in the graph |
114 | ||
115 | - .. row 7 | |
116 | ||
117 | - __u64 | |
118 | ||
119 | - ``ptr_pads`` | |
120 | ||
5377d91f | 121 | - A pointer to a memory area where the pads array will be stored, |
0579e6e3 MCC |
122 | converted to a 64-bits integer. It can be zero. if zero, the ioctl |
123 | won't store the pads. It will just update ``num_pads`` | |
5377d91f MH |
124 | |
125 | - .. row 8 | |
126 | ||
127 | - __u64 | |
128 | ||
129 | - ``num_links`` | |
130 | ||
5377d91f MH |
131 | - Total number of data and interface links in the graph |
132 | ||
133 | - .. row 9 | |
134 | ||
135 | - __u64 | |
136 | ||
137 | - ``ptr_links`` | |
138 | ||
5377d91f | 139 | - A pointer to a memory area where the links array will be stored, |
0579e6e3 MCC |
140 | converted to a 64-bits integer. It can be zero. if zero, the ioctl |
141 | won't store the links. It will just update ``num_links`` | |
5377d91f MH |
142 | |
143 | ||
fa92b04d | 144 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 145 | |
e8be7e97 | 146 | .. c:type:: media_v2_entity |
5377d91f MH |
147 | |
148 | .. flat-table:: struct media_v2_entity | |
149 | :header-rows: 0 | |
150 | :stub-columns: 0 | |
8926814e | 151 | :widths: 1 2 8 |
5377d91f MH |
152 | |
153 | ||
154 | - .. row 1 | |
155 | ||
156 | - __u32 | |
157 | ||
158 | - ``id`` | |
159 | ||
5377d91f MH |
160 | - Unique ID for the entity. |
161 | ||
162 | - .. row 2 | |
163 | ||
164 | - char | |
165 | ||
8968da9b | 166 | - ``name``\ [64] |
5377d91f | 167 | |
5377d91f MH |
168 | - Entity name as an UTF-8 NULL-terminated string. |
169 | ||
170 | - .. row 3 | |
171 | ||
172 | - __u32 | |
173 | ||
174 | - ``function`` | |
175 | ||
5377d91f MH |
176 | - Entity main function, see :ref:`media-entity-type` for details. |
177 | ||
178 | - .. row 4 | |
179 | ||
180 | - __u32 | |
181 | ||
8968da9b | 182 | - ``reserved``\ [12] |
5377d91f MH |
183 | |
184 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 185 | this array to zero. |
5377d91f MH |
186 | |
187 | ||
fa92b04d | 188 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 189 | |
e8be7e97 | 190 | .. c:type:: media_v2_interface |
5377d91f MH |
191 | |
192 | .. flat-table:: struct media_v2_interface | |
193 | :header-rows: 0 | |
194 | :stub-columns: 0 | |
8926814e | 195 | :widths: 1 2 8 |
5377d91f MH |
196 | |
197 | - .. row 1 | |
198 | ||
199 | - __u32 | |
200 | ||
201 | - ``id`` | |
202 | ||
5377d91f MH |
203 | - Unique ID for the interface. |
204 | ||
205 | - .. row 2 | |
206 | ||
207 | - __u32 | |
208 | ||
209 | - ``intf_type`` | |
210 | ||
5377d91f MH |
211 | - Interface type, see :ref:`media-intf-type` for details. |
212 | ||
213 | - .. row 3 | |
214 | ||
215 | - __u32 | |
216 | ||
217 | - ``flags`` | |
218 | ||
5377d91f MH |
219 | - Interface flags. Currently unused. |
220 | ||
221 | - .. row 4 | |
222 | ||
223 | - __u32 | |
224 | ||
8968da9b | 225 | - ``reserved``\ [9] |
5377d91f | 226 | |
5377d91f | 227 | - Reserved for future extensions. Drivers and applications must set |
0579e6e3 | 228 | this array to zero. |
5377d91f MH |
229 | |
230 | - .. row 5 | |
231 | ||
232 | - struct media_v2_intf_devnode | |
233 | ||
234 | - ``devnode`` | |
235 | ||
5377d91f | 236 | - Used only for device node interfaces. See |
16f8306b | 237 | :c:type:`media_v2_intf_devnode` for details.. |
5377d91f MH |
238 | |
239 | ||
fa92b04d | 240 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 241 | |
e8be7e97 | 242 | .. c:type:: media_v2_intf_devnode |
5377d91f MH |
243 | |
244 | .. flat-table:: struct media_v2_interface | |
245 | :header-rows: 0 | |
246 | :stub-columns: 0 | |
8926814e | 247 | :widths: 1 2 8 |
5377d91f MH |
248 | |
249 | ||
250 | - .. row 1 | |
251 | ||
252 | - __u32 | |
253 | ||
254 | - ``major`` | |
255 | ||
5377d91f MH |
256 | - Device node major number. |
257 | ||
258 | - .. row 2 | |
259 | ||
260 | - __u32 | |
261 | ||
262 | - ``minor`` | |
263 | ||
5377d91f MH |
264 | - Device node minor number. |
265 | ||
266 | ||
fa92b04d | 267 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 268 | |
e8be7e97 | 269 | .. c:type:: media_v2_pad |
5377d91f MH |
270 | |
271 | .. flat-table:: struct media_v2_pad | |
272 | :header-rows: 0 | |
273 | :stub-columns: 0 | |
8926814e | 274 | :widths: 1 2 8 |
5377d91f MH |
275 | |
276 | ||
277 | - .. row 1 | |
278 | ||
279 | - __u32 | |
280 | ||
281 | - ``id`` | |
282 | ||
5377d91f MH |
283 | - Unique ID for the pad. |
284 | ||
285 | - .. row 2 | |
286 | ||
287 | - __u32 | |
288 | ||
289 | - ``entity_id`` | |
290 | ||
5377d91f MH |
291 | - Unique ID for the entity where this pad belongs. |
292 | ||
293 | - .. row 3 | |
294 | ||
295 | - __u32 | |
296 | ||
297 | - ``flags`` | |
298 | ||
5377d91f MH |
299 | - Pad flags, see :ref:`media-pad-flag` for more details. |
300 | ||
301 | - .. row 4 | |
302 | ||
303 | - __u32 | |
304 | ||
8968da9b | 305 | - ``reserved``\ [9] |
5377d91f | 306 | |
5377d91f | 307 | - Reserved for future extensions. Drivers and applications must set |
0579e6e3 | 308 | this array to zero. |
5377d91f MH |
309 | |
310 | ||
fa92b04d | 311 | .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| |
5377d91f | 312 | |
e8be7e97 | 313 | .. c:type:: media_v2_link |
5377d91f MH |
314 | |
315 | .. flat-table:: struct media_v2_pad | |
316 | :header-rows: 0 | |
317 | :stub-columns: 0 | |
8926814e | 318 | :widths: 1 2 8 |
5377d91f MH |
319 | |
320 | ||
321 | - .. row 1 | |
322 | ||
323 | - __u32 | |
324 | ||
325 | - ``id`` | |
326 | ||
5377d91f MH |
327 | - Unique ID for the pad. |
328 | ||
329 | - .. row 2 | |
330 | ||
331 | - __u32 | |
332 | ||
333 | - ``source_id`` | |
334 | ||
5377d91f MH |
335 | - On pad to pad links: unique ID for the source pad. |
336 | ||
0579e6e3 | 337 | On interface to entity links: unique ID for the interface. |
5377d91f MH |
338 | |
339 | - .. row 3 | |
340 | ||
341 | - __u32 | |
342 | ||
343 | - ``sink_id`` | |
344 | ||
5377d91f MH |
345 | - On pad to pad links: unique ID for the sink pad. |
346 | ||
0579e6e3 | 347 | On interface to entity links: unique ID for the entity. |
5377d91f MH |
348 | |
349 | - .. row 4 | |
350 | ||
351 | - __u32 | |
352 | ||
353 | - ``flags`` | |
354 | ||
5377d91f MH |
355 | - Link flags, see :ref:`media-link-flag` for more details. |
356 | ||
357 | - .. row 5 | |
358 | ||
359 | - __u32 | |
360 | ||
8968da9b | 361 | - ``reserved``\ [5] |
5377d91f | 362 | |
5377d91f | 363 | - Reserved for future extensions. Drivers and applications must set |
0579e6e3 | 364 | this array to zero. |
5377d91f MH |
365 | |
366 | ||
15e7d615 | 367 | Return Value |
5377d91f MH |
368 | ============ |
369 | ||
370 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
371 | appropriately. The generic error codes are described at the | |
372 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
373 | ||
374 | ENOSPC | |
375 | This is returned when either one or more of the num_entities, | |
376 | num_interfaces, num_links or num_pads are non-zero and are | |
377 | smaller than the actual number of elements inside the graph. This | |
378 | may happen if the ``topology_version`` changed when compared to the | |
379 | last time this ioctl was called. Userspace should usually free the | |
380 | area for the pointers, zero the struct elements and call this ioctl | |
381 | again. |