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