]>
Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_QUERYCAP: |
5377d91f MH |
4 | |
5 | ********************* | |
6 | ioctl VIDIOC_QUERYCAP | |
7 | ********************* | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_QUERYCAP - Query device capabilities |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_QUERYCAP, struct v4l2_capability *argp ) |
19 | :name: VIDIOC_QUERYCAP | |
5377d91f | 20 | |
586027ce | 21 | |
15e7d615 | 22 | Arguments |
5377d91f MH |
23 | ========= |
24 | ||
25 | ``fd`` | |
26 | File descriptor returned by :ref:`open() <func-open>`. | |
27 | ||
5377d91f MH |
28 | ``argp`` |
29 | ||
30 | ||
15e7d615 | 31 | Description |
5377d91f MH |
32 | =========== |
33 | ||
34 | All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to | |
35 | identify kernel devices compatible with this specification and to obtain | |
36 | information about driver and hardware capabilities. The ioctl takes a | |
e8be7e97 | 37 | pointer to a struct :c:type:`v4l2_capability` which is |
5377d91f | 38 | filled by the driver. When the driver is not compatible with this |
cdb4af0f | 39 | specification the ioctl returns an ``EINVAL`` error code. |
5377d91f MH |
40 | |
41 | ||
48f69937 MCC |
42 | .. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}| |
43 | ||
e8be7e97 | 44 | .. c:type:: v4l2_capability |
fa92b04d | 45 | |
5377d91f MH |
46 | .. flat-table:: struct v4l2_capability |
47 | :header-rows: 0 | |
48 | :stub-columns: 0 | |
48f69937 | 49 | :widths: 3 4 20 |
5377d91f | 50 | |
c2b66caf LP |
51 | * - __u8 |
52 | - ``driver``\ [16] | |
53 | - Name of the driver, a unique NUL-terminated ASCII string. For | |
54 | example: "bttv". Driver specific applications can use this | |
55 | information to verify the driver identity. It is also useful to | |
56 | work around known bugs, or to identify drivers in error reports. | |
57 | ||
58 | Storing strings in fixed sized arrays is bad practice but | |
59 | unavoidable here. Drivers and applications should take precautions | |
60 | to never read or write beyond the end of the array and to make | |
61 | sure the strings are properly NUL-terminated. | |
62 | * - __u8 | |
63 | - ``card``\ [32] | |
64 | - Name of the device, a NUL-terminated UTF-8 string. For example: | |
65 | "Yoyodyne TV/FM". One driver may support different brands or | |
66 | models of video hardware. This information is intended for users, | |
67 | for example in a menu of available devices. Since multiple TV | |
68 | cards of the same brand may be installed which are supported by | |
69 | the same driver, this name should be combined with the character | |
70 | device file name (e. g. ``/dev/video2``) or the ``bus_info`` | |
71 | string to avoid ambiguities. | |
72 | * - __u8 | |
73 | - ``bus_info``\ [32] | |
74 | - Location of the device in the system, a NUL-terminated ASCII | |
75 | string. For example: "PCI:0000:05:06.0". This information is | |
76 | intended for users, to distinguish multiple identical devices. If | |
77 | no such information is available the field must simply count the | |
78 | devices controlled by the driver ("platform:vivi-000"). The | |
79 | bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI | |
80 | Express boards, "usb-" for USB devices, "I2C:" for i2c devices, | |
81 | "ISA:" for ISA devices, "parport" for parallel port devices and | |
82 | "platform:" for platform devices. | |
83 | * - __u32 | |
84 | - ``version`` | |
85 | - Version number of the driver. | |
86 | ||
87 | Starting with kernel 3.1, the version reported is provided by the | |
88 | V4L2 subsystem following the kernel numbering scheme. However, it | |
89 | may not always return the same version as the kernel if, for | |
90 | example, a stable or distribution-modified kernel uses the V4L2 | |
91 | stack from a newer kernel. | |
92 | ||
93 | The version number is formatted using the ``KERNEL_VERSION()`` | |
94 | macro: | |
95 | * - :cspan:`2` | |
96 | ||
97 | ``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))`` | |
98 | ||
99 | ``__u32 version = KERNEL_VERSION(0, 8, 1);`` | |
100 | ||
101 | ``printf ("Version: %u.%u.%u\\n",`` | |
102 | ||
103 | ``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);`` | |
104 | * - __u32 | |
105 | - ``capabilities`` | |
106 | - Available capabilities of the physical device as a whole, see | |
107 | :ref:`device-capabilities`. The same physical device can export | |
108 | multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and | |
109 | /dev/radioZ). The ``capabilities`` field should contain a union of | |
110 | all capabilities available around the several V4L2 devices | |
111 | exported to userspace. For all those devices the ``capabilities`` | |
112 | field returns the same set of capabilities. This allows | |
113 | applications to open just one of the devices (typically the video | |
114 | device) and discover whether video, vbi and/or radio are also | |
115 | supported. | |
116 | * - __u32 | |
117 | - ``device_caps`` | |
118 | - Device capabilities of the opened device, see | |
119 | :ref:`device-capabilities`. Should contain the available | |
120 | capabilities of that specific device node. So, for example, | |
121 | ``device_caps`` of a radio device will only contain radio related | |
122 | capabilities and no video or vbi capabilities. This field is only | |
123 | set if the ``capabilities`` field contains the | |
124 | ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities`` | |
125 | field can have the ``V4L2_CAP_DEVICE_CAPS`` capability, | |
126 | ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``. | |
127 | * - __u32 | |
128 | - ``reserved``\ [3] | |
129 | - Reserved for future extensions. Drivers must set this array to | |
130 | zero. | |
5377d91f MH |
131 | |
132 | ||
133 | ||
48f69937 MCC |
134 | .. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}| |
135 | ||
fa92b04d MCC |
136 | .. _device-capabilities: |
137 | ||
48f69937 MCC |
138 | .. cssclass:: longtable |
139 | ||
5377d91f MH |
140 | .. flat-table:: Device Capabilities Flags |
141 | :header-rows: 0 | |
142 | :stub-columns: 0 | |
143 | :widths: 3 1 4 | |
144 | ||
c2b66caf LP |
145 | * - ``V4L2_CAP_VIDEO_CAPTURE`` |
146 | - 0x00000001 | |
147 | - The device supports the single-planar API through the | |
148 | :ref:`Video Capture <capture>` interface. | |
149 | * - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` | |
150 | - 0x00001000 | |
151 | - The device supports the :ref:`multi-planar API <planar-apis>` | |
152 | through the :ref:`Video Capture <capture>` interface. | |
153 | * - ``V4L2_CAP_VIDEO_OUTPUT`` | |
154 | - 0x00000002 | |
155 | - The device supports the single-planar API through the | |
156 | :ref:`Video Output <output>` interface. | |
157 | * - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` | |
158 | - 0x00002000 | |
159 | - The device supports the :ref:`multi-planar API <planar-apis>` | |
160 | through the :ref:`Video Output <output>` interface. | |
161 | * - ``V4L2_CAP_VIDEO_M2M`` | |
162 | - 0x00004000 | |
163 | - The device supports the single-planar API through the Video | |
164 | Memory-To-Memory interface. | |
165 | * - ``V4L2_CAP_VIDEO_M2M_MPLANE`` | |
166 | - 0x00008000 | |
167 | - The device supports the :ref:`multi-planar API <planar-apis>` | |
168 | through the Video Memory-To-Memory interface. | |
169 | * - ``V4L2_CAP_VIDEO_OVERLAY`` | |
170 | - 0x00000004 | |
171 | - The device supports the :ref:`Video Overlay <overlay>` | |
172 | interface. A video overlay device typically stores captured images | |
173 | directly in the video memory of a graphics card, with hardware | |
174 | clipping and scaling. | |
175 | * - ``V4L2_CAP_VBI_CAPTURE`` | |
176 | - 0x00000010 | |
177 | - The device supports the :ref:`Raw VBI Capture <raw-vbi>` | |
178 | interface, providing Teletext and Closed Caption data. | |
179 | * - ``V4L2_CAP_VBI_OUTPUT`` | |
180 | - 0x00000020 | |
181 | - The device supports the :ref:`Raw VBI Output <raw-vbi>` | |
182 | interface. | |
183 | * - ``V4L2_CAP_SLICED_VBI_CAPTURE`` | |
184 | - 0x00000040 | |
185 | - The device supports the :ref:`Sliced VBI Capture <sliced>` | |
186 | interface. | |
187 | * - ``V4L2_CAP_SLICED_VBI_OUTPUT`` | |
188 | - 0x00000080 | |
189 | - The device supports the :ref:`Sliced VBI Output <sliced>` | |
190 | interface. | |
191 | * - ``V4L2_CAP_RDS_CAPTURE`` | |
192 | - 0x00000100 | |
193 | - The device supports the :ref:`RDS <rds>` capture interface. | |
194 | * - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` | |
195 | - 0x00000200 | |
196 | - The device supports the :ref:`Video Output Overlay <osd>` (OSD) | |
197 | interface. Unlike the *Video Overlay* interface, this is a | |
198 | secondary function of video output devices and overlays an image | |
199 | onto an outgoing video signal. When the driver sets this flag, it | |
200 | must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice | |
201 | versa. [#f1]_ | |
202 | * - ``V4L2_CAP_HW_FREQ_SEEK`` | |
203 | - 0x00000400 | |
204 | - The device supports the | |
205 | :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl | |
206 | for hardware frequency seeking. | |
207 | * - ``V4L2_CAP_RDS_OUTPUT`` | |
208 | - 0x00000800 | |
209 | - The device supports the :ref:`RDS <rds>` output interface. | |
210 | * - ``V4L2_CAP_TUNER`` | |
211 | - 0x00010000 | |
212 | - The device has some sort of tuner to receive RF-modulated video | |
213 | signals. For more information about tuner programming see | |
214 | :ref:`tuner`. | |
215 | * - ``V4L2_CAP_AUDIO`` | |
216 | - 0x00020000 | |
217 | - The device has audio inputs or outputs. It may or may not support | |
218 | audio recording or playback, in PCM or compressed formats. PCM | |
219 | audio support must be implemented as ALSA or OSS interface. For | |
220 | more information on audio inputs and outputs see :ref:`audio`. | |
221 | * - ``V4L2_CAP_RADIO`` | |
222 | - 0x00040000 | |
223 | - This is a radio receiver. | |
224 | * - ``V4L2_CAP_MODULATOR`` | |
225 | - 0x00080000 | |
226 | - The device has some sort of modulator to emit RF-modulated | |
227 | video/audio signals. For more information about modulator | |
228 | programming see :ref:`tuner`. | |
229 | * - ``V4L2_CAP_SDR_CAPTURE`` | |
230 | - 0x00100000 | |
231 | - The device supports the :ref:`SDR Capture <sdr>` interface. | |
232 | * - ``V4L2_CAP_EXT_PIX_FORMAT`` | |
233 | - 0x00200000 | |
234 | - The device supports the struct | |
235 | :c:type:`v4l2_pix_format` extended fields. | |
236 | * - ``V4L2_CAP_SDR_OUTPUT`` | |
237 | - 0x00400000 | |
238 | - The device supports the :ref:`SDR Output <sdr>` interface. | |
fb9ffa6a LP |
239 | * - ``V4L2_CAP_META_CAPTURE`` |
240 | - 0x00800000 | |
241 | - The device supports the :ref:`metadata` capture interface. | |
c2b66caf LP |
242 | * - ``V4L2_CAP_READWRITE`` |
243 | - 0x01000000 | |
244 | - The device supports the :ref:`read() <rw>` and/or | |
245 | :ref:`write() <rw>` I/O methods. | |
246 | * - ``V4L2_CAP_ASYNCIO`` | |
247 | - 0x02000000 | |
248 | - The device supports the :ref:`asynchronous <async>` I/O methods. | |
249 | * - ``V4L2_CAP_STREAMING`` | |
250 | - 0x04000000 | |
251 | - The device supports the :ref:`streaming <mmap>` I/O method. | |
252 | * - ``V4L2_CAP_TOUCH`` | |
253 | - 0x10000000 | |
254 | - This is a touch device. | |
255 | * - ``V4L2_CAP_DEVICE_CAPS`` | |
256 | - 0x80000000 | |
257 | - The driver fills the ``device_caps`` field. This capability can | |
258 | only appear in the ``capabilities`` field and never in the | |
259 | ``device_caps`` field. | |
5377d91f MH |
260 | |
261 | ||
15e7d615 | 262 | Return Value |
5377d91f MH |
263 | ============ |
264 | ||
265 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
266 | appropriately. The generic error codes are described at the | |
267 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
268 | ||
4855307b | 269 | .. [#f1] |
e8be7e97 | 270 | The struct :c:type:`v4l2_framebuffer` lacks an |
56683d7d | 271 | enum :c:type:`v4l2_buf_type` field, therefore the |
5377d91f | 272 | type of overlay is implied by the driver capabilities. |