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