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