1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: MC 3 4.. _media_ioc_g_topology: 5 6************************** 7ioctl MEDIA_IOC_G_TOPOLOGY 8************************** 9 10Name 11==== 12 13MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties 14 15Synopsis 16======== 17 18.. c:macro:: MEDIA_IOC_G_TOPOLOGY 19 20``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)`` 21 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :c:func:`open()`. 27 28``argp`` 29 Pointer to struct :c:type:`media_v2_topology`. 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.3cm}| 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.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| 123 124.. c:type:: media_v2_entity 125 126.. flat-table:: struct media_v2_entity 127 :header-rows: 0 128 :stub-columns: 0 129 :widths: 1 2 8 130 131 * - __u32 132 - ``id`` 133 - Unique ID for the entity. Do not expect that the ID will 134 always be the same for each instance of the device. In other words, 135 do not hardcode entity IDs in an application. 136 137 * - char 138 - ``name``\ [64] 139 - Entity name as an UTF-8 NULL-terminated string. This name must be unique 140 within the media topology. 141 142 * - __u32 143 - ``function`` 144 - Entity main function, see :ref:`media-entity-functions` for details. 145 146 * - __u32 147 - ``flags`` 148 - Entity flags, see :ref:`media-entity-flag` for details. 149 Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)`` 150 returns true. The ``media_version`` is defined in struct 151 :c:type:`media_device_info` and can be retrieved using 152 :ref:`MEDIA_IOC_DEVICE_INFO`. 153 154 * - __u32 155 - ``reserved``\ [5] 156 - Reserved for future extensions. Drivers and applications must set 157 this array to zero. 158 159.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| 160 161.. c:type:: media_v2_interface 162 163.. flat-table:: struct media_v2_interface 164 :header-rows: 0 165 :stub-columns: 0 166 :widths: 1 2 8 167 168 * - __u32 169 - ``id`` 170 - Unique ID for the interface. Do not expect that the ID will 171 always be the same for each instance of the device. In other words, 172 do not hardcode interface IDs in an application. 173 174 * - __u32 175 - ``intf_type`` 176 - Interface type, see :ref:`media-intf-type` for details. 177 178 * - __u32 179 - ``flags`` 180 - Interface flags. Currently unused. 181 182 * - __u32 183 - ``reserved``\ [9] 184 - Reserved for future extensions. Drivers and applications must set 185 this array to zero. 186 187 * - struct media_v2_intf_devnode 188 - ``devnode`` 189 - Used only for device node interfaces. See 190 :c:type:`media_v2_intf_devnode` for details. 191 192.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| 193 194.. c:type:: media_v2_intf_devnode 195 196.. flat-table:: struct media_v2_intf_devnode 197 :header-rows: 0 198 :stub-columns: 0 199 :widths: 1 2 8 200 201 * - __u32 202 - ``major`` 203 - Device node major number. 204 205 * - __u32 206 - ``minor`` 207 - Device node minor number. 208 209.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| 210 211.. c:type:: media_v2_pad 212 213.. flat-table:: struct media_v2_pad 214 :header-rows: 0 215 :stub-columns: 0 216 :widths: 1 2 8 217 218 * - __u32 219 - ``id`` 220 - Unique ID for the pad. Do not expect that the ID will 221 always be the same for each instance of the device. In other words, 222 do not hardcode pad IDs in an application. 223 224 * - __u32 225 - ``entity_id`` 226 - Unique ID for the entity where this pad belongs. 227 228 * - __u32 229 - ``flags`` 230 - Pad flags, see :ref:`media-pad-flag` for more details. 231 232 * - __u32 233 - ``index`` 234 - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)`` 235 returns true. The ``media_version`` is defined in struct 236 :c:type:`media_device_info` and can be retrieved using 237 :ref:`MEDIA_IOC_DEVICE_INFO`. 238 239 * - __u32 240 - ``reserved``\ [4] 241 - Reserved for future extensions. Drivers and applications must set 242 this array to zero. 243 244.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| 245 246.. c:type:: media_v2_link 247 248.. flat-table:: struct media_v2_link 249 :header-rows: 0 250 :stub-columns: 0 251 :widths: 1 2 8 252 253 * - __u32 254 - ``id`` 255 - Unique ID for the link. Do not expect that the ID will 256 always be the same for each instance of the device. In other words, 257 do not hardcode link IDs in an application. 258 259 * - __u32 260 - ``source_id`` 261 - On pad to pad links: unique ID for the source pad. 262 263 On interface to entity links: unique ID for the interface. 264 265 * - __u32 266 - ``sink_id`` 267 - On pad to pad links: unique ID for the sink pad. 268 269 On interface to entity links: unique ID for the entity. 270 271 * - __u32 272 - ``flags`` 273 - Link flags, see :ref:`media-link-flag` for more details. 274 275 * - __u32 276 - ``reserved``\ [6] 277 - Reserved for future extensions. Drivers and applications must set 278 this array to zero. 279 280Return Value 281============ 282 283On success 0 is returned, on error -1 and the ``errno`` variable is set 284appropriately. The generic error codes are described at the 285:ref:`Generic Error Codes <gen-errors>` chapter. 286 287ENOSPC 288 This is returned when either one or more of the num_entities, 289 num_interfaces, num_links or num_pads are non-zero and are 290 smaller than the actual number of elements inside the graph. This 291 may happen if the ``topology_version`` changed when compared to the 292 last time this ioctl was called. Userspace should usually free the 293 area for the pointers, zero the struct elements and call this ioctl 294 again. 295