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