tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: MC
3
4.. _media_ioc_enum_links:
5
6**************************
7ioctl MEDIA_IOC_ENUM_LINKS
8**************************
9
10Name
11====
12
13MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
14
15Synopsis
16========
17
18.. c:macro:: MEDIA_IOC_ENUM_LINKS
19
20``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *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_links_enum`.
30
31Description
32===========
33
34To enumerate pads and/or links for a given entity, applications set the
35entity field of a struct :c:type:`media_links_enum`
36structure and initialize the struct
37:c:type:`media_pad_desc` and struct
38:c:type:`media_link_desc` structure arrays pointed by
39the ``pads`` and ``links`` fields. They then call the
40MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
41
42If the ``pads`` field is not NULL, the driver fills the ``pads`` array
43with information about the entity's pads. The array must have enough
44room to store all the entity's pads. The number of pads can be retrieved
45with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
46
47If the ``links`` field is not NULL, the driver fills the ``links`` array
48with information about the entity's outbound links. The array must have
49enough room to store all the entity's outbound links. The number of
50outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.
51
52Only forward links that originate at one of the entity's source pads are
53returned during the enumeration process.
54
55.. c:type:: media_links_enum
56
57.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
58
59.. flat-table:: struct media_links_enum
60 :header-rows: 0
61 :stub-columns: 0
62 :widths: 1 1 2
63
64 * - __u32
65 - ``entity``
66 - Entity id, set by the application.
67
68 * - struct :c:type:`media_pad_desc`
69 - \*\ ``pads``
70 - Pointer to a pads array allocated by the application. Ignored if
71 NULL.
72
73 * - struct :c:type:`media_link_desc`
74 - \*\ ``links``
75 - Pointer to a links array allocated by the application. Ignored if
76 NULL.
77
78 * - __u32
79 - ``reserved[4]``
80 - Reserved for future extensions. Drivers and applications must set
81 the array to zero.
82
83.. c:type:: media_pad_desc
84
85.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
86
87.. flat-table:: struct media_pad_desc
88 :header-rows: 0
89 :stub-columns: 0
90 :widths: 1 1 2
91
92 * - __u32
93 - ``entity``
94 - ID of the entity this pad belongs to.
95
96 * - __u16
97 - ``index``
98 - Pad index, starts at 0.
99
100 * - __u32
101 - ``flags``
102 - Pad flags, see :ref:`media-pad-flag` for more details.
103
104 * - __u32
105 - ``reserved[2]``
106 - Reserved for future extensions. Drivers and applications must set
107 the array to zero.
108
109
110.. c:type:: media_link_desc
111
112.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
113
114.. flat-table:: struct media_link_desc
115 :header-rows: 0
116 :stub-columns: 0
117 :widths: 1 1 2
118
119 * - struct :c:type:`media_pad_desc`
120 - ``source``
121 - Pad at the origin of this link.
122
123 * - struct :c:type:`media_pad_desc`
124 - ``sink``
125 - Pad at the target of this link.
126
127 * - __u32
128 - ``flags``
129 - Link flags, see :ref:`media-link-flag` for more details.
130
131 * - __u32
132 - ``reserved[2]``
133 - Reserved for future extensions. Drivers and applications must set
134 the array to zero.
135
136Return Value
137============
138
139On success 0 is returned, on error -1 and the ``errno`` variable is set
140appropriately. The generic error codes are described at the
141:ref:`Generic Error Codes <gen-errors>` chapter.
142
143EINVAL
144 The struct :c:type:`media_links_enum` ``id``
145 references a non-existing entity.