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