Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <refentry id="vidioc-querycap"> |
2 | <refmeta> | |
3 | <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle> | |
4 | &manvol; | |
5 | </refmeta> | |
6 | ||
7 | <refnamediv> | |
8 | <refname>VIDIOC_QUERYCAP</refname> | |
9 | <refpurpose>Query device capabilities</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 v4l2_capability *<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>&fd;</para> | |
31 | </listitem> | |
32 | </varlistentry> | |
33 | <varlistentry> | |
34 | <term><parameter>request</parameter></term> | |
35 | <listitem> | |
36 | <para>VIDIOC_QUERYCAP</para> | |
37 | </listitem> | |
38 | </varlistentry> | |
39 | <varlistentry> | |
40 | <term><parameter>argp</parameter></term> | |
41 | <listitem> | |
42 | <para></para> | |
43 | </listitem> | |
44 | </varlistentry> | |
45 | </variablelist> | |
46 | </refsect1> | |
47 | ||
48 | <refsect1> | |
49 | <title>Description</title> | |
50 | ||
51 | <para>All V4L2 devices support the | |
52 | <constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify | |
53 | kernel devices compatible with this specification and to obtain | |
54 | information about driver and hardware capabilities. The ioctl takes a | |
55 | pointer to a &v4l2-capability; which is filled by the driver. When the | |
56 | driver is not compatible with this specification the ioctl returns an | |
57 | &EINVAL;.</para> | |
58 | ||
59 | <table pgwide="1" frame="none" id="v4l2-capability"> | |
60 | <title>struct <structname>v4l2_capability</structname></title> | |
61 | <tgroup cols="3"> | |
62 | &cs-str; | |
63 | <tbody valign="top"> | |
64 | <row> | |
65 | <entry>__u8</entry> | |
66 | <entry><structfield>driver</structfield>[16]</entry> | |
67 | <entry><para>Name of the driver, a unique NUL-terminated | |
68 | ASCII string. For example: "bttv". Driver specific applications can | |
69 | use this information to verify the driver identity. It is also useful | |
c20eb18c MCC |
70 | to work around known bugs, or to identify drivers in error reports.</para> |
71 | <para>Storing strings in fixed sized arrays is bad | |
8e080c2e MCC |
72 | practice but unavoidable here. Drivers and applications should take |
73 | precautions to never read or write beyond the end of the array and to | |
74 | make sure the strings are properly NUL-terminated.</para></entry> | |
75 | </row> | |
76 | <row> | |
77 | <entry>__u8</entry> | |
78 | <entry><structfield>card</structfield>[32]</entry> | |
22331a5e | 79 | <entry>Name of the device, a NUL-terminated UTF-8 string. |
8e080c2e MCC |
80 | For example: "Yoyodyne TV/FM". One driver may support different brands |
81 | or models of video hardware. This information is intended for users, | |
82 | for example in a menu of available devices. Since multiple TV cards of | |
83 | the same brand may be installed which are supported by the same | |
84 | driver, this name should be combined with the character device file | |
85 | name (⪚ <filename>/dev/video2</filename>) or the | |
86 | <structfield>bus_info</structfield> string to avoid | |
87 | ambiguities.</entry> | |
88 | </row> | |
89 | <row> | |
90 | <entry>__u8</entry> | |
91 | <entry><structfield>bus_info</structfield>[32]</entry> | |
92 | <entry>Location of the device in the system, a | |
cd56c8dd | 93 | NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This |
8e080c2e | 94 | information is intended for users, to distinguish multiple |
cd56c8dd HV |
95 | identical devices. If no such information is available the field must |
96 | simply count the devices controlled by the driver ("platform:vivi-000"). | |
97 | The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards, | |
98 | "usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices, | |
99 | "parport" for parallel port devices and "platform:" for platform devices.</entry> | |
8e080c2e MCC |
100 | </row> |
101 | <row> | |
102 | <entry>__u32</entry> | |
103 | <entry><structfield>version</structfield></entry> | |
c20eb18c | 104 | <entry><para>Version number of the driver.</para> |
5f853487 HV |
105 | <para>Starting with kernel 3.1, the version reported is provided by the |
106 | V4L2 subsystem following the kernel numbering scheme. However, it | |
107 | may not always return the same version as the kernel if, for example, | |
108 | a stable or distribution-modified kernel uses the V4L2 stack from a | |
c20eb18c MCC |
109 | newer kernel.</para> |
110 | <para>The version number is formatted using the | |
8e080c2e MCC |
111 | <constant>KERNEL_VERSION()</constant> macro:</para></entry> |
112 | </row> | |
113 | <row> | |
114 | <entry spanname="hspan"><para> | |
115 | <programlisting> | |
116 | #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) | |
117 | ||
118 | __u32 version = KERNEL_VERSION(0, 8, 1); | |
119 | ||
120 | printf ("Version: %u.%u.%u\n", | |
121 | (version >> 16) & 0xFF, | |
122 | (version >> 8) & 0xFF, | |
123 | version & 0xFF); | |
124 | </programlisting></para></entry> | |
125 | </row> | |
126 | <row> | |
127 | <entry>__u32</entry> | |
128 | <entry><structfield>capabilities</structfield></entry> | |
583aa3a9 HV |
129 | <entry>Available capabilities of the physical device as a whole, see <xref |
130 | linkend="device-capabilities" />. The same physical device can export | |
131 | multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and /dev/radioZ). | |
132 | The <structfield>capabilities</structfield> field should contain a union | |
133 | of all capabilities available around the several V4L2 devices exported | |
134 | to userspace. | |
135 | For all those devices the <structfield>capabilities</structfield> field | |
136 | returns the same set of capabilities. This allows applications to open | |
137 | just one of the devices (typically the video device) and discover whether | |
138 | video, vbi and/or radio are also supported. | |
139 | </entry> | |
8e080c2e MCC |
140 | </row> |
141 | <row> | |
142 | <entry>__u32</entry> | |
583aa3a9 HV |
143 | <entry><structfield>device_caps</structfield></entry> |
144 | <entry>Device capabilities of the opened device, see <xref | |
145 | linkend="device-capabilities" />. Should contain the available capabilities | |
146 | of that specific device node. So, for example, <structfield>device_caps</structfield> | |
147 | of a radio device will only contain radio related capabilities and | |
148 | no video or vbi capabilities. This field is only set if the <structfield>capabilities</structfield> | |
149 | field contains the <constant>V4L2_CAP_DEVICE_CAPS</constant> capability. | |
150 | Only the <structfield>capabilities</structfield> field can have the | |
151 | <constant>V4L2_CAP_DEVICE_CAPS</constant> capability, <structfield>device_caps</structfield> | |
152 | will never set <constant>V4L2_CAP_DEVICE_CAPS</constant>. | |
153 | </entry> | |
154 | </row> | |
155 | <row> | |
156 | <entry>__u32</entry> | |
157 | <entry><structfield>reserved</structfield>[3]</entry> | |
8e080c2e MCC |
158 | <entry>Reserved for future extensions. Drivers must set |
159 | this array to zero.</entry> | |
160 | </row> | |
161 | </tbody> | |
162 | </tgroup> | |
163 | </table> | |
164 | ||
165 | <table pgwide="1" frame="none" id="device-capabilities"> | |
166 | <title>Device Capabilities Flags</title> | |
167 | <tgroup cols="3"> | |
168 | &cs-def; | |
169 | <tbody valign="top"> | |
170 | <row> | |
171 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> | |
172 | <entry>0x00000001</entry> | |
d39155d9 PO |
173 | <entry>The device supports the single-planar API through the <link |
174 | linkend="capture">Video Capture</link> interface.</entry> | |
53b5d574 PO |
175 | </row> |
176 | <row> | |
177 | <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry> | |
178 | <entry>0x00001000</entry> | |
d39155d9 PO |
179 | <entry>The device supports the |
180 | <link linkend="planar-apis">multi-planar API</link> through the | |
181 | <link linkend="capture">Video Capture</link> interface.</entry> | |
8e080c2e MCC |
182 | </row> |
183 | <row> | |
184 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> | |
185 | <entry>0x00000002</entry> | |
d39155d9 PO |
186 | <entry>The device supports the single-planar API through the <link |
187 | linkend="output">Video Output</link> interface.</entry> | |
53b5d574 PO |
188 | </row> |
189 | <row> | |
190 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry> | |
191 | <entry>0x00002000</entry> | |
d39155d9 PO |
192 | <entry>The device supports the |
193 | <link linkend="planar-apis">multi-planar API</link> through the | |
194 | <link linkend="output">Video Output</link> interface.</entry> | |
8e080c2e | 195 | </row> |
f0476a83 SN |
196 | <row> |
197 | <entry><constant>V4L2_CAP_VIDEO_M2M</constant></entry> | |
198 | <entry>0x00004000</entry> | |
199 | <entry>The device supports the single-planar API through the | |
200 | Video Memory-To-Memory interface.</entry> | |
201 | </row> | |
202 | <row> | |
203 | <entry><constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant></entry> | |
204 | <entry>0x00008000</entry> | |
205 | <entry>The device supports the | |
206 | <link linkend="planar-apis">multi-planar API</link> through the | |
207 | Video Memory-To-Memory interface.</entry> | |
208 | </row> | |
8e080c2e MCC |
209 | <row> |
210 | <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> | |
211 | <entry>0x00000004</entry> | |
212 | <entry>The device supports the <link | |
213 | linkend="overlay">Video Overlay</link> interface. A video overlay device | |
214 | typically stores captured images directly in the video memory of a | |
215 | graphics card, with hardware clipping and scaling.</entry> | |
216 | </row> | |
217 | <row> | |
218 | <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> | |
219 | <entry>0x00000010</entry> | |
220 | <entry>The device supports the <link linkend="raw-vbi">Raw | |
221 | VBI Capture</link> interface, providing Teletext and Closed Caption | |
222 | data.</entry> | |
223 | </row> | |
224 | <row> | |
225 | <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry> | |
226 | <entry>0x00000020</entry> | |
227 | <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry> | |
228 | </row> | |
229 | <row> | |
230 | <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry> | |
231 | <entry>0x00000040</entry> | |
232 | <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry> | |
233 | </row> | |
234 | <row> | |
235 | <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry> | |
236 | <entry>0x00000080</entry> | |
237 | <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry> | |
238 | </row> | |
239 | <row> | |
240 | <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> | |
241 | <entry>0x00000100</entry> | |
0827d066 | 242 | <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry> |
8e080c2e MCC |
243 | </row> |
244 | <row> | |
245 | <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> | |
246 | <entry>0x00000200</entry> | |
247 | <entry>The device supports the <link linkend="osd">Video | |
248 | Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video | |
249 | Overlay</wordasword> interface, this is a secondary function of video | |
250 | output devices and overlays an image onto an outgoing video signal. | |
251 | When the driver sets this flag, it must clear the | |
252 | <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice | |
253 | versa.<footnote><para>The &v4l2-framebuffer; lacks an | |
254 | &v4l2-buf-type; field, therefore the type of overlay is implied by the | |
255 | driver capabilities.</para></footnote></entry> | |
256 | </row> | |
257 | <row> | |
258 | <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry> | |
259 | <entry>0x00000400</entry> | |
260 | <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for | |
261 | hardware frequency seeking.</entry> | |
262 | </row> | |
0827d066 HV |
263 | <row> |
264 | <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry> | |
265 | <entry>0x00000800</entry> | |
266 | <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry> | |
267 | </row> | |
8e080c2e MCC |
268 | <row> |
269 | <entry><constant>V4L2_CAP_TUNER</constant></entry> | |
270 | <entry>0x00010000</entry> | |
271 | <entry>The device has some sort of tuner to | |
272 | receive RF-modulated video signals. For more information about | |
273 | tuner programming see | |
274 | <xref linkend="tuner" />.</entry> | |
275 | </row> | |
276 | <row> | |
277 | <entry><constant>V4L2_CAP_AUDIO</constant></entry> | |
278 | <entry>0x00020000</entry> | |
279 | <entry>The device has audio inputs or outputs. It may or | |
280 | may not support audio recording or playback, in PCM or compressed | |
281 | formats. PCM audio support must be implemented as ALSA or OSS | |
282 | interface. For more information on audio inputs and outputs see <xref | |
283 | linkend="audio" />.</entry> | |
284 | </row> | |
285 | <row> | |
286 | <entry><constant>V4L2_CAP_RADIO</constant></entry> | |
287 | <entry>0x00040000</entry> | |
288 | <entry>This is a radio receiver.</entry> | |
289 | </row> | |
290 | <row> | |
291 | <entry><constant>V4L2_CAP_MODULATOR</constant></entry> | |
292 | <entry>0x00080000</entry> | |
293 | <entry>The device has some sort of modulator to | |
294 | emit RF-modulated video/audio signals. For more information about | |
295 | modulator programming see | |
296 | <xref linkend="tuner" />.</entry> | |
559f40fe AP |
297 | </row> |
298 | <row> | |
299 | <entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry> | |
300 | <entry>0x00100000</entry> | |
301 | <entry>The device supports the | |
302 | <link linkend="sdr">SDR Capture</link> interface.</entry> | |
d52e2381 LP |
303 | </row> |
304 | <row> | |
305 | <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry> | |
306 | <entry>0x00200000</entry> | |
307 | <entry>The device supports the &v4l2-pix-format; extended | |
308 | fields.</entry> | |
be8ee526 AP |
309 | </row> |
310 | <row> | |
311 | <entry><constant>V4L2_CAP_SDR_OUTPUT</constant></entry> | |
312 | <entry>0x00400000</entry> | |
313 | <entry>The device supports the | |
314 | <link linkend="sdr">SDR Output</link> interface.</entry> | |
8e080c2e MCC |
315 | </row> |
316 | <row> | |
317 | <entry><constant>V4L2_CAP_READWRITE</constant></entry> | |
318 | <entry>0x01000000</entry> | |
319 | <entry>The device supports the <link | |
320 | linkend="rw">read()</link> and/or <link linkend="rw">write()</link> | |
321 | I/O methods.</entry> | |
322 | </row> | |
323 | <row> | |
324 | <entry><constant>V4L2_CAP_ASYNCIO</constant></entry> | |
325 | <entry>0x02000000</entry> | |
326 | <entry>The device supports the <link | |
327 | linkend="async">asynchronous</link> I/O methods.</entry> | |
328 | </row> | |
329 | <row> | |
330 | <entry><constant>V4L2_CAP_STREAMING</constant></entry> | |
331 | <entry>0x04000000</entry> | |
332 | <entry>The device supports the <link | |
333 | linkend="mmap">streaming</link> I/O method.</entry> | |
334 | </row> | |
583aa3a9 HV |
335 | <row> |
336 | <entry><constant>V4L2_CAP_DEVICE_CAPS</constant></entry> | |
337 | <entry>0x80000000</entry> | |
338 | <entry>The driver fills the <structfield>device_caps</structfield> | |
339 | field. This capability can only appear in the <structfield>capabilities</structfield> | |
340 | field and never in the <structfield>device_caps</structfield> field.</entry> | |
341 | </row> | |
8e080c2e MCC |
342 | </tbody> |
343 | </tgroup> | |
344 | </table> | |
345 | </refsect1> | |
346 | ||
347 | <refsect1> | |
348 | &return-value; | |
8e080c2e MCC |
349 | </refsect1> |
350 | </refentry> |