ARM: 7409/1: Do not call flush_cache_user_range with mmap_sem held
[linux/fpc-iii.git] / Documentation / DocBook / v4l / media-ioc-enum-entities.xml
blob576b68b33f2c4606b138c52b286cd60b88c6dcab
1 <refentry id="media-ioc-enum-entities">
2   <refmeta>
3     <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
4     &manvol;
5   </refmeta>
7   <refnamediv>
8     <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
9     <refpurpose>Enumerate entities and their properties</refpurpose>
10   </refnamediv>
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>
23   <refsect1>
24     <title>Arguments</title>
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>
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>
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>
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>
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>
295   <refsect1>
296     &return-value;
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>