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