Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_DV_TIMINGS:
   4
   5 **********************************************
   6 ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
   7 **********************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
  29     VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37 To set DV timings for the input or output, applications use the
  38 :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
  39 applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
  40 information is filled in using the structure struct
  41 :ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
  42 pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
  43 structure as argument. If the ioctl is not supported or the timing
  44 values are not correct, the driver returns ``EINVAL`` error code.
  45
  46 The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
  47 the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
  48 the current input or output does not support DV timings (e.g. if
  49 :ref:`VIDIOC_ENUMINPUT` does not set the
  50 ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
  51
  52
  53 Return Value
  54 ============
  55
  56 On success 0 is returned, on error -1 and the ``errno`` variable is set
  57 appropriately. The generic error codes are described at the
  58 :ref:`Generic Error Codes <gen-errors>` chapter.
  59
  60 EINVAL
  61     This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
  62     parameter was unsuitable.
  63
  64 ENODATA
  65     Digital video timings are not supported for this input or output.
  66
  67 EBUSY
  68     The device is busy and therefore can not change the timings.
  69
  70
  71 .. _v4l2-bt-timings:
  72
  73 .. flat-table:: struct v4l2_bt_timings
  74     :header-rows:  0
  75     :stub-columns: 0
  76     :widths:       1 1 2
  77
  78
  79     -  .. row 1
  80
  81        -  __u32
  82
  83        -  ``width``
  84
  85        -  Width of the active video in pixels.
  86
  87     -  .. row 2
  88
  89        -  __u32
  90
  91        -  ``height``
  92
  93        -  Height of the active video frame in lines. So for interlaced
  94           formats the height of the active video in each field is
  95           ``height``/2.
  96
  97     -  .. row 3
  98
  99        -  __u32
 100
 101        -  ``interlaced``
 102
 103        -  Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
 104
 105     -  .. row 4
 106
 107        -  __u32
 108
 109        -  ``polarities``
 110
 111        -  This is a bit mask that defines polarities of sync signals. bit 0
 112           (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
 113           1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
 114           the bit is set (1) it is positive polarity and if is cleared (0),
 115           it is negative polarity.
 116
 117     -  .. row 5
 118
 119        -  __u64
 120
 121        -  ``pixelclock``
 122
 123        -  Pixel clock in Hz. Ex. 74.25MHz->74250000
 124
 125     -  .. row 6
 126
 127        -  __u32
 128
 129        -  ``hfrontporch``
 130
 131        -  Horizontal front porch in pixels
 132
 133     -  .. row 7
 134
 135        -  __u32
 136
 137        -  ``hsync``
 138
 139        -  Horizontal sync length in pixels
 140
 141     -  .. row 8
 142
 143        -  __u32
 144
 145        -  ``hbackporch``
 146
 147        -  Horizontal back porch in pixels
 148
 149     -  .. row 9
 150
 151        -  __u32
 152
 153        -  ``vfrontporch``
 154
 155        -  Vertical front porch in lines. For interlaced formats this refers
 156           to the odd field (aka field 1).
 157
 158     -  .. row 10
 159
 160        -  __u32
 161
 162        -  ``vsync``
 163
 164        -  Vertical sync length in lines. For interlaced formats this refers
 165           to the odd field (aka field 1).
 166
 167     -  .. row 11
 168
 169        -  __u32
 170
 171        -  ``vbackporch``
 172
 173        -  Vertical back porch in lines. For interlaced formats this refers
 174           to the odd field (aka field 1).
 175
 176     -  .. row 12
 177
 178        -  __u32
 179
 180        -  ``il_vfrontporch``
 181
 182        -  Vertical front porch in lines for the even field (aka field 2) of
 183           interlaced field formats. Must be 0 for progressive formats.
 184
 185     -  .. row 13
 186
 187        -  __u32
 188
 189        -  ``il_vsync``
 190
 191        -  Vertical sync length in lines for the even field (aka field 2) of
 192           interlaced field formats. Must be 0 for progressive formats.
 193
 194     -  .. row 14
 195
 196        -  __u32
 197
 198        -  ``il_vbackporch``
 199
 200        -  Vertical back porch in lines for the even field (aka field 2) of
 201           interlaced field formats. Must be 0 for progressive formats.
 202
 203     -  .. row 15
 204
 205        -  __u32
 206
 207        -  ``standards``
 208
 209        -  The video standard(s) this format belongs to. This will be filled
 210           in by the driver. Applications must set this to 0. See
 211           :ref:`dv-bt-standards` for a list of standards.
 212
 213     -  .. row 16
 214
 215        -  __u32
 216
 217        -  ``flags``
 218
 219        -  Several flags giving more information about the format. See
 220           :ref:`dv-bt-flags` for a description of the flags.
 221
 222
 223
 224 .. _v4l2-dv-timings:
 225
 226 .. flat-table:: struct v4l2_dv_timings
 227     :header-rows:  0
 228     :stub-columns: 0
 229     :widths:       1 1 2 1
 230
 231
 232     -  .. row 1
 233
 234        -  __u32
 235
 236        -  ``type``
 237
 238        -
 239        -  Type of DV timings as listed in :ref:`dv-timing-types`.
 240
 241     -  .. row 2
 242
 243        -  union
 244
 245        -
 246        -
 247
 248     -  .. row 3
 249
 250        -
 251        -  struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
 252
 253        -  ``bt``
 254
 255        -  Timings defined by BT.656/1120 specifications
 256
 257     -  .. row 4
 258
 259        -
 260        -  __u32
 261
 262        -  ``reserved``\ [32]
 263
 264        -
 265
 266
 267
 268 .. _dv-timing-types:
 269
 270 .. flat-table:: DV Timing types
 271     :header-rows:  0
 272     :stub-columns: 0
 273     :widths:       1 1 2
 274
 275
 276     -  .. row 1
 277
 278        -  Timing type
 279
 280        -  value
 281
 282        -  Description
 283
 284     -  .. row 2
 285
 286        -
 287        -
 288        -
 289
 290     -  .. row 3
 291
 292        -  ``V4L2_DV_BT_656_1120``
 293
 294        -  0
 295
 296        -  BT.656/1120 timings
 297
 298
 299
 300 .. _dv-bt-standards:
 301
 302 .. flat-table:: DV BT Timing standards
 303     :header-rows:  0
 304     :stub-columns: 0
 305
 306
 307     -  .. row 1
 308
 309        -  Timing standard
 310
 311        -  Description
 312
 313     -  .. row 2
 314
 315        -
 316        -
 317
 318     -  .. row 3
 319
 320        -  ``V4L2_DV_BT_STD_CEA861``
 321
 322        -  The timings follow the CEA-861 Digital TV Profile standard
 323
 324     -  .. row 4
 325
 326        -  ``V4L2_DV_BT_STD_DMT``
 327
 328        -  The timings follow the VESA Discrete Monitor Timings standard
 329
 330     -  .. row 5
 331
 332        -  ``V4L2_DV_BT_STD_CVT``
 333
 334        -  The timings follow the VESA Coordinated Video Timings standard
 335
 336     -  .. row 6
 337
 338        -  ``V4L2_DV_BT_STD_GTF``
 339
 340        -  The timings follow the VESA Generalized Timings Formula standard
 341
 342
 343
 344 .. _dv-bt-flags:
 345
 346 .. flat-table:: DV BT Timing flags
 347     :header-rows:  0
 348     :stub-columns: 0
 349
 350
 351     -  .. row 1
 352
 353        -  Flag
 354
 355        -  Description
 356
 357     -  .. row 2
 358
 359        -
 360        -
 361
 362     -  .. row 3
 363
 364        -  ``V4L2_DV_FL_REDUCED_BLANKING``
 365
 366        -  CVT/GTF specific: the timings use reduced blanking (CVT) or the
 367           'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 368           vertical blanking intervals are reduced, allowing a higher
 369           resolution over the same bandwidth. This is a read-only flag,
 370           applications must not set this.
 371
 372     -  .. row 4
 373
 374        -  ``V4L2_DV_FL_CAN_REDUCE_FPS``
 375
 376        -  CEA-861 specific: set for CEA-861 formats with a framerate that is
 377           a multiple of six. These formats can be optionally played at 1 /
 378           1.001 speed to be compatible with 60 Hz based standards such as
 379           NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 380           the transmitter can't generate such frequencies, then the flag
 381           will also be cleared. This is a read-only flag, applications must
 382           not set this.
 383
 384     -  .. row 5
 385
 386        -  ``V4L2_DV_FL_REDUCED_FPS``
 387
 388        -  CEA-861 specific: only valid for video transmitters, the flag is
 389           cleared by receivers. It is also only valid for formats with the
 390           ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 391           flag will be cleared by the driver. If the application sets this
 392           flag, then the pixelclock used to set up the transmitter is
 393           divided by 1.001 to make it compatible with NTSC framerates. If
 394           the transmitter can't generate such frequencies, then the flag
 395           will also be cleared.
 396
 397     -  .. row 6
 398
 399        -  ``V4L2_DV_FL_HALF_LINE``
 400
 401        -  Specific to interlaced formats: if set, then the vertical
 402           frontporch of field 1 (aka the odd field) is really one half-line
 403           longer and the vertical backporch of field 2 (aka the even field)
 404           is really one half-line shorter, so each field has exactly the
 405           same number of half-lines. Whether half-lines can be detected or
 406           used depends on the hardware.
 407
 408     -  .. row 7
 409
 410        -  ``V4L2_DV_FL_IS_CE_VIDEO``
 411
 412        -  If set, then this is a Consumer Electronics (CE) video format.
 413           Such formats differ from other formats (commonly called IT
 414           formats) in that if R'G'B' encoding is used then by default the
 415           R'G'B' values use limited range (i.e. 16-235) as opposed to full
 416           range (i.e. 0-255). All formats defined in CEA-861 except for the
 417           640x480p59.94 format are CE formats.