295 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: MC3 4.. _media_ioc_g_topology:5 6**************************7ioctl MEDIA_IOC_G_TOPOLOGY8**************************9 10Name11====12 13MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties14 15Synopsis16========17 18.. c:macro:: MEDIA_IOC_G_TOPOLOGY19 20``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``21 22Arguments23=========24 25``fd``26 File descriptor returned by :c:func:`open()`.27 28``argp``29 Pointer to struct :c:type:`media_v2_topology`.30 31Description32===========33 34The typical usage of this ioctl is to call it twice. On the first call,35the structure defined at struct36:c:type:`media_v2_topology` should be zeroed. At37return, if no errors happen, this ioctl will return the38``topology_version`` and the total number of entities, interfaces, pads39and links.40 41Before the second call, the userspace should allocate arrays to store42the graph elements that are desired, putting the pointers to them at the43ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the44other values untouched.45 46If the ``topology_version`` remains the same, the ioctl should fill the47desired arrays with the media graph elements.48 49.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}|50 51.. c:type:: media_v2_topology52 53.. flat-table:: struct media_v2_topology54 :header-rows: 055 :stub-columns: 056 :widths: 1 2 857 58 * - __u6459 - ``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 added62 or removed, this field is incremented.63 64 * - __u3265 - ``num_entities``66 - Number of entities in the graph67 68 * - __u3269 - ``reserved1``70 - Applications and drivers shall set this to 0.71 72 * - __u6473 - ``ptr_entities``74 - A pointer to a memory area where the entities array will be75 stored, converted to a 64-bits integer. It can be zero. if zero,76 the ioctl won't store the entities. It will just update77 ``num_entities``78 79 * - __u3280 - ``num_interfaces``81 - Number of interfaces in the graph82 83 * - __u3284 - ``reserved2``85 - Applications and drivers shall set this to 0.86 87 * - __u6488 - ``ptr_interfaces``89 - A pointer to a memory area where the interfaces array will be90 stored, converted to a 64-bits integer. It can be zero. if zero,91 the ioctl won't store the interfaces. It will just update92 ``num_interfaces``93 94 * - __u3295 - ``num_pads``96 - Total number of pads in the graph97 98 * - __u3299 - ``reserved3``100 - Applications and drivers shall set this to 0.101 102 * - __u64103 - ``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 ioctl106 won't store the pads. It will just update ``num_pads``107 108 * - __u32109 - ``num_links``110 - Total number of data and interface links in the graph111 112 * - __u32113 - ``reserved4``114 - Applications and drivers shall set this to 0.115 116 * - __u64117 - ``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 ioctl120 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_entity125 126.. flat-table:: struct media_v2_entity127 :header-rows: 0128 :stub-columns: 0129 :widths: 1 2 8130 131 * - __u32132 - ``id``133 - Unique ID for the entity. Do not expect that the ID will134 always be the same for each instance of the device. In other words,135 do not hardcode entity IDs in an application.136 137 * - char138 - ``name``\ [64]139 - Entity name as an UTF-8 NULL-terminated string. This name must be unique140 within the media topology.141 142 * - __u32143 - ``function``144 - Entity main function, see :ref:`media-entity-functions` for details.145 146 * - __u32147 - ``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 struct151 :c:type:`media_device_info` and can be retrieved using152 :ref:`MEDIA_IOC_DEVICE_INFO`.153 154 * - __u32155 - ``reserved``\ [5]156 - Reserved for future extensions. Drivers and applications must set157 this array to zero.158 159.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|160 161.. c:type:: media_v2_interface162 163.. flat-table:: struct media_v2_interface164 :header-rows: 0165 :stub-columns: 0166 :widths: 1 2 8167 168 * - __u32169 - ``id``170 - Unique ID for the interface. Do not expect that the ID will171 always be the same for each instance of the device. In other words,172 do not hardcode interface IDs in an application.173 174 * - __u32175 - ``intf_type``176 - Interface type, see :ref:`media-intf-type` for details.177 178 * - __u32179 - ``flags``180 - Interface flags. Currently unused.181 182 * - __u32183 - ``reserved``\ [9]184 - Reserved for future extensions. Drivers and applications must set185 this array to zero.186 187 * - struct media_v2_intf_devnode188 - ``devnode``189 - Used only for device node interfaces. See190 :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_devnode195 196.. flat-table:: struct media_v2_intf_devnode197 :header-rows: 0198 :stub-columns: 0199 :widths: 1 2 8200 201 * - __u32202 - ``major``203 - Device node major number.204 205 * - __u32206 - ``minor``207 - Device node minor number.208 209.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|210 211.. c:type:: media_v2_pad212 213.. flat-table:: struct media_v2_pad214 :header-rows: 0215 :stub-columns: 0216 :widths: 1 2 8217 218 * - __u32219 - ``id``220 - Unique ID for the pad. Do not expect that the ID will221 always be the same for each instance of the device. In other words,222 do not hardcode pad IDs in an application.223 224 * - __u32225 - ``entity_id``226 - Unique ID for the entity where this pad belongs.227 228 * - __u32229 - ``flags``230 - Pad flags, see :ref:`media-pad-flag` for more details.231 232 * - __u32233 - ``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 struct236 :c:type:`media_device_info` and can be retrieved using237 :ref:`MEDIA_IOC_DEVICE_INFO`.238 239 * - __u32240 - ``reserved``\ [4]241 - Reserved for future extensions. Drivers and applications must set242 this array to zero.243 244.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|245 246.. c:type:: media_v2_link247 248.. flat-table:: struct media_v2_link249 :header-rows: 0250 :stub-columns: 0251 :widths: 1 2 8252 253 * - __u32254 - ``id``255 - Unique ID for the link. Do not expect that the ID will256 always be the same for each instance of the device. In other words,257 do not hardcode link IDs in an application.258 259 * - __u32260 - ``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 * - __u32266 - ``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 * - __u32272 - ``flags``273 - Link flags, see :ref:`media-link-flag` for more details.274 275 * - __u32276 - ``reserved``\ [6]277 - Reserved for future extensions. Drivers and applications must set278 this array to zero.279 280Return Value281============282 283On success 0 is returned, on error -1 and the ``errno`` variable is set284appropriately. The generic error codes are described at the285:ref:`Generic Error Codes <gen-errors>` chapter.286 287ENOSPC288 This is returned when either one or more of the num_entities,289 num_interfaces, num_links or num_pads are non-zero and are290 smaller than the actual number of elements inside the graph. This291 may happen if the ``topology_version`` changed when compared to the292 last time this ioctl was called. Userspace should usually free the293 area for the pointers, zero the struct elements and call this ioctl294 again.295