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, 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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  72
  73 .. _v4l2-bt-timings:
  74
  75 .. flat-table:: struct v4l2_bt_timings
  76     :header-rows:  0
  77     :stub-columns: 0
  78     :widths:       1 1 2
  79
  80
  81     -  .. row 1
  82
  83        -  __u32
  84
  85        -  ``width``
  86
  87        -  Width of the active video in pixels.
  88
  89     -  .. row 2
  90
  91        -  __u32
  92
  93        -  ``height``
  94
  95        -  Height of the active video frame in lines. So for interlaced
  96           formats the height of the active video in each field is
  97           ``height``/2.
  98
  99     -  .. row 3
 100
 101        -  __u32
 102
 103        -  ``interlaced``
 104
 105        -  Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
 106
 107     -  .. row 4
 108
 109        -  __u32
 110
 111        -  ``polarities``
 112
 113        -  This is a bit mask that defines polarities of sync signals. bit 0
 114           (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
 115           1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
 116           the bit is set (1) it is positive polarity and if is cleared (0),
 117           it is negative polarity.
 118
 119     -  .. row 5
 120
 121        -  __u64
 122
 123        -  ``pixelclock``
 124
 125        -  Pixel clock in Hz. Ex. 74.25MHz->74250000
 126
 127     -  .. row 6
 128
 129        -  __u32
 130
 131        -  ``hfrontporch``
 132
 133        -  Horizontal front porch in pixels
 134
 135     -  .. row 7
 136
 137        -  __u32
 138
 139        -  ``hsync``
 140
 141        -  Horizontal sync length in pixels
 142
 143     -  .. row 8
 144
 145        -  __u32
 146
 147        -  ``hbackporch``
 148
 149        -  Horizontal back porch in pixels
 150
 151     -  .. row 9
 152
 153        -  __u32
 154
 155        -  ``vfrontporch``
 156
 157        -  Vertical front porch in lines. For interlaced formats this refers
 158           to the odd field (aka field 1).
 159
 160     -  .. row 10
 161
 162        -  __u32
 163
 164        -  ``vsync``
 165
 166        -  Vertical sync length in lines. For interlaced formats this refers
 167           to the odd field (aka field 1).
 168
 169     -  .. row 11
 170
 171        -  __u32
 172
 173        -  ``vbackporch``
 174
 175        -  Vertical back porch in lines. For interlaced formats this refers
 176           to the odd field (aka field 1).
 177
 178     -  .. row 12
 179
 180        -  __u32
 181
 182        -  ``il_vfrontporch``
 183
 184        -  Vertical front porch in lines for the even field (aka field 2) of
 185           interlaced field formats. Must be 0 for progressive formats.
 186
 187     -  .. row 13
 188
 189        -  __u32
 190
 191        -  ``il_vsync``
 192
 193        -  Vertical sync length in lines for the even field (aka field 2) of
 194           interlaced field formats. Must be 0 for progressive formats.
 195
 196     -  .. row 14
 197
 198        -  __u32
 199
 200        -  ``il_vbackporch``
 201
 202        -  Vertical back porch in lines for the even field (aka field 2) of
 203           interlaced field formats. Must be 0 for progressive formats.
 204
 205     -  .. row 15
 206
 207        -  __u32
 208
 209        -  ``standards``
 210
 211        -  The video standard(s) this format belongs to. This will be filled
 212           in by the driver. Applications must set this to 0. See
 213           :ref:`dv-bt-standards` for a list of standards.
 214
 215     -  .. row 16
 216
 217        -  __u32
 218
 219        -  ``flags``
 220
 221        -  Several flags giving more information about the format. See
 222           :ref:`dv-bt-flags` for a description of the flags.
 223
 224
 225
 226 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
 227
 228 .. _v4l2-dv-timings:
 229
 230 .. flat-table:: struct v4l2_dv_timings
 231     :header-rows:  0
 232     :stub-columns: 0
 233     :widths:       1 1 2 1
 234
 235
 236     -  .. row 1
 237
 238        -  __u32
 239
 240        -  ``type``
 241
 242        -
 243        -  Type of DV timings as listed in :ref:`dv-timing-types`.
 244
 245     -  .. row 2
 246
 247        -  union
 248
 249        -
 250        -
 251
 252     -  .. row 3
 253
 254        -
 255        -  struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
 256
 257        -  ``bt``
 258
 259        -  Timings defined by BT.656/1120 specifications
 260
 261     -  .. row 4
 262
 263        -
 264        -  __u32
 265
 266        -  ``reserved``\ [32]
 267
 268        -
 269
 270 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 271
 272 .. _dv-timing-types:
 273
 274 .. flat-table:: DV Timing types
 275     :header-rows:  0
 276     :stub-columns: 0
 277     :widths:       1 1 2
 278
 279
 280     -  .. row 1
 281
 282        -  Timing type
 283
 284        -  value
 285
 286        -  Description
 287
 288     -  .. row 2
 289
 290        -
 291        -
 292        -
 293
 294     -  .. row 3
 295
 296        -  ``V4L2_DV_BT_656_1120``
 297
 298        -  0
 299
 300        -  BT.656/1120 timings
 301
 302
 303
 304 .. _dv-bt-standards:
 305
 306 .. flat-table:: DV BT Timing standards
 307     :header-rows:  0
 308     :stub-columns: 0
 309
 310
 311     -  .. row 1
 312
 313        -  Timing standard
 314
 315        -  Description
 316
 317     -  .. row 3
 318
 319        -  ``V4L2_DV_BT_STD_CEA861``
 320
 321        -  The timings follow the CEA-861 Digital TV Profile standard
 322
 323     -  .. row 4
 324
 325        -  ``V4L2_DV_BT_STD_DMT``
 326
 327        -  The timings follow the VESA Discrete Monitor Timings standard
 328
 329     -  .. row 5
 330
 331        -  ``V4L2_DV_BT_STD_CVT``
 332
 333        -  The timings follow the VESA Coordinated Video Timings standard
 334
 335     -  .. row 6
 336
 337        -  ``V4L2_DV_BT_STD_GTF``
 338
 339        -  The timings follow the VESA Generalized Timings Formula standard
 340
 341
 342 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
 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 3
 358
 359        -  ``V4L2_DV_FL_REDUCED_BLANKING``
 360
 361        -  CVT/GTF specific: the timings use reduced blanking (CVT) or the
 362           'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 363           vertical blanking intervals are reduced, allowing a higher
 364           resolution over the same bandwidth. This is a read-only flag,
 365           applications must not set this.
 366
 367     -  .. row 4
 368
 369        -  ``V4L2_DV_FL_CAN_REDUCE_FPS``
 370
 371        -  CEA-861 specific: set for CEA-861 formats with a framerate that is
 372           a multiple of six. These formats can be optionally played at 1 /
 373           1.001 speed to be compatible with 60 Hz based standards such as
 374           NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 375           the transmitter can't generate such frequencies, then the flag
 376           will also be cleared. This is a read-only flag, applications must
 377           not set this.
 378
 379     -  .. row 5
 380
 381        -  ``V4L2_DV_FL_REDUCED_FPS``
 382
 383        -  CEA-861 specific: only valid for video transmitters, the flag is
 384           cleared by receivers. It is also only valid for formats with the
 385           ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 386           flag will be cleared by the driver. If the application sets this
 387           flag, then the pixelclock used to set up the transmitter is
 388           divided by 1.001 to make it compatible with NTSC framerates. If
 389           the transmitter can't generate such frequencies, then the flag
 390           will also be cleared.
 391
 392     -  .. row 6
 393
 394        -  ``V4L2_DV_FL_HALF_LINE``
 395
 396        -  Specific to interlaced formats: if set, then the vertical
 397           frontporch of field 1 (aka the odd field) is really one half-line
 398           longer and the vertical backporch of field 2 (aka the even field)
 399           is really one half-line shorter, so each field has exactly the
 400           same number of half-lines. Whether half-lines can be detected or
 401           used depends on the hardware.
 402
 403     -  .. row 7
 404
 405        -  ``V4L2_DV_FL_IS_CE_VIDEO``
 406
 407        -  If set, then this is a Consumer Electronics (CE) video format.
 408           Such formats differ from other formats (commonly called IT
 409           formats) in that if R'G'B' encoding is used then by default the
 410           R'G'B' values use limited range (i.e. 16-235) as opposed to full
 411           range (i.e. 0-255). All formats defined in CEA-861 except for the
 412           640x480p59.94 format are CE formats.