Documentation/media/uapi/v4l/vidioc-enuminput.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUMINPUT:
   4
   5 **********************
   6 ioctl VIDIOC_ENUMINPUT
   7 **********************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_ENUMINPUT - Enumerate video inputs
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_ENUMINPUT
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 To query the attributes of a video input applications initialize the
  37 ``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
  38 :ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
  39 fill the rest of the structure or return an ``EINVAL`` error code when the
  40 index is out of bounds. To enumerate all inputs applications shall begin
  41 at index zero, incrementing by one until the driver returns ``EINVAL``.
  42
  43
  44 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  45
  46 .. _v4l2-input:
  47
  48 .. flat-table:: struct v4l2_input
  49     :header-rows:  0
  50     :stub-columns: 0
  51     :widths:       1 1 2
  52
  53
  54     -  .. row 1
  55
  56        -  __u32
  57
  58        -  ``index``
  59
  60        -  Identifies the input, set by the application.
  61
  62     -  .. row 2
  63
  64        -  __u8
  65
  66        -  ``name``\ [32]
  67
  68        -  Name of the video input, a NUL-terminated ASCII string, for
  69           example: "Vin (Composite 2)". This information is intended for the
  70           user, preferably the connector label on the device itself.
  71
  72     -  .. row 3
  73
  74        -  __u32
  75
  76        -  ``type``
  77
  78        -  Type of the input, see :ref:`input-type`.
  79
  80     -  .. row 4
  81
  82        -  __u32
  83
  84        -  ``audioset``
  85
  86        -  Drivers can enumerate up to 32 video and audio inputs. This field
  87           shows which audio inputs were selectable as audio source if this
  88           was the currently selected video input. It is a bit mask. The LSB
  89           corresponds to audio input 0, the MSB to input 31. Any number of
  90           bits can be set, or none.
  91
  92           When the driver does not enumerate audio inputs no bits must be
  93           set. Applications shall not interpret this as lack of audio
  94           support. Some drivers automatically select audio sources and do
  95           not enumerate them since there is no choice anyway.
  96
  97           For details on audio inputs and how to select the current input
  98           see :ref:`audio`.
  99
 100     -  .. row 5
 101
 102        -  __u32
 103
 104        -  ``tuner``
 105
 106        -  Capture devices can have zero or more tuners (RF demodulators).
 107           When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
 108           RF connector and this field identifies the tuner. It corresponds
 109           to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
 110           details on tuners see :ref:`tuner`.
 111
 112     -  .. row 6
 113
 114        -  :ref:`v4l2_std_id <v4l2-std-id>`
 115
 116        -  ``std``
 117
 118        -  Every video input supports one or more different video standards.
 119           This field is a set of all supported standards. For details on
 120           video standards and how to switch see :ref:`standard`.
 121
 122     -  .. row 7
 123
 124        -  __u32
 125
 126        -  ``status``
 127
 128        -  This field provides status information about the input. See
 129           :ref:`input-status` for flags. With the exception of the sensor
 130           orientation bits ``status`` is only valid when this is the current
 131           input.
 132
 133     -  .. row 8
 134
 135        -  __u32
 136
 137        -  ``capabilities``
 138
 139        -  This field provides capabilities for the input. See
 140           :ref:`input-capabilities` for flags.
 141
 142     -  .. row 9
 143
 144        -  __u32
 145
 146        -  ``reserved``\ [3]
 147
 148        -  Reserved for future extensions. Drivers must set the array to
 149           zero.
 150
 151
 152
 153 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 154
 155 .. _input-type:
 156
 157 .. flat-table:: Input Types
 158     :header-rows:  0
 159     :stub-columns: 0
 160     :widths:       3 1 4
 161
 162
 163     -  .. row 1
 164
 165        -  ``V4L2_INPUT_TYPE_TUNER``
 166
 167        -  1
 168
 169        -  This input uses a tuner (RF demodulator).
 170
 171     -  .. row 2
 172
 173        -  ``V4L2_INPUT_TYPE_CAMERA``
 174
 175        -  2
 176
 177        -  Analog baseband input, for example CVBS / Composite Video,
 178           S-Video, RGB.
 179
 180
 181
 182 .. tabularcolumns:: |p{4.8cm}|p{2.6cm}|p{10.1cm}|
 183
 184 .. _input-status:
 185
 186 .. flat-table:: Input Status Flags
 187     :header-rows:  0
 188     :stub-columns: 0
 189
 190
 191     -  .. row 1
 192
 193        -  :cspan:`2` General
 194
 195     -  .. row 2
 196
 197        -  ``V4L2_IN_ST_NO_POWER``
 198
 199        -  0x00000001
 200
 201        -  Attached device is off.
 202
 203     -  .. row 3
 204
 205        -  ``V4L2_IN_ST_NO_SIGNAL``
 206
 207        -  0x00000002
 208
 209        -
 210
 211     -  .. row 4
 212
 213        -  ``V4L2_IN_ST_NO_COLOR``
 214
 215        -  0x00000004
 216
 217        -  The hardware supports color decoding, but does not detect color
 218           modulation in the signal.
 219
 220     -  .. row 5
 221
 222        -  :cspan:`2` Sensor Orientation
 223
 224     -  .. row 6
 225
 226        -  ``V4L2_IN_ST_HFLIP``
 227
 228        -  0x00000010
 229
 230        -  The input is connected to a device that produces a signal that is
 231           flipped horizontally and does not correct this before passing the
 232           signal to userspace.
 233
 234     -  .. row 7
 235
 236        -  ``V4L2_IN_ST_VFLIP``
 237
 238        -  0x00000020
 239
 240        -  The input is connected to a device that produces a signal that is
 241           flipped vertically and does not correct this before passing the
 242           signal to userspace.
 243           .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
 244
 245     -  .. row 8
 246
 247        -  :cspan:`2` Analog Video
 248
 249     -  .. row 9
 250
 251        -  ``V4L2_IN_ST_NO_H_LOCK``
 252
 253        -  0x00000100
 254
 255        -  No horizontal sync lock.
 256
 257     -  .. row 10
 258
 259        -  ``V4L2_IN_ST_COLOR_KILL``
 260
 261        -  0x00000200
 262
 263        -  A color killer circuit automatically disables color decoding when
 264           it detects no color modulation. When this flag is set the color
 265           killer is enabled *and* has shut off color decoding.
 266
 267     -  .. row 11
 268
 269        -  :cspan:`2` Digital Video
 270
 271     -  .. row 12
 272
 273        -  ``V4L2_IN_ST_NO_SYNC``
 274
 275        -  0x00010000
 276
 277        -  No synchronization lock.
 278
 279     -  .. row 13
 280
 281        -  ``V4L2_IN_ST_NO_EQU``
 282
 283        -  0x00020000
 284
 285        -  No equalizer lock.
 286
 287     -  .. row 14
 288
 289        -  ``V4L2_IN_ST_NO_CARRIER``
 290
 291        -  0x00040000
 292
 293        -  Carrier recovery failed.
 294
 295     -  .. row 15
 296
 297        -  :cspan:`2` VCR and Set-Top Box
 298
 299     -  .. row 16
 300
 301        -  ``V4L2_IN_ST_MACROVISION``
 302
 303        -  0x01000000
 304
 305        -  Macrovision is an analog copy prevention system mangling the video
 306           signal to confuse video recorders. When this flag is set
 307           Macrovision has been detected.
 308
 309     -  .. row 17
 310
 311        -  ``V4L2_IN_ST_NO_ACCESS``
 312
 313        -  0x02000000
 314
 315        -  Conditional access denied.
 316
 317     -  .. row 18
 318
 319        -  ``V4L2_IN_ST_VTR``
 320
 321        -  0x04000000
 322
 323        -  VTR time constant. [?]
 324
 325
 326
 327 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 328
 329 .. _input-capabilities:
 330
 331 .. flat-table:: Input capabilities
 332     :header-rows:  0
 333     :stub-columns: 0
 334     :widths:       3 1 4
 335
 336
 337     -  .. row 1
 338
 339        -  ``V4L2_IN_CAP_DV_TIMINGS``
 340
 341        -  0x00000002
 342
 343        -  This input supports setting video timings by using
 344           VIDIOC_S_DV_TIMINGS.
 345
 346     -  .. row 2
 347
 348        -  ``V4L2_IN_CAP_STD``
 349
 350        -  0x00000004
 351
 352        -  This input supports setting the TV standard by using
 353           VIDIOC_S_STD.
 354
 355     -  .. row 3
 356
 357        -  ``V4L2_IN_CAP_NATIVE_SIZE``
 358
 359        -  0x00000008
 360
 361        -  This input supports setting the native size using the
 362           ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
 363           :ref:`v4l2-selections-common`.
 364
 365
 366 Return Value
 367 ============
 368
 369 On success 0 is returned, on error -1 and the ``errno`` variable is set
 370 appropriately. The generic error codes are described at the
 371 :ref:`Generic Error Codes <gen-errors>` chapter.
 372
 373 EINVAL
 374     The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
 375     bounds.