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 .. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}|
  45
  46 .. _v4l2-capability:
  47
  48 .. flat-table:: struct v4l2_capability
  49     :header-rows:  0
  50     :stub-columns: 0
  51     :widths:       3 4 20
  52
  53     -  .. row 1
  54
  55        -  __u8
  56
  57        -  ``driver``\ [16]
  58
  59        -  Name of the driver, a unique NUL-terminated ASCII string. For
  60           example: "bttv". Driver specific applications can use this
  61           information to verify the driver identity. It is also useful to
  62           work around known bugs, or to identify drivers in error reports.
  63
  64           Storing strings in fixed sized arrays is bad practice but
  65           unavoidable here. Drivers and applications should take precautions
  66           to never read or write beyond the end of the array and to make
  67           sure the strings are properly NUL-terminated.
  68
  69     -  .. row 2
  70
  71        -  __u8
  72
  73        -  ``card``\ [32]
  74
  75        -  Name of the device, a NUL-terminated UTF-8 string. For example:
  76           "Yoyodyne TV/FM". One driver may support different brands or
  77           models of video hardware. This information is intended for users,
  78           for example in a menu of available devices. Since multiple TV
  79           cards of the same brand may be installed which are supported by
  80           the same driver, this name should be combined with the character
  81           device file name (e. g. ``/dev/video2``) or the ``bus_info``
  82           string to avoid ambiguities.
  83
  84     -  .. row 3
  85
  86        -  __u8
  87
  88        -  ``bus_info``\ [32]
  89
  90        -  Location of the device in the system, a NUL-terminated ASCII
  91           string. For example: "PCI:0000:05:06.0". This information is
  92           intended for users, to distinguish multiple identical devices. If
  93           no such information is available the field must simply count the
  94           devices controlled by the driver ("platform:vivi-000"). The
  95           bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
  96           Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
  97           "ISA:" for ISA devices, "parport" for parallel port devices and
  98           "platform:" for platform devices.
  99
 100     -  .. row 4
 101
 102        -  __u32
 103
 104        -  ``version``
 105
 106        -  Version number of the driver.
 107
 108           Starting with kernel 3.1, the version reported is provided by the
 109           V4L2 subsystem following the kernel numbering scheme. However, it
 110           may not always return the same version as the kernel if, for
 111           example, a stable or distribution-modified kernel uses the V4L2
 112           stack from a newer kernel.
 113
 114           The version number is formatted using the ``KERNEL_VERSION()``
 115           macro:
 116
 117     -  .. row 5
 118
 119        -  :cspan:`2`
 120
 121           ``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))``
 122
 123           ``__u32 version = KERNEL_VERSION(0, 8, 1);``
 124
 125           ``printf ("Version: %u.%u.%u\\n",``
 126
 127           ``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);``
 128
 129     -  .. row 6
 130
 131        -  __u32
 132
 133        -  ``capabilities``
 134
 135        -  Available capabilities of the physical device as a whole, see
 136           :ref:`device-capabilities`. The same physical device can export
 137           multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
 138           /dev/radioZ). The ``capabilities`` field should contain a union of
 139           all capabilities available around the several V4L2 devices
 140           exported to userspace. For all those devices the ``capabilities``
 141           field returns the same set of capabilities. This allows
 142           applications to open just one of the devices (typically the video
 143           device) and discover whether video, vbi and/or radio are also
 144           supported.
 145
 146     -  .. row 7
 147
 148        -  __u32
 149
 150        -  ``device_caps``
 151
 152        -  Device capabilities of the opened device, see
 153           :ref:`device-capabilities`. Should contain the available
 154           capabilities of that specific device node. So, for example,
 155           ``device_caps`` of a radio device will only contain radio related
 156           capabilities and no video or vbi capabilities. This field is only
 157           set if the ``capabilities`` field contains the
 158           ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
 159           field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
 160           ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
 161
 162     -  .. row 8
 163
 164        -  __u32
 165
 166        -  ``reserved``\ [3]
 167
 168        -  Reserved for future extensions. Drivers must set this array to
 169           zero.
 170
 171
 172
 173 .. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}|
 174
 175 .. _device-capabilities:
 176
 177 .. cssclass:: longtable
 178
 179 .. flat-table:: Device Capabilities Flags
 180     :header-rows:  0
 181     :stub-columns: 0
 182     :widths:       3 1 4
 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.