Documentation/userspace-api/media/v4l/vidioc-enuminput.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_ENUMINPUT:
   5
   6 **********************
   7 ioctl VIDIOC_ENUMINPUT
   8 **********************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_ENUMINPUT - Enumerate video inputs
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_ENUMINPUT
  19
  20 ``int ioctl(int fd, VIDIOC_ENUMINPUT, struct v4l2_input *argp)``
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :c:func:`open()`.
  27
  28 ``argp``
  29     Pointer to struct :c:type:`v4l2_input`.
  30
  31 Description
  32 ===========
  33
  34 To query the attributes of a video input applications initialize the
  35 ``index`` field of struct :c:type:`v4l2_input` and call the
  36 :ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
  37 fill the rest of the structure or return an ``EINVAL`` error code when the
  38 index is out of bounds. To enumerate all inputs applications shall begin
  39 at index zero, incrementing by one until the driver returns ``EINVAL``.
  40
  41 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  42
  43 .. c:type:: v4l2_input
  44
  45 .. flat-table:: struct v4l2_input
  46     :header-rows:  0
  47     :stub-columns: 0
  48     :widths:       1 1 2
  49
  50     * - __u32
  51       - ``index``
  52       - Identifies the input, set by the application.
  53     * - __u8
  54       - ``name``\ [32]
  55       - Name of the video input, a NUL-terminated ASCII string, for
  56         example: "Vin (Composite 2)". This information is intended for the
  57         user, preferably the connector label on the device itself.
  58     * - __u32
  59       - ``type``
  60       - Type of the input, see :ref:`input-type`.
  61     * - __u32
  62       - ``audioset``
  63       - Drivers can enumerate up to 32 video and audio inputs. This field
  64         shows which audio inputs were selectable as audio source if this
  65         was the currently selected video input. It is a bit mask. The LSB
  66         corresponds to audio input 0, the MSB to input 31. Any number of
  67         bits can be set, or none.
  68
  69         When the driver does not enumerate audio inputs no bits must be
  70         set. Applications shall not interpret this as lack of audio
  71         support. Some drivers automatically select audio sources and do
  72         not enumerate them since there is no choice anyway.
  73
  74         For details on audio inputs and how to select the current input
  75         see :ref:`audio`.
  76     * - __u32
  77       - ``tuner``
  78       - Capture devices can have zero or more tuners (RF demodulators).
  79         When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
  80         RF connector and this field identifies the tuner. It corresponds
  81         to struct :c:type:`v4l2_tuner` field ``index``. For
  82         details on tuners see :ref:`tuner`.
  83     * - :ref:`v4l2_std_id <v4l2-std-id>`
  84       - ``std``
  85       - Every video input supports one or more different video standards.
  86         This field is a set of all supported standards. For details on
  87         video standards and how to switch see :ref:`standard`.
  88     * - __u32
  89       - ``status``
  90       - This field provides status information about the input. See
  91         :ref:`input-status` for flags. With the exception of the sensor
  92         orientation bits ``status`` is only valid when this is the current
  93         input.
  94     * - __u32
  95       - ``capabilities``
  96       - This field provides capabilities for the input. See
  97         :ref:`input-capabilities` for flags.
  98     * - __u32
  99       - ``reserved``\ [3]
 100       - Reserved for future extensions. Drivers must set the array to
 101         zero.
 102
 103
 104 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 105
 106 .. _input-type:
 107
 108 .. flat-table:: Input Types
 109     :header-rows:  0
 110     :stub-columns: 0
 111     :widths:       3 1 4
 112
 113     * - ``V4L2_INPUT_TYPE_TUNER``
 114       - 1
 115       - This input uses a tuner (RF demodulator).
 116     * - ``V4L2_INPUT_TYPE_CAMERA``
 117       - 2
 118       - Any non-tuner video input, for example Composite Video,
 119         S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
 120         today we would have called it ``_TYPE_VIDEO``.
 121     * - ``V4L2_INPUT_TYPE_TOUCH``
 122       - 3
 123       - This input is a touch device for capturing raw touch data.
 124
 125
 126 .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
 127
 128 .. _input-status:
 129
 130 .. flat-table:: Input Status Flags
 131     :header-rows:  0
 132     :stub-columns: 0
 133
 134     * - :cspan:`2` General
 135     * - ``V4L2_IN_ST_NO_POWER``
 136       - 0x00000001
 137       - Attached device is off.
 138     * - ``V4L2_IN_ST_NO_SIGNAL``
 139       - 0x00000002
 140       -
 141     * - ``V4L2_IN_ST_NO_COLOR``
 142       - 0x00000004
 143       - The hardware supports color decoding, but does not detect color
 144         modulation in the signal.
 145     * - :cspan:`2` Sensor Orientation
 146     * - ``V4L2_IN_ST_HFLIP``
 147       - 0x00000010
 148       - The input is connected to a device that produces a signal that is
 149         flipped horizontally and does not correct this before passing the
 150         signal to userspace.
 151     * - ``V4L2_IN_ST_VFLIP``
 152       - 0x00000020
 153       - The input is connected to a device that produces a signal that is
 154         flipped vertically and does not correct this before passing the
 155         signal to userspace.
 156         .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
 157     * - :cspan:`2` Analog Video
 158     * - ``V4L2_IN_ST_NO_H_LOCK``
 159       - 0x00000100
 160       - No horizontal sync lock.
 161     * - ``V4L2_IN_ST_COLOR_KILL``
 162       - 0x00000200
 163       - A color killer circuit automatically disables color decoding when
 164         it detects no color modulation. When this flag is set the color
 165         killer is enabled *and* has shut off color decoding.
 166     * - ``V4L2_IN_ST_NO_V_LOCK``
 167       - 0x00000400
 168       - No vertical sync lock.
 169     * - ``V4L2_IN_ST_NO_STD_LOCK``
 170       - 0x00000800
 171       - No standard format lock in case of auto-detection format
 172         by the component.
 173     * - :cspan:`2` Digital Video
 174     * - ``V4L2_IN_ST_NO_SYNC``
 175       - 0x00010000
 176       - No synchronization lock.
 177     * - ``V4L2_IN_ST_NO_EQU``
 178       - 0x00020000
 179       - No equalizer lock.
 180     * - ``V4L2_IN_ST_NO_CARRIER``
 181       - 0x00040000
 182       - Carrier recovery failed.
 183     * - :cspan:`2` VCR and Set-Top Box
 184     * - ``V4L2_IN_ST_MACROVISION``
 185       - 0x01000000
 186       - Macrovision is an analog copy prevention system mangling the video
 187         signal to confuse video recorders. When this flag is set
 188         Macrovision has been detected.
 189     * - ``V4L2_IN_ST_NO_ACCESS``
 190       - 0x02000000
 191       - Conditional access denied.
 192     * - ``V4L2_IN_ST_VTR``
 193       - 0x04000000
 194       - VTR time constant. [?]
 195
 196
 197 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 198
 199 .. _input-capabilities:
 200
 201 .. flat-table:: Input capabilities
 202     :header-rows:  0
 203     :stub-columns: 0
 204     :widths:       3 1 4
 205
 206     * - ``V4L2_IN_CAP_DV_TIMINGS``
 207       - 0x00000002
 208       - This input supports setting video timings by using
 209         ``VIDIOC_S_DV_TIMINGS``.
 210     * - ``V4L2_IN_CAP_STD``
 211       - 0x00000004
 212       - This input supports setting the TV standard by using
 213         ``VIDIOC_S_STD``.
 214     * - ``V4L2_IN_CAP_NATIVE_SIZE``
 215       - 0x00000008
 216       - This input supports setting the native size using the
 217         ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 218         :ref:`v4l2-selections-common`.
 219
 220 Return Value
 221 ============
 222
 223 On success 0 is returned, on error -1 and the ``errno`` variable is set
 224 appropriately. The generic error codes are described at the
 225 :ref:`Generic Error Codes <gen-errors>` chapter.
 226
 227 EINVAL
 228     The struct :c:type:`v4l2_input` ``index`` is out of
 229     bounds.