← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-ti-omap4/precise

« back to all changes in this revision

Viewing changes to Documentation/DocBook/v4l/media-ioc-enum-entities.xml

  • Committer: Bazaar Package Importer
  • Author(s): Paolo Pisati
  • Date: 2011-06-29 15:23:51 UTC
  • mfrom: (26.1.1 natty-proposed)
  • Revision ID: james.westby@ubuntu.com-20110629152351-xs96tm303d95rpbk
Tags: 3.0.0-1200.2
* Rebased against 3.0.0-6.7
* BSP from TI based on 3.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/v4l/media-ioc-enum-entities.xml
 
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>