CoCalc -- media-ioc-enum-entities.xml

GitHub Repository: awilliam/linux-vfio
Path: blob/master/Documentation/DocBook/v4l/media-ioc-enum-entities.xml
¹⁰⁸²¹ views
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

310
Product

Resources

Company
