1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _media_ioc_g_topology:
4
5**************************
6ioctl MEDIA_IOC_G_TOPOLOGY
7**************************
8
9Name
10====
11
12MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
13
14
15Synopsis
16========
17
18.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp )
19    :name: MEDIA_IOC_G_TOPOLOGY
20
21
22Arguments
23=========
24
25``fd``
26    File descriptor returned by :ref:`open() <media-func-open>`.
27
28``argp``
29    Pointer to struct :c:type:`media_v2_topology`.
30
31
32Description
33===========
34
35The typical usage of this ioctl is to call it twice. On the first call,
36the structure defined at struct
37:c:type:`media_v2_topology` should be zeroed. At
38return, if no errors happen, this ioctl will return the
39``topology_version`` and the total number of entities, interfaces, pads
40and links.
41
42Before the second call, the userspace should allocate arrays to store
43the graph elements that are desired, putting the pointers to them at the
44ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
45other values untouched.
46
47If the ``topology_version`` remains the same, the ioctl should fill the
48desired arrays with the media graph elements.
49
50.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}|
51
52.. c:type:: media_v2_topology
53
54.. flat-table:: struct media_v2_topology
55    :header-rows:  0
56    :stub-columns: 0
57    :widths: 1 2 8
58
59    *  -  __u64
60       -  ``topology_version``
61       -  Version of the media graph topology. When the graph is created,
62	  this field starts with zero. Every time a graph element is added
63	  or removed, this field is incremented.
64
65    *  -  __u32
66       -  ``num_entities``
67       -  Number of entities in the graph
68
69    *  -  __u32
70       -  ``reserved1``
71       -  Applications and drivers shall set this to 0.
72
73    *  -  __u64
74       -  ``ptr_entities``
75       -  A pointer to a memory area where the entities array will be
76	  stored, converted to a 64-bits integer. It can be zero. if zero,
77	  the ioctl won't store the entities. It will just update
78	  ``num_entities``
79
80    *  -  __u32
81       -  ``num_interfaces``
82       -  Number of interfaces in the graph
83
84    *  -  __u32
85       -  ``reserved2``
86       -  Applications and drivers shall set this to 0.
87
88    *  -  __u64
89       -  ``ptr_interfaces``
90       -  A pointer to a memory area where the interfaces array will be
91	  stored, converted to a 64-bits integer. It can be zero. if zero,
92	  the ioctl won't store the interfaces. It will just update
93	  ``num_interfaces``
94
95    *  -  __u32
96       -  ``num_pads``
97       -  Total number of pads in the graph
98
99    *  -  __u32
100       -  ``reserved3``
101       -  Applications and drivers shall set this to 0.
102
103    *  -  __u64
104       -  ``ptr_pads``
105       -  A pointer to a memory area where the pads array will be stored,
106	  converted to a 64-bits integer. It can be zero. if zero, the ioctl
107	  won't store the pads. It will just update ``num_pads``
108
109    *  -  __u32
110       -  ``num_links``
111       -  Total number of data and interface links in the graph
112
113    *  -  __u32
114       -  ``reserved4``
115       -  Applications and drivers shall set this to 0.
116
117    *  -  __u64
118       -  ``ptr_links``
119       -  A pointer to a memory area where the links array will be stored,
120	  converted to a 64-bits integer. It can be zero. if zero, the ioctl
121	  won't store the links. It will just update ``num_links``
122
123
124.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
125
126.. c:type:: media_v2_entity
127
128.. flat-table:: struct media_v2_entity
129    :header-rows:  0
130    :stub-columns: 0
131    :widths: 1 2 8
132
133    *  -  __u32
134       -  ``id``
135       -  Unique ID for the entity. Do not expect that the ID will
136	  always be the same for each instance of the device. In other words,
137	  do not hardcode entity IDs in an application.
138
139    *  -  char
140       -  ``name``\ [64]
141       -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
142          within the media topology.
143
144    *  -  __u32
145       -  ``function``
146       -  Entity main function, see :ref:`media-entity-functions` for details.
147
148    *  -  __u32
149       -  ``flags``
150       -  Entity flags, see :ref:`media-entity-flag` for details.
151	  Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)``
152	  returns true. The ``media_version`` is defined in struct
153	  :c:type:`media_device_info` and can be retrieved using
154	  :ref:`MEDIA_IOC_DEVICE_INFO`.
155
156    *  -  __u32
157       -  ``reserved``\ [5]
158       -  Reserved for future extensions. Drivers and applications must set
159	  this array to zero.
160
161
162.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
163
164.. c:type:: media_v2_interface
165
166.. flat-table:: struct media_v2_interface
167    :header-rows:  0
168    :stub-columns: 0
169    :widths: 1 2 8
170
171    *  -  __u32
172       -  ``id``
173       -  Unique ID for the interface. Do not expect that the ID will
174	  always be the same for each instance of the device. In other words,
175	  do not hardcode interface IDs in an application.
176
177    *  -  __u32
178       -  ``intf_type``
179       -  Interface type, see :ref:`media-intf-type` for details.
180
181    *  -  __u32
182       -  ``flags``
183       -  Interface flags. Currently unused.
184
185    *  -  __u32
186       -  ``reserved``\ [9]
187       -  Reserved for future extensions. Drivers and applications must set
188	  this array to zero.
189
190    *  -  struct media_v2_intf_devnode
191       -  ``devnode``
192       -  Used only for device node interfaces. See
193	  :c:type:`media_v2_intf_devnode` for details.
194
195
196.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
197
198.. c:type:: media_v2_intf_devnode
199
200.. flat-table:: struct media_v2_intf_devnode
201    :header-rows:  0
202    :stub-columns: 0
203    :widths: 1 2 8
204
205    *  -  __u32
206       -  ``major``
207       -  Device node major number.
208
209    *  -  __u32
210       -  ``minor``
211       -  Device node minor number.
212
213.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
214
215.. c:type:: media_v2_pad
216
217.. flat-table:: struct media_v2_pad
218    :header-rows:  0
219    :stub-columns: 0
220    :widths: 1 2 8
221
222    *  -  __u32
223       -  ``id``
224       -  Unique ID for the pad. Do not expect that the ID will
225	  always be the same for each instance of the device. In other words,
226	  do not hardcode pad IDs in an application.
227
228    *  -  __u32
229       -  ``entity_id``
230       -  Unique ID for the entity where this pad belongs.
231
232    *  -  __u32
233       -  ``flags``
234       -  Pad flags, see :ref:`media-pad-flag` for more details.
235
236    *  -  __u32
237       -  ``index``
238       -  Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)``
239	  returns true. The ``media_version`` is defined in struct
240	  :c:type:`media_device_info` and can be retrieved using
241	  :ref:`MEDIA_IOC_DEVICE_INFO`.
242
243    *  -  __u32
244       -  ``reserved``\ [4]
245       -  Reserved for future extensions. Drivers and applications must set
246	  this array to zero.
247
248
249.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
250
251.. c:type:: media_v2_link
252
253.. flat-table:: struct media_v2_link
254    :header-rows:  0
255    :stub-columns: 0
256    :widths: 1 2 8
257
258    *  -  __u32
259       -  ``id``
260       -  Unique ID for the link. Do not expect that the ID will
261	  always be the same for each instance of the device. In other words,
262	  do not hardcode link IDs in an application.
263
264    *  -  __u32
265       -  ``source_id``
266       -  On pad to pad links: unique ID for the source pad.
267
268	  On interface to entity links: unique ID for the interface.
269
270    *  -  __u32
271       -  ``sink_id``
272       -  On pad to pad links: unique ID for the sink pad.
273
274	  On interface to entity links: unique ID for the entity.
275
276    *  -  __u32
277       -  ``flags``
278       -  Link flags, see :ref:`media-link-flag` for more details.
279
280    *  -  __u32
281       -  ``reserved``\ [6]
282       -  Reserved for future extensions. Drivers and applications must set
283	  this array to zero.
284
285
286Return Value
287============
288
289On success 0 is returned, on error -1 and the ``errno`` variable is set
290appropriately. The generic error codes are described at the
291:ref:`Generic Error Codes <gen-errors>` chapter.
292
293ENOSPC
294    This is returned when either one or more of the num_entities,
295    num_interfaces, num_links or num_pads are non-zero and are
296    smaller than the actual number of elements inside the graph. This
297    may happen if the ``topology_version`` changed when compared to the
298    last time this ioctl was called. Userspace should usually free the
299    area for the pointers, zero the struct elements and call this ioctl
300    again.
301