1 .. -*- coding: utf-8; mode: rst -*-
3 .. _media_ioc_g_topology:
5 **************************
6 ioctl MEDIA_IOC_G_TOPOLOGY
7 **************************
12 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
18 .. c:function:: int ioctl( int fd, int request, struct media_v2_topology *argp )
25 File descriptor returned by :ref:`open() <media-func-open>`.
36 The typical usage of this ioctl is to call it twice. On the first call,
37 the structure defined at struct
38 :ref:`media_v2_topology <media-v2-topology>` should be zeroed. At
39 return, if no errors happen, this ioctl will return the
40 ``topology_version`` and the total number of entities, interfaces, pads
43 Before the second call, the userspace should allocate arrays to store
44 the graph elements that are desired, putting the pointers to them at the
45 ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
46 other values untouched.
48 If the ``topology_version`` remains the same, the ioctl should fill the
49 desired arrays with the media graph elements.
51 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
53 .. _media-v2-topology:
55 .. flat-table:: struct media_v2_topology
65 - ``topology_version``
67 - Version of the media graph topology. When the graph is created,
68 this field starts with zero. Every time a graph element is added
69 or removed, this field is incremented.
77 - Number of entities in the graph
85 - A pointer to a memory area where the entities array will be
86 stored, converted to a 64-bits integer. It can be zero. if zero,
87 the ioctl won't store the entities. It will just update
96 - Number of interfaces in the graph
104 - A pointer to a memory area where the interfaces array will be
105 stored, converted to a 64-bits integer. It can be zero. if zero,
106 the ioctl won't store the interfaces. It will just update
115 - Total number of pads in the graph
123 - A pointer to a memory area where the pads array will be stored,
124 converted to a 64-bits integer. It can be zero. if zero, the ioctl
125 won't store the pads. It will just update ``num_pads``
133 - Total number of data and interface links in the graph
141 - A pointer to a memory area where the links array will be stored,
142 converted to a 64-bits integer. It can be zero. if zero, the ioctl
143 won't store the links. It will just update ``num_links``
146 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
150 .. flat-table:: struct media_v2_entity
162 - Unique ID for the entity.
170 - Entity name as an UTF-8 NULL-terminated string.
178 - Entity main function, see :ref:`media-entity-type` for details.
186 - Reserved for future extensions. Drivers and applications must set
190 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
192 .. _media-v2-interface:
194 .. flat-table:: struct media_v2_interface
205 - Unique ID for the interface.
213 - Interface type, see :ref:`media-intf-type` for details.
221 - Interface flags. Currently unused.
229 - Reserved for future extensions. Drivers and applications must set
234 - struct media_v2_intf_devnode
238 - Used only for device node interfaces. See
239 :ref:`media-v2-intf-devnode` for details..
242 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
244 .. _media-v2-intf-devnode:
246 .. flat-table:: struct media_v2_interface
258 - Device node major number.
266 - Device node minor number.
269 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
273 .. flat-table:: struct media_v2_pad
285 - Unique ID for the pad.
293 - Unique ID for the entity where this pad belongs.
301 - Pad flags, see :ref:`media-pad-flag` for more details.
309 - Reserved for future extensions. Drivers and applications must set
313 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}|
317 .. flat-table:: struct media_v2_pad
329 - Unique ID for the pad.
337 - On pad to pad links: unique ID for the source pad.
339 On interface to entity links: unique ID for the interface.
347 - On pad to pad links: unique ID for the sink pad.
349 On interface to entity links: unique ID for the entity.
357 - Link flags, see :ref:`media-link-flag` for more details.
365 - Reserved for future extensions. Drivers and applications must set
372 On success 0 is returned, on error -1 and the ``errno`` variable is set
373 appropriately. The generic error codes are described at the
374 :ref:`Generic Error Codes <gen-errors>` chapter.
377 This is returned when either one or more of the num_entities,
378 num_interfaces, num_links or num_pads are non-zero and are
379 smaller than the actual number of elements inside the graph. This
380 may happen if the ``topology_version`` changed when compared to the
381 last time this ioctl was called. Userspace should usually free the
382 area for the pointers, zero the struct elements and call this ioctl