Documentation/media/uapi/v4l/vidioc-querycap.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_QUERYCAP:
   4
   5 *********************
   6 ioctl VIDIOC_QUERYCAP
   7 *********************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_QUERYCAP - Query device capabilities
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_QUERYCAP
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
  37 identify kernel devices compatible with this specification and to obtain
  38 information about driver and hardware capabilities. The ioctl takes a
  39 pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is
  40 filled by the driver. When the driver is not compatible with this
  41 specification the ioctl returns an ``EINVAL`` error code.
  42
  43
  44 .. _v4l2-capability:
  45
  46 .. flat-table:: struct v4l2_capability
  47     :header-rows:  0
  48     :stub-columns: 0
  49     :widths:       1 1 2
  50
  51
  52     -  .. row 1
  53
  54        -  __u8
  55
  56        -  ``driver``\ [16]
  57
  58        -  Name of the driver, a unique NUL-terminated ASCII string. For
  59           example: "bttv". Driver specific applications can use this
  60           information to verify the driver identity. It is also useful to
  61           work around known bugs, or to identify drivers in error reports.
  62
  63           Storing strings in fixed sized arrays is bad practice but
  64           unavoidable here. Drivers and applications should take precautions
  65           to never read or write beyond the end of the array and to make
  66           sure the strings are properly NUL-terminated.
  67
  68     -  .. row 2
  69
  70        -  __u8
  71
  72        -  ``card``\ [32]
  73
  74        -  Name of the device, a NUL-terminated UTF-8 string. For example:
  75           "Yoyodyne TV/FM". One driver may support different brands or
  76           models of video hardware. This information is intended for users,
  77           for example in a menu of available devices. Since multiple TV
  78           cards of the same brand may be installed which are supported by
  79           the same driver, this name should be combined with the character
  80           device file name (e. g. ``/dev/video2``) or the ``bus_info``
  81           string to avoid ambiguities.
  82
  83     -  .. row 3
  84
  85        -  __u8
  86
  87        -  ``bus_info``\ [32]
  88
  89        -  Location of the device in the system, a NUL-terminated ASCII
  90           string. For example: "PCI:0000:05:06.0". This information is
  91           intended for users, to distinguish multiple identical devices. If
  92           no such information is available the field must simply count the
  93           devices controlled by the driver ("platform:vivi-000"). The
  94           bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
  95           Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
  96           "ISA:" for ISA devices, "parport" for parallel port devices and
  97           "platform:" for platform devices.
  98
  99     -  .. row 4
 100
 101        -  __u32
 102
 103        -  ``version``
 104
 105        -  Version number of the driver.
 106
 107           Starting with kernel 3.1, the version reported is provided by the
 108           V4L2 subsystem following the kernel numbering scheme. However, it
 109           may not always return the same version as the kernel if, for
 110           example, a stable or distribution-modified kernel uses the V4L2
 111           stack from a newer kernel.
 112
 113           The version number is formatted using the ``KERNEL_VERSION()``
 114           macro:
 115
 116     -  .. row 5
 117
 118        -  :cspan:`2`
 119
 120
 121           .. code-block:: c
 122
 123               #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
 124
 125               __u32 version = KERNEL_VERSION(0, 8, 1);
 126
 127               printf ("Version: %u.%u.%u\\n",
 128                   (version >> 16) & 0xFF,
 129                   (version >> 8) & 0xFF,
 130                    version & 0xFF);
 131
 132     -  .. row 6
 133
 134        -  __u32
 135
 136        -  ``capabilities``
 137
 138        -  Available capabilities of the physical device as a whole, see
 139           :ref:`device-capabilities`. The same physical device can export
 140           multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
 141           /dev/radioZ). The ``capabilities`` field should contain a union of
 142           all capabilities available around the several V4L2 devices
 143           exported to userspace. For all those devices the ``capabilities``
 144           field returns the same set of capabilities. This allows
 145           applications to open just one of the devices (typically the video
 146           device) and discover whether video, vbi and/or radio are also
 147           supported.
 148
 149     -  .. row 7
 150
 151        -  __u32
 152
 153        -  ``device_caps``
 154
 155        -  Device capabilities of the opened device, see
 156           :ref:`device-capabilities`. Should contain the available
 157           capabilities of that specific device node. So, for example,
 158           ``device_caps`` of a radio device will only contain radio related
 159           capabilities and no video or vbi capabilities. This field is only
 160           set if the ``capabilities`` field contains the
 161           ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
 162           field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
 163           ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
 164
 165     -  .. row 8
 166
 167        -  __u32
 168
 169        -  ``reserved``\ [3]
 170
 171        -  Reserved for future extensions. Drivers must set this array to
 172           zero.
 173
 174
 175
 176 .. _device-capabilities:
 177
 178 .. flat-table:: Device Capabilities Flags
 179     :header-rows:  0
 180     :stub-columns: 0
 181     :widths:       3 1 4
 182
 183
 184     -  .. row 1
 185
 186        -  ``V4L2_CAP_VIDEO_CAPTURE``
 187
 188        -  0x00000001
 189
 190        -  The device supports the single-planar API through the
 191           :ref:`Video Capture <capture>` interface.
 192
 193     -  .. row 2
 194
 195        -  ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
 196
 197        -  0x00001000
 198
 199        -  The device supports the :ref:`multi-planar API <planar-apis>`
 200           through the :ref:`Video Capture <capture>` interface.
 201
 202     -  .. row 3
 203
 204        -  ``V4L2_CAP_VIDEO_OUTPUT``
 205
 206        -  0x00000002
 207
 208        -  The device supports the single-planar API through the
 209           :ref:`Video Output <output>` interface.
 210
 211     -  .. row 4
 212
 213        -  ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
 214
 215        -  0x00002000
 216
 217        -  The device supports the :ref:`multi-planar API <planar-apis>`
 218           through the :ref:`Video Output <output>` interface.
 219
 220     -  .. row 5
 221
 222        -  ``V4L2_CAP_VIDEO_M2M``
 223
 224        -  0x00004000
 225
 226        -  The device supports the single-planar API through the Video
 227           Memory-To-Memory interface.
 228
 229     -  .. row 6
 230
 231        -  ``V4L2_CAP_VIDEO_M2M_MPLANE``
 232
 233        -  0x00008000
 234
 235        -  The device supports the :ref:`multi-planar API <planar-apis>`
 236           through the Video Memory-To-Memory interface.
 237
 238     -  .. row 7
 239
 240        -  ``V4L2_CAP_VIDEO_OVERLAY``
 241
 242        -  0x00000004
 243
 244        -  The device supports the :ref:`Video Overlay <overlay>`
 245           interface. A video overlay device typically stores captured images
 246           directly in the video memory of a graphics card, with hardware
 247           clipping and scaling.
 248
 249     -  .. row 8
 250
 251        -  ``V4L2_CAP_VBI_CAPTURE``
 252
 253        -  0x00000010
 254
 255        -  The device supports the :ref:`Raw VBI Capture <raw-vbi>`
 256           interface, providing Teletext and Closed Caption data.
 257
 258     -  .. row 9
 259
 260        -  ``V4L2_CAP_VBI_OUTPUT``
 261
 262        -  0x00000020
 263
 264        -  The device supports the :ref:`Raw VBI Output <raw-vbi>`
 265           interface.
 266
 267     -  .. row 10
 268
 269        -  ``V4L2_CAP_SLICED_VBI_CAPTURE``
 270
 271        -  0x00000040
 272
 273        -  The device supports the :ref:`Sliced VBI Capture <sliced>`
 274           interface.
 275
 276     -  .. row 11
 277
 278        -  ``V4L2_CAP_SLICED_VBI_OUTPUT``
 279
 280        -  0x00000080
 281
 282        -  The device supports the :ref:`Sliced VBI Output <sliced>`
 283           interface.
 284
 285     -  .. row 12
 286
 287        -  ``V4L2_CAP_RDS_CAPTURE``
 288
 289        -  0x00000100
 290
 291        -  The device supports the :ref:`RDS <rds>` capture interface.
 292
 293     -  .. row 13
 294
 295        -  ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
 296
 297        -  0x00000200
 298
 299        -  The device supports the :ref:`Video Output Overlay <osd>` (OSD)
 300           interface. Unlike the *Video Overlay* interface, this is a
 301           secondary function of video output devices and overlays an image
 302           onto an outgoing video signal. When the driver sets this flag, it
 303           must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
 304           versa. [#f1]_
 305
 306     -  .. row 14
 307
 308        -  ``V4L2_CAP_HW_FREQ_SEEK``
 309
 310        -  0x00000400
 311
 312        -  The device supports the
 313           :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
 314           for hardware frequency seeking.
 315
 316     -  .. row 15
 317
 318        -  ``V4L2_CAP_RDS_OUTPUT``
 319
 320        -  0x00000800
 321
 322        -  The device supports the :ref:`RDS <rds>` output interface.
 323
 324     -  .. row 16
 325
 326        -  ``V4L2_CAP_TUNER``
 327
 328        -  0x00010000
 329
 330        -  The device has some sort of tuner to receive RF-modulated video
 331           signals. For more information about tuner programming see
 332           :ref:`tuner`.
 333
 334     -  .. row 17
 335
 336        -  ``V4L2_CAP_AUDIO``
 337
 338        -  0x00020000
 339
 340        -  The device has audio inputs or outputs. It may or may not support
 341           audio recording or playback, in PCM or compressed formats. PCM
 342           audio support must be implemented as ALSA or OSS interface. For
 343           more information on audio inputs and outputs see :ref:`audio`.
 344
 345     -  .. row 18
 346
 347        -  ``V4L2_CAP_RADIO``
 348
 349        -  0x00040000
 350
 351        -  This is a radio receiver.
 352
 353     -  .. row 19
 354
 355        -  ``V4L2_CAP_MODULATOR``
 356
 357        -  0x00080000
 358
 359        -  The device has some sort of modulator to emit RF-modulated
 360           video/audio signals. For more information about modulator
 361           programming see :ref:`tuner`.
 362
 363     -  .. row 20
 364
 365        -  ``V4L2_CAP_SDR_CAPTURE``
 366
 367        -  0x00100000
 368
 369        -  The device supports the :ref:`SDR Capture <sdr>` interface.
 370
 371     -  .. row 21
 372
 373        -  ``V4L2_CAP_EXT_PIX_FORMAT``
 374
 375        -  0x00200000
 376
 377        -  The device supports the struct
 378           :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields.
 379
 380     -  .. row 22
 381
 382        -  ``V4L2_CAP_SDR_OUTPUT``
 383
 384        -  0x00400000
 385
 386        -  The device supports the :ref:`SDR Output <sdr>` interface.
 387
 388     -  .. row 23
 389
 390        -  ``V4L2_CAP_READWRITE``
 391
 392        -  0x01000000
 393
 394        -  The device supports the :ref:`read() <rw>` and/or
 395           :ref:`write() <rw>` I/O methods.
 396
 397     -  .. row 24
 398
 399        -  ``V4L2_CAP_ASYNCIO``
 400
 401        -  0x02000000
 402
 403        -  The device supports the :ref:`asynchronous <async>` I/O methods.
 404
 405     -  .. row 25
 406
 407        -  ``V4L2_CAP_STREAMING``
 408
 409        -  0x04000000
 410
 411        -  The device supports the :ref:`streaming <mmap>` I/O method.
 412
 413     -  .. row 26
 414
 415        -  ``V4L2_CAP_DEVICE_CAPS``
 416
 417        -  0x80000000
 418
 419        -  The driver fills the ``device_caps`` field. This capability can
 420           only appear in the ``capabilities`` field and never in the
 421           ``device_caps`` field.
 422
 423
 424 Return Value
 425 ============
 426
 427 On success 0 is returned, on error -1 and the ``errno`` variable is set
 428 appropriately. The generic error codes are described at the
 429 :ref:`Generic Error Codes <gen-errors>` chapter.
 430
 431 .. [#f1]
 432    The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
 433    enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
 434    type of overlay is implied by the driver capabilities.