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