1<refentry id="media-ioc-enum-entities">
2  <refmeta>
3    <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
4    &manvol;
5  </refmeta>
6
7  <refnamediv>
8    <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
9    <refpurpose>Enumerate entities and their properties</refpurpose>
10  </refnamediv>
11
12  <refsynopsisdiv>
13    <funcsynopsis>
14      <funcprototype>
15	<funcdef>int <function>ioctl</function></funcdef>
16	<paramdef>int <parameter>fd</parameter></paramdef>
17	<paramdef>int <parameter>request</parameter></paramdef>
18	<paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
19      </funcprototype>
20    </funcsynopsis>
21  </refsynopsisdiv>
22
23  <refsect1>
24    <title>Arguments</title>
25
26    <variablelist>
27      <varlistentry>
28	<term><parameter>fd</parameter></term>
29	<listitem>
30	  <para>File descriptor returned by
31	  <link linkend='media-func-open'><function>open()</function></link>.</para>
32	</listitem>
33      </varlistentry>
34      <varlistentry>
35	<term><parameter>request</parameter></term>
36	<listitem>
37	  <para>MEDIA_IOC_ENUM_ENTITIES</para>
38	</listitem>
39      </varlistentry>
40      <varlistentry>
41	<term><parameter>argp</parameter></term>
42	<listitem>
43	  <para></para>
44	</listitem>
45      </varlistentry>
46    </variablelist>
47  </refsect1>
48
49  <refsect1>
50    <title>Description</title>
51    <para>To query the attributes of an entity, applications set the id field
52    of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
53    ioctl with a pointer to this structure. The driver fills the rest of the
54    structure or returns an &EINVAL; when the id is invalid.</para>
55    <para>Entities can be enumerated by or'ing the id with the
56    <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
57    information about the entity with the smallest id strictly larger than the
58    requested one ('next entity'), or the &EINVAL; if there is none.</para>
59    <para>Entity IDs can be non-contiguous. Applications must
60    <emphasis>not</emphasis> try to enumerate entities by calling
61    MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
62    <para>Two or more entities that share a common non-zero
63    <structfield>group_id</structfield> value are considered as logically
64    grouped. Groups are used to report
65    <itemizedlist>
66      <listitem><para>ALSA, VBI and video nodes that carry the same media
67      stream</para></listitem>
68      <listitem><para>lens and flash controllers associated with a sensor</para></listitem>
69    </itemizedlist>
70    </para>
71
72    <table pgwide="1" frame="none" id="media-entity-desc">
73      <title>struct <structname>media_entity_desc</structname></title>
74      <tgroup cols="5">
75	<colspec colname="c1" />
76	<colspec colname="c2" />
77	<colspec colname="c3" />
78	<colspec colname="c4" />
79	<colspec colname="c5" />
80	<tbody valign="top">
81	  <row>
82	    <entry>__u32</entry>
83	    <entry><structfield>id</structfield></entry>
84	    <entry></entry>
85	    <entry></entry>
86	    <entry>Entity id, set by the application. When the id is or'ed with
87	    <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
88	    flag and returns the first entity with a larger id.</entry>
89	  </row>
90	  <row>
91	    <entry>char</entry>
92	    <entry><structfield>name</structfield>[32]</entry>
93	    <entry></entry>
94	    <entry></entry>
95	    <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
96	  </row>
97	  <row>
98	    <entry>__u32</entry>
99	    <entry><structfield>type</structfield></entry>
100	    <entry></entry>
101	    <entry></entry>
102	    <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
103	  </row>
104	  <row>
105	    <entry>__u32</entry>
106	    <entry><structfield>revision</structfield></entry>
107	    <entry></entry>
108	    <entry></entry>
109	    <entry>Entity revision in a driver/hardware specific format.</entry>
110	  </row>
111	  <row>
112	    <entry>__u32</entry>
113	    <entry><structfield>flags</structfield></entry>
114	    <entry></entry>
115	    <entry></entry>
116	    <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
117	  </row>
118	  <row>
119	    <entry>__u32</entry>
120	    <entry><structfield>group_id</structfield></entry>
121	    <entry></entry>
122	    <entry></entry>
123	    <entry>Entity group ID</entry>
124	  </row>
125	  <row>
126	    <entry>__u16</entry>
127	    <entry><structfield>pads</structfield></entry>
128	    <entry></entry>
129	    <entry></entry>
130	    <entry>Number of pads</entry>
131	  </row>
132	  <row>
133	    <entry>__u16</entry>
134	    <entry><structfield>links</structfield></entry>
135	    <entry></entry>
136	    <entry></entry>
137	    <entry>Total number of outbound links. Inbound links are not counted
138	    in this field.</entry>
139	  </row>
140	  <row>
141	    <entry>union</entry>
142	  </row>
143	  <row>
144	    <entry></entry>
145	    <entry>struct</entry>
146	    <entry><structfield>v4l</structfield></entry>
147	    <entry></entry>
148	    <entry>Valid for V4L sub-devices and nodes only.</entry>
149	  </row>
150	  <row>
151	    <entry></entry>
152	    <entry></entry>
153	    <entry>__u32</entry>
154	    <entry><structfield>major</structfield></entry>
155	    <entry>V4L device node major number. For V4L sub-devices with no
156	    device node, set by the driver to 0.</entry>
157	  </row>
158	  <row>
159	    <entry></entry>
160	    <entry></entry>
161	    <entry>__u32</entry>
162	    <entry><structfield>minor</structfield></entry>
163	    <entry>V4L device node minor number. For V4L sub-devices with no
164	    device node, set by the driver to 0.</entry>
165	  </row>
166	  <row>
167	    <entry></entry>
168	    <entry>struct</entry>
169	    <entry><structfield>fb</structfield></entry>
170	    <entry></entry>
171	    <entry>Valid for frame buffer nodes only.</entry>
172	  </row>
173	  <row>
174	    <entry></entry>
175	    <entry></entry>
176	    <entry>__u32</entry>
177	    <entry><structfield>major</structfield></entry>
178	    <entry>Frame buffer device node major number.</entry>
179	  </row>
180	  <row>
181	    <entry></entry>
182	    <entry></entry>
183	    <entry>__u32</entry>
184	    <entry><structfield>minor</structfield></entry>
185	    <entry>Frame buffer device node minor number.</entry>
186	  </row>
187	  <row>
188	    <entry></entry>
189	    <entry>struct</entry>
190	    <entry><structfield>alsa</structfield></entry>
191	    <entry></entry>
192	    <entry>Valid for ALSA devices only.</entry>
193	  </row>
194	  <row>
195	    <entry></entry>
196	    <entry></entry>
197	    <entry>__u32</entry>
198	    <entry><structfield>card</structfield></entry>
199	    <entry>ALSA card number</entry>
200	  </row>
201	  <row>
202	    <entry></entry>
203	    <entry></entry>
204	    <entry>__u32</entry>
205	    <entry><structfield>device</structfield></entry>
206	    <entry>ALSA device number</entry>
207	  </row>
208	  <row>
209	    <entry></entry>
210	    <entry></entry>
211	    <entry>__u32</entry>
212	    <entry><structfield>subdevice</structfield></entry>
213	    <entry>ALSA sub-device number</entry>
214	  </row>
215	  <row>
216	    <entry></entry>
217	    <entry>int</entry>
218	    <entry><structfield>dvb</structfield></entry>
219	    <entry></entry>
220	    <entry>DVB card number</entry>
221	  </row>
222	  <row>
223	    <entry></entry>
224	    <entry>__u8</entry>
225	    <entry><structfield>raw</structfield>[180]</entry>
226	    <entry></entry>
227	    <entry></entry>
228	  </row>
229	</tbody>
230      </tgroup>
231    </table>
232
233    <table frame="none" pgwide="1" id="media-entity-type">
234      <title>Media entity types</title>
235      <tgroup cols="2">
236        <colspec colname="c1"/>
237        <colspec colname="c2"/>
238	<tbody valign="top">
239	  <row>
240	    <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry>
241	    <entry>Unknown device node</entry>
242	  </row>
243	  <row>
244	    <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry>
245	    <entry>V4L video, radio or vbi device node</entry>
246	  </row>
247	  <row>
248	    <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry>
249	    <entry>Frame buffer device node</entry>
250	  </row>
251	  <row>
252	    <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry>
253	    <entry>ALSA card</entry>
254	  </row>
255	  <row>
256	    <entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry>
257	    <entry>DVB card</entry>
258	  </row>
259	  <row>
260	    <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry>
261	    <entry>Unknown V4L sub-device</entry>
262	  </row>
263	  <row>
264	    <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
265	    <entry>Video sensor</entry>
266	  </row>
267	  <row>
268	    <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
269	    <entry>Flash controller</entry>
270	  </row>
271	  <row>
272	    <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
273	    <entry>Lens controller</entry>
274	  </row>
275	</tbody>
276      </tgroup>
277    </table>
278
279    <table frame="none" pgwide="1" id="media-entity-flag">
280      <title>Media entity flags</title>
281      <tgroup cols="2">
282        <colspec colname="c1"/>
283        <colspec colname="c2"/>
284	<tbody valign="top">
285	  <row>
286	    <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
287	    <entry>Default entity for its type. Used to discover the default
288	    audio, VBI and video devices, the default camera sensor, ...</entry>
289	  </row>
290	</tbody>
291      </tgroup>
292    </table>
293  </refsect1>
294
295  <refsect1>
296    &return-value;
297
298    <variablelist>
299      <varlistentry>
300	<term><errorcode>EINVAL</errorcode></term>
301	<listitem>
302	  <para>The &media-entity-desc; <structfield>id</structfield> references
303	  a non-existing entity.</para>
304	</listitem>
305      </varlistentry>
306    </variablelist>
307  </refsect1>
308</refentry>
309