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 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  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 .. _v4l2-dv-timings:
 227
 228 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
 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
 271
 272 .. _dv-timing-types:
 273
 274 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 275
 276 .. flat-table:: DV Timing types
 277     :header-rows:  0
 278     :stub-columns: 0
 279     :widths:       1 1 2
 280
 281
 282     -  .. row 1
 283
 284        -  Timing type
 285
 286        -  value
 287
 288        -  Description
 289
 290     -  .. row 2
 291
 292        -
 293        -
 294        -
 295
 296     -  .. row 3
 297
 298        -  ``V4L2_DV_BT_656_1120``
 299
 300        -  0
 301
 302        -  BT.656/1120 timings
 303
 304
 305
 306 .. _dv-bt-standards:
 307
 308 .. flat-table:: DV BT Timing standards
 309     :header-rows:  0
 310     :stub-columns: 0
 311
 312
 313     -  .. row 1
 314
 315        -  Timing standard
 316
 317        -  Description
 318
 319     -  .. row 3
 320
 321        -  ``V4L2_DV_BT_STD_CEA861``
 322
 323        -  The timings follow the CEA-861 Digital TV Profile standard
 324
 325     -  .. row 4
 326
 327        -  ``V4L2_DV_BT_STD_DMT``
 328
 329        -  The timings follow the VESA Discrete Monitor Timings standard
 330
 331     -  .. row 5
 332
 333        -  ``V4L2_DV_BT_STD_CVT``
 334
 335        -  The timings follow the VESA Coordinated Video Timings standard
 336
 337     -  .. row 6
 338
 339        -  ``V4L2_DV_BT_STD_GTF``
 340
 341        -  The timings follow the VESA Generalized Timings Formula standard
 342
 343
 344 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
 345
 346 .. _dv-bt-flags:
 347
 348 .. flat-table:: DV BT Timing flags
 349     :header-rows:  0
 350     :stub-columns: 0
 351
 352
 353     -  .. row 1
 354
 355        -  Flag
 356
 357        -  Description
 358
 359     -  .. row 3
 360
 361        -  ``V4L2_DV_FL_REDUCED_BLANKING``
 362
 363        -  CVT/GTF specific: the timings use reduced blanking (CVT) or the
 364           'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 365           vertical blanking intervals are reduced, allowing a higher
 366           resolution over the same bandwidth. This is a read-only flag,
 367           applications must not set this.
 368
 369     -  .. row 4
 370
 371        -  ``V4L2_DV_FL_CAN_REDUCE_FPS``
 372
 373        -  CEA-861 specific: set for CEA-861 formats with a framerate that is
 374           a multiple of six. These formats can be optionally played at 1 /
 375           1.001 speed to be compatible with 60 Hz based standards such as
 376           NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 377           the transmitter can't generate such frequencies, then the flag
 378           will also be cleared. This is a read-only flag, applications must
 379           not set this.
 380
 381     -  .. row 5
 382
 383        -  ``V4L2_DV_FL_REDUCED_FPS``
 384
 385        -  CEA-861 specific: only valid for video transmitters, the flag is
 386           cleared by receivers. It is also only valid for formats with the
 387           ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 388           flag will be cleared by the driver. If the application sets this
 389           flag, then the pixelclock used to set up the transmitter is
 390           divided by 1.001 to make it compatible with NTSC framerates. If
 391           the transmitter can't generate such frequencies, then the flag
 392           will also be cleared.
 393
 394     -  .. row 6
 395
 396        -  ``V4L2_DV_FL_HALF_LINE``
 397
 398        -  Specific to interlaced formats: if set, then the vertical
 399           frontporch of field 1 (aka the odd field) is really one half-line
 400           longer and the vertical backporch of field 2 (aka the even field)
 401           is really one half-line shorter, so each field has exactly the
 402           same number of half-lines. Whether half-lines can be detected or
 403           used depends on the hardware.
 404
 405     -  .. row 7
 406
 407        -  ``V4L2_DV_FL_IS_CE_VIDEO``
 408
 409        -  If set, then this is a Consumer Electronics (CE) video format.
 410           Such formats differ from other formats (commonly called IT
 411           formats) in that if R'G'B' encoding is used then by default the
 412           R'G'B' values use limited range (i.e. 16-235) as opposed to full
 413           range (i.e. 0-255). All formats defined in CEA-861 except for the
 414           640x480p59.94 format are CE formats.