Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/userspace-api/media/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_SUBDEV_QUERYCAP:
  11
  12 ****************************
  13 ioctl VIDIOC_SUBDEV_QUERYCAP
  14 ****************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp )
  26     :name: VIDIOC_SUBDEV_QUERYCAP
  27
  28
  29 Arguments
  30 =========
  31
  32 ``fd``
  33     File descriptor returned by :ref:`open() <func-open>`.
  34
  35 ``argp``
  36     Pointer to struct :c:type:`v4l2_subdev_capability`.
  37
  38
  39 Description
  40 ===========
  41
  42 All V4L2 sub-devices support the ``VIDIOC_SUBDEV_QUERYCAP`` ioctl. It is used to
  43 identify kernel devices compatible with this specification and to obtain
  44 information about driver and hardware capabilities. The ioctl takes a pointer to
  45 a struct :c:type:`v4l2_subdev_capability` which is filled by the driver. When
  46 the driver is not compatible with this specification the ioctl returns
  47 ``ENOTTY`` error code.
  48
  49 .. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}|
  50
  51 .. c:type:: v4l2_subdev_capability
  52
  53 .. flat-table:: struct v4l2_subdev_capability
  54     :header-rows:  0
  55     :stub-columns: 0
  56     :widths:       3 4 20
  57
  58     * - __u32
  59       - ``version``
  60       - Version number of the driver.
  61
  62         The version reported is provided by the V4L2 subsystem following the
  63         kernel numbering scheme. However, it may not always return the same
  64         version as the kernel if, for example, a stable or
  65         distribution-modified kernel uses the V4L2 stack from a newer kernel.
  66
  67         The version number is formatted using the ``KERNEL_VERSION()``
  68         macro:
  69     * - :cspan:`2`
  70
  71         ``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))``
  72
  73         ``__u32 version = KERNEL_VERSION(0, 8, 1);``
  74
  75         ``printf ("Version: %u.%u.%u\\n",``
  76
  77         ``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);``
  78     * - __u32
  79       - ``capabilities``
  80       - Sub-device capabilities of the opened device, see
  81         :ref:`subdevice-capabilities`.
  82     * - __u32
  83       - ``reserved``\ [14]
  84       - Reserved for future extensions. Set to 0 by the V4L2 core.
  85
  86 .. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}|
  87
  88 .. _subdevice-capabilities:
  89
  90 .. cssclass:: longtable
  91
  92 .. flat-table:: Sub-Device Capabilities Flags
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       3 1 4
  96
  97     * - V4L2_SUBDEV_CAP_RO_SUBDEV
  98       - 0x00000001
  99       - The sub-device device node is registered in read-only mode.
 100         Access to the sub-device ioctls that modify the device state is
 101         restricted. Refer to each individual subdevice ioctl documentation
 102         for a description of which restrictions apply to a read-only sub-device.
 103
 104 Return Value
 105 ============
 106
 107 On success 0 is returned, on error -1 and the ``errno`` variable is set
 108 appropriately. The generic error codes are described at the
 109 :ref:`Generic Error Codes <gen-errors>` chapter.
 110
 111 ENOTTY
 112     The device node is not a V4L2 sub-device.