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