0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_ioc_g_topology:
0005
0006 **************************
0007 ioctl MEDIA_IOC_G_TOPOLOGY
0008 **************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_IOC_G_TOPOLOGY
0019
0020 ``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`media_v2_topology`.
0030
0031 Description
0032 ===========
0033
0034 The typical usage of this ioctl is to call it twice. On the first call,
0035 the structure defined at struct
0036 :c:type:`media_v2_topology` should be zeroed. At
0037 return, if no errors happen, this ioctl will return the
0038 ``topology_version`` and the total number of entities, interfaces, pads
0039 and links.
0040
0041 Before the second call, the userspace should allocate arrays to store
0042 the graph elements that are desired, putting the pointers to them at the
0043 ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
0044 other values untouched.
0045
0046 If the ``topology_version`` remains the same, the ioctl should fill the
0047 desired arrays with the media graph elements.
0048
0049 .. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}|
0050
0051 .. c:type:: media_v2_topology
0052
0053 .. flat-table:: struct media_v2_topology
0054 :header-rows: 0
0055 :stub-columns: 0
0056 :widths: 1 2 8
0057
0058 * - __u64
0059 - ``topology_version``
0060 - Version of the media graph topology. When the graph is created,
0061 this field starts with zero. Every time a graph element is added
0062 or removed, this field is incremented.
0063
0064 * - __u32
0065 - ``num_entities``
0066 - Number of entities in the graph
0067
0068 * - __u32
0069 - ``reserved1``
0070 - Applications and drivers shall set this to 0.
0071
0072 * - __u64
0073 - ``ptr_entities``
0074 - A pointer to a memory area where the entities array will be
0075 stored, converted to a 64-bits integer. It can be zero. if zero,
0076 the ioctl won't store the entities. It will just update
0077 ``num_entities``
0078
0079 * - __u32
0080 - ``num_interfaces``
0081 - Number of interfaces in the graph
0082
0083 * - __u32
0084 - ``reserved2``
0085 - Applications and drivers shall set this to 0.
0086
0087 * - __u64
0088 - ``ptr_interfaces``
0089 - A pointer to a memory area where the interfaces array will be
0090 stored, converted to a 64-bits integer. It can be zero. if zero,
0091 the ioctl won't store the interfaces. It will just update
0092 ``num_interfaces``
0093
0094 * - __u32
0095 - ``num_pads``
0096 - Total number of pads in the graph
0097
0098 * - __u32
0099 - ``reserved3``
0100 - Applications and drivers shall set this to 0.
0101
0102 * - __u64
0103 - ``ptr_pads``
0104 - A pointer to a memory area where the pads array will be stored,
0105 converted to a 64-bits integer. It can be zero. if zero, the ioctl
0106 won't store the pads. It will just update ``num_pads``
0107
0108 * - __u32
0109 - ``num_links``
0110 - Total number of data and interface links in the graph
0111
0112 * - __u32
0113 - ``reserved4``
0114 - Applications and drivers shall set this to 0.
0115
0116 * - __u64
0117 - ``ptr_links``
0118 - A pointer to a memory area where the links array will be stored,
0119 converted to a 64-bits integer. It can be zero. if zero, the ioctl
0120 won't store the links. It will just update ``num_links``
0121
0122 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
0123
0124 .. c:type:: media_v2_entity
0125
0126 .. flat-table:: struct media_v2_entity
0127 :header-rows: 0
0128 :stub-columns: 0
0129 :widths: 1 2 8
0130
0131 * - __u32
0132 - ``id``
0133 - Unique ID for the entity. Do not expect that the ID will
0134 always be the same for each instance of the device. In other words,
0135 do not hardcode entity IDs in an application.
0136
0137 * - char
0138 - ``name``\ [64]
0139 - Entity name as an UTF-8 NULL-terminated string. This name must be unique
0140 within the media topology.
0141
0142 * - __u32
0143 - ``function``
0144 - Entity main function, see :ref:`media-entity-functions` for details.
0145
0146 * - __u32
0147 - ``flags``
0148 - Entity flags, see :ref:`media-entity-flag` for details.
0149 Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
0150 returns true. The ``media_version`` is defined in struct
0151 :c:type:`media_device_info` and can be retrieved using
0152 :ref:`MEDIA_IOC_DEVICE_INFO`.
0153
0154 * - __u32
0155 - ``reserved``\ [5]
0156 - Reserved for future extensions. Drivers and applications must set
0157 this array to zero.
0158
0159 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
0160
0161 .. c:type:: media_v2_interface
0162
0163 .. flat-table:: struct media_v2_interface
0164 :header-rows: 0
0165 :stub-columns: 0
0166 :widths: 1 2 8
0167
0168 * - __u32
0169 - ``id``
0170 - Unique ID for the interface. Do not expect that the ID will
0171 always be the same for each instance of the device. In other words,
0172 do not hardcode interface IDs in an application.
0173
0174 * - __u32
0175 - ``intf_type``
0176 - Interface type, see :ref:`media-intf-type` for details.
0177
0178 * - __u32
0179 - ``flags``
0180 - Interface flags. Currently unused.
0181
0182 * - __u32
0183 - ``reserved``\ [9]
0184 - Reserved for future extensions. Drivers and applications must set
0185 this array to zero.
0186
0187 * - struct media_v2_intf_devnode
0188 - ``devnode``
0189 - Used only for device node interfaces. See
0190 :c:type:`media_v2_intf_devnode` for details.
0191
0192 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
0193
0194 .. c:type:: media_v2_intf_devnode
0195
0196 .. flat-table:: struct media_v2_intf_devnode
0197 :header-rows: 0
0198 :stub-columns: 0
0199 :widths: 1 2 8
0200
0201 * - __u32
0202 - ``major``
0203 - Device node major number.
0204
0205 * - __u32
0206 - ``minor``
0207 - Device node minor number.
0208
0209 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
0210
0211 .. c:type:: media_v2_pad
0212
0213 .. flat-table:: struct media_v2_pad
0214 :header-rows: 0
0215 :stub-columns: 0
0216 :widths: 1 2 8
0217
0218 * - __u32
0219 - ``id``
0220 - Unique ID for the pad. Do not expect that the ID will
0221 always be the same for each instance of the device. In other words,
0222 do not hardcode pad IDs in an application.
0223
0224 * - __u32
0225 - ``entity_id``
0226 - Unique ID for the entity where this pad belongs.
0227
0228 * - __u32
0229 - ``flags``
0230 - Pad flags, see :ref:`media-pad-flag` for more details.
0231
0232 * - __u32
0233 - ``index``
0234 - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
0235 returns true. The ``media_version`` is defined in struct
0236 :c:type:`media_device_info` and can be retrieved using
0237 :ref:`MEDIA_IOC_DEVICE_INFO`.
0238
0239 * - __u32
0240 - ``reserved``\ [4]
0241 - Reserved for future extensions. Drivers and applications must set
0242 this array to zero.
0243
0244 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}|
0245
0246 .. c:type:: media_v2_link
0247
0248 .. flat-table:: struct media_v2_link
0249 :header-rows: 0
0250 :stub-columns: 0
0251 :widths: 1 2 8
0252
0253 * - __u32
0254 - ``id``
0255 - Unique ID for the link. Do not expect that the ID will
0256 always be the same for each instance of the device. In other words,
0257 do not hardcode link IDs in an application.
0258
0259 * - __u32
0260 - ``source_id``
0261 - On pad to pad links: unique ID for the source pad.
0262
0263 On interface to entity links: unique ID for the interface.
0264
0265 * - __u32
0266 - ``sink_id``
0267 - On pad to pad links: unique ID for the sink pad.
0268
0269 On interface to entity links: unique ID for the entity.
0270
0271 * - __u32
0272 - ``flags``
0273 - Link flags, see :ref:`media-link-flag` for more details.
0274
0275 * - __u32
0276 - ``reserved``\ [6]
0277 - Reserved for future extensions. Drivers and applications must set
0278 this array to zero.
0279
0280 Return Value
0281 ============
0282
0283 On success 0 is returned, on error -1 and the ``errno`` variable is set
0284 appropriately. The generic error codes are described at the
0285 :ref:`Generic Error Codes <gen-errors>` chapter.
0286
0287 ENOSPC
0288 This is returned when either one or more of the num_entities,
0289 num_interfaces, num_links or num_pads are non-zero and are
0290 smaller than the actual number of elements inside the graph. This
0291 may happen if the ``topology_version`` changed when compared to the
0292 last time this ioctl was called. Userspace should usually free the
0293 area for the pointers, zero the struct elements and call this ioctl
0294 again.
