| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: MC |
| 3 |
|
| 4 |
.. _media_ioc_g_topology: |
| 5 |
|
| 6 |
************************** |
| 7 |
ioctl MEDIA_IOC_G_TOPOLOGY |
| 8 |
************************** |
| 9 |
|
| 10 |
Name |
| 11 |
==== |
| 12 |
|
| 13 |
MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties |
| 14 |
|
| 15 |
Synopsis |
| 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 |
|
| 22 |
Arguments |
| 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 |
|
| 31 |
Description |
| 32 |
=========== |
| 33 |
|
| 34 |
The typical usage of this ioctl is to call it twice. On the first call, |
| 35 |
the structure defined at struct |
| 36 |
:c:type:`media_v2_topology` should be zeroed. At |
| 37 |
return, if no errors happen, this ioctl will return the |
| 38 |
``topology_version`` and the total number of entities, interfaces, pads |
| 39 |
and links. |
| 40 |
|
| 41 |
Before the second call, the userspace should allocate arrays to store |
| 42 |
the graph elements that are desired, putting the pointers to them at the |
| 43 |
ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the |
| 44 |
other values untouched. |
| 45 |
|
| 46 |
If the ``topology_version`` remains the same, the ioctl should fill the |
| 47 |
desired 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 |
|
| 280 |
Return Value |
| 281 |
============ |
| 282 |
|
| 283 |
On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 284 |
appropriately. The generic error codes are described at the |
| 285 |
:ref:`Generic Error Codes <gen-errors>` chapter. |
| 286 |
|
| 287 |
ENOSPC |
| 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. |