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