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