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