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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _vidioc-querycap:
   4
   5 *********************
   6 ioctl VIDIOC_QUERYCAP
   7 *********************
   8
   9 *man VIDIOC_QUERYCAP(2)*
  10
  11 Query device capabilities
  12
  13
  14 Synopsis
  15 ========
  16
  17 .. c:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
  18
  19 Arguments
  20 =========
  21
  22 ``fd``
  23     File descriptor returned by :ref:`open() <func-open>`.
  24
  25 ``request``
  26     VIDIOC_QUERYCAP
  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 .. _v4l2-capability:
  43
  44 .. flat-table:: struct v4l2_capability
  45     :header-rows:  0
  46     :stub-columns: 0
  47     :widths:       1 1 2
  48
  49
  50     -  .. row 1
  51
  52        -  __u8
  53
  54        -  ``driver``\ [16]
  55
  56        -  Name of the driver, a unique NUL-terminated ASCII string. For
  57           example: "bttv". Driver specific applications can use this
  58           information to verify the driver identity. It is also useful to
  59           work around known bugs, or to identify drivers in error reports.
  60
  61           Storing strings in fixed sized arrays is bad practice but
  62           unavoidable here. Drivers and applications should take precautions
  63           to never read or write beyond the end of the array and to make
  64           sure the strings are properly NUL-terminated.
  65
  66     -  .. row 2
  67
  68        -  __u8
  69
  70        -  ``card``\ [32]
  71
  72        -  Name of the device, a NUL-terminated UTF-8 string. For example:
  73           "Yoyodyne TV/FM". One driver may support different brands or
  74           models of video hardware. This information is intended for users,
  75           for example in a menu of available devices. Since multiple TV
  76           cards of the same brand may be installed which are supported by
  77           the same driver, this name should be combined with the character
  78           device file name (e. g. ``/dev/video2``) or the ``bus_info``
  79           string to avoid ambiguities.
  80
  81     -  .. row 3
  82
  83        -  __u8
  84
  85        -  ``bus_info``\ [32]
  86
  87        -  Location of the device in the system, a NUL-terminated ASCII
  88           string. For example: "PCI:0000:05:06.0". This information is
  89           intended for users, to distinguish multiple identical devices. If
  90           no such information is available the field must simply count the
  91           devices controlled by the driver ("platform:vivi-000"). The
  92           bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
  93           Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
  94           "ISA:" for ISA devices, "parport" for parallel port devices and
  95           "platform:" for platform devices.
  96
  97     -  .. row 4
  98
  99        -  __u32
 100
 101        -  ``version``
 102
 103        -  Version number of the driver.
 104
 105           Starting with kernel 3.1, the version reported is provided by the
 106           V4L2 subsystem following the kernel numbering scheme. However, it
 107           may not always return the same version as the kernel if, for
 108           example, a stable or distribution-modified kernel uses the V4L2
 109           stack from a newer kernel.
 110
 111           The version number is formatted using the ``KERNEL_VERSION()``
 112           macro:
 113
 114     -  .. row 5
 115
 116        -  :cspan:`2`
 117
 118
 119           .. code-block:: c
 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                   (version >> 16) & 0xFF,
 127                   (version >> 8) & 0xFF,
 128                    version & 0xFF);
 129
 130     -  .. row 6
 131
 132        -  __u32
 133
 134        -  ``capabilities``
 135
 136        -  Available capabilities of the physical device as a whole, see
 137           :ref:`device-capabilities`. The same physical device can export
 138           multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
 139           /dev/radioZ). The ``capabilities`` field should contain a union of
 140           all capabilities available around the several V4L2 devices
 141           exported to userspace. For all those devices the ``capabilities``
 142           field returns the same set of capabilities. This allows
 143           applications to open just one of the devices (typically the video
 144           device) and discover whether video, vbi and/or radio are also
 145           supported.
 146
 147     -  .. row 7
 148
 149        -  __u32
 150
 151        -  ``device_caps``
 152
 153        -  Device capabilities of the opened device, see
 154           :ref:`device-capabilities`. Should contain the available
 155           capabilities of that specific device node. So, for example,
 156           ``device_caps`` of a radio device will only contain radio related
 157           capabilities and no video or vbi capabilities. This field is only
 158           set if the ``capabilities`` field contains the
 159           ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
 160           field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
 161           ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
 162
 163     -  .. row 8
 164
 165        -  __u32
 166
 167        -  ``reserved``\ [3]
 168
 169        -  Reserved for future extensions. Drivers must set this array to
 170           zero.
 171
 172
 173
 174 .. _device-capabilities:
 175
 176 .. flat-table:: Device Capabilities Flags
 177     :header-rows:  0
 178     :stub-columns: 0
 179     :widths:       3 1 4
 180
 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. [1]_
 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 <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
 423 Return Value
 424 ============
 425
 426 On success 0 is returned, on error -1 and the ``errno`` variable is set
 427 appropriately. The generic error codes are described at the
 428 :ref:`Generic Error Codes <gen-errors>` chapter.
 429
 430 .. [1]
 431    The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
 432    enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
 433    type of overlay is implied by the driver capabilities.
 434
 435
 436 .. ------------------------------------------------------------------------------
 437 .. This file was automatically converted from DocBook-XML with the dbxml
 438 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 439 .. from the linux kernel, refer to:
 440 ..
 441 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 442 .. ------------------------------------------------------------------------------