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