Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 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 | *man VIDIOC_G_DV_TIMINGS(2)* |
| 10 | |
| 11 | VIDIOC_S_DV_TIMINGS |
| 12 | VIDIOC_SUBDEV_G_DV_TIMINGS |
| 13 | VIDIOC_SUBDEV_S_DV_TIMINGS |
| 14 | Get or set DV timings for input or output |
| 15 | |
| 16 | |
| 17 | Synopsis |
| 18 | ======== |
| 19 | |
| 20 | .. c:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp ) |
| 21 | |
| 22 | Arguments |
| 23 | ========= |
| 24 | |
| 25 | ``fd`` |
| 26 | File descriptor returned by :ref:`open() <func-open>`. |
| 27 | |
| 28 | ``request`` |
| 29 | VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS, |
| 30 | VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS |
| 31 | |
| 32 | ``argp`` |
| 33 | |
| 34 | |
| 35 | Description |
| 36 | =========== |
| 37 | |
| 38 | To set DV timings for the input or output, applications use the |
| 39 | ``VIDIOC_S_DV_TIMINGS`` ioctl and to get the current timings, |
| 40 | applications use the ``VIDIOC_G_DV_TIMINGS`` ioctl. The detailed timing |
| 41 | information is filled in using the structure struct |
| 42 | :ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a |
| 43 | pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>` |
| 44 | structure as argument. If the ioctl is not supported or the timing |
| 45 | values are not correct, the driver returns EINVAL error code. |
| 46 | |
| 47 | The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of |
| 48 | the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If |
| 49 | the current input or output does not support DV timings (e.g. if |
| 50 | :ref:`VIDIOC_ENUMINPUT <vidioc-enuminput>` does not set the |
| 51 | ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ENODATA error code is returned. |
| 52 | |
| 53 | |
| 54 | Return Value |
| 55 | ============ |
| 56 | |
| 57 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 58 | appropriately. The generic error codes are described at the |
| 59 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 60 | |
| 61 | EINVAL |
| 62 | This ioctl is not supported, or the ``VIDIOC_S_DV_TIMINGS`` |
| 63 | parameter was unsuitable. |
| 64 | |
| 65 | ENODATA |
| 66 | Digital video timings are not supported for this input or output. |
| 67 | |
| 68 | EBUSY |
| 69 | The device is busy and therefore can not change the timings. |
| 70 | |
| 71 | |
| 72 | .. _v4l2-bt-timings: |
| 73 | |
| 74 | .. flat-table:: struct v4l2_bt_timings |
| 75 | :header-rows: 0 |
| 76 | :stub-columns: 0 |
| 77 | :widths: 1 1 2 |
| 78 | |
| 79 | |
| 80 | - .. row 1 |
| 81 | |
| 82 | - __u32 |
| 83 | |
| 84 | - ``width`` |
| 85 | |
| 86 | - Width of the active video in pixels. |
| 87 | |
| 88 | - .. row 2 |
| 89 | |
| 90 | - __u32 |
| 91 | |
| 92 | - ``height`` |
| 93 | |
| 94 | - Height of the active video frame in lines. So for interlaced |
| 95 | formats the height of the active video in each field is |
| 96 | ``height``/2. |
| 97 | |
| 98 | - .. row 3 |
| 99 | |
| 100 | - __u32 |
| 101 | |
| 102 | - ``interlaced`` |
| 103 | |
| 104 | - Progressive (0) or interlaced (1) |
| 105 | |
| 106 | - .. row 4 |
| 107 | |
| 108 | - __u32 |
| 109 | |
| 110 | - ``polarities`` |
| 111 | |
| 112 | - This is a bit mask that defines polarities of sync signals. bit 0 |
| 113 | (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit |
| 114 | 1 (V4L2_DV_HSYNC_POS_POL) is for horizontal sync polarity. If |
| 115 | the bit is set (1) it is positive polarity and if is cleared (0), |
| 116 | it is negative polarity. |
| 117 | |
| 118 | - .. row 5 |
| 119 | |
| 120 | - __u64 |
| 121 | |
| 122 | - ``pixelclock`` |
| 123 | |
| 124 | - Pixel clock in Hz. Ex. 74.25MHz->74250000 |
| 125 | |
| 126 | - .. row 6 |
| 127 | |
| 128 | - __u32 |
| 129 | |
| 130 | - ``hfrontporch`` |
| 131 | |
| 132 | - Horizontal front porch in pixels |
| 133 | |
| 134 | - .. row 7 |
| 135 | |
| 136 | - __u32 |
| 137 | |
| 138 | - ``hsync`` |
| 139 | |
| 140 | - Horizontal sync length in pixels |
| 141 | |
| 142 | - .. row 8 |
| 143 | |
| 144 | - __u32 |
| 145 | |
| 146 | - ``hbackporch`` |
| 147 | |
| 148 | - Horizontal back porch in pixels |
| 149 | |
| 150 | - .. row 9 |
| 151 | |
| 152 | - __u32 |
| 153 | |
| 154 | - ``vfrontporch`` |
| 155 | |
| 156 | - Vertical front porch in lines. For interlaced formats this refers |
| 157 | to the odd field (aka field 1). |
| 158 | |
| 159 | - .. row 10 |
| 160 | |
| 161 | - __u32 |
| 162 | |
| 163 | - ``vsync`` |
| 164 | |
| 165 | - Vertical sync length in lines. For interlaced formats this refers |
| 166 | to the odd field (aka field 1). |
| 167 | |
| 168 | - .. row 11 |
| 169 | |
| 170 | - __u32 |
| 171 | |
| 172 | - ``vbackporch`` |
| 173 | |
| 174 | - Vertical back porch in lines. For interlaced formats this refers |
| 175 | to the odd field (aka field 1). |
| 176 | |
| 177 | - .. row 12 |
| 178 | |
| 179 | - __u32 |
| 180 | |
| 181 | - ``il_vfrontporch`` |
| 182 | |
| 183 | - Vertical front porch in lines for the even field (aka field 2) of |
| 184 | interlaced field formats. Must be 0 for progressive formats. |
| 185 | |
| 186 | - .. row 13 |
| 187 | |
| 188 | - __u32 |
| 189 | |
| 190 | - ``il_vsync`` |
| 191 | |
| 192 | - Vertical sync length in lines for the even field (aka field 2) of |
| 193 | interlaced field formats. Must be 0 for progressive formats. |
| 194 | |
| 195 | - .. row 14 |
| 196 | |
| 197 | - __u32 |
| 198 | |
| 199 | - ``il_vbackporch`` |
| 200 | |
| 201 | - Vertical back porch in lines for the even field (aka field 2) of |
| 202 | interlaced field formats. Must be 0 for progressive formats. |
| 203 | |
| 204 | - .. row 15 |
| 205 | |
| 206 | - __u32 |
| 207 | |
| 208 | - ``standards`` |
| 209 | |
| 210 | - The video standard(s) this format belongs to. This will be filled |
| 211 | in by the driver. Applications must set this to 0. See |
| 212 | :ref:`dv-bt-standards` for a list of standards. |
| 213 | |
| 214 | - .. row 16 |
| 215 | |
| 216 | - __u32 |
| 217 | |
| 218 | - ``flags`` |
| 219 | |
| 220 | - Several flags giving more information about the format. See |
| 221 | :ref:`dv-bt-flags` for a description of the flags. |
| 222 | |
| 223 | |
| 224 | |
| 225 | .. _v4l2-dv-timings: |
| 226 | |
| 227 | .. flat-table:: struct v4l2_dv_timings |
| 228 | :header-rows: 0 |
| 229 | :stub-columns: 0 |
| 230 | :widths: 1 1 2 1 |
| 231 | |
| 232 | |
| 233 | - .. row 1 |
| 234 | |
| 235 | - __u32 |
| 236 | |
| 237 | - ``type`` |
| 238 | |
| 239 | - |
| 240 | - Type of DV timings as listed in :ref:`dv-timing-types`. |
| 241 | |
| 242 | - .. row 2 |
| 243 | |
| 244 | - union |
| 245 | |
| 246 | - |
| 247 | - |
| 248 | |
| 249 | - .. row 3 |
| 250 | |
| 251 | - |
| 252 | - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>` |
| 253 | |
| 254 | - ``bt`` |
| 255 | |
| 256 | - Timings defined by BT.656/1120 specifications |
| 257 | |
| 258 | - .. row 4 |
| 259 | |
| 260 | - |
| 261 | - __u32 |
| 262 | |
| 263 | - ``reserved``\ [32] |
| 264 | |
| 265 | - |
| 266 | |
| 267 | |
| 268 | |
| 269 | .. _dv-timing-types: |
| 270 | |
| 271 | .. flat-table:: DV Timing types |
| 272 | :header-rows: 0 |
| 273 | :stub-columns: 0 |
| 274 | :widths: 1 1 2 |
| 275 | |
| 276 | |
| 277 | - .. row 1 |
| 278 | |
| 279 | - Timing type |
| 280 | |
| 281 | - value |
| 282 | |
| 283 | - Description |
| 284 | |
| 285 | - .. row 2 |
| 286 | |
| 287 | - |
| 288 | - |
| 289 | - |
| 290 | |
| 291 | - .. row 3 |
| 292 | |
| 293 | - V4L2_DV_BT_656_1120 |
| 294 | |
| 295 | - 0 |
| 296 | |
| 297 | - BT.656/1120 timings |
| 298 | |
| 299 | |
| 300 | |
| 301 | .. _dv-bt-standards: |
| 302 | |
| 303 | .. flat-table:: DV BT Timing standards |
| 304 | :header-rows: 0 |
| 305 | :stub-columns: 0 |
| 306 | |
| 307 | |
| 308 | - .. row 1 |
| 309 | |
| 310 | - Timing standard |
| 311 | |
| 312 | - Description |
| 313 | |
| 314 | - .. row 2 |
| 315 | |
| 316 | - |
| 317 | - |
| 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 | |
| 345 | .. _dv-bt-flags: |
| 346 | |
| 347 | .. flat-table:: DV BT Timing flags |
| 348 | :header-rows: 0 |
| 349 | :stub-columns: 0 |
| 350 | |
| 351 | |
| 352 | - .. row 1 |
| 353 | |
| 354 | - Flag |
| 355 | |
| 356 | - Description |
| 357 | |
| 358 | - .. row 2 |
| 359 | |
| 360 | - |
| 361 | - |
| 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. |
| 419 | |
| 420 | |
| 421 | |
| 422 | |
| 423 | .. ------------------------------------------------------------------------------ |
| 424 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 425 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 426 | .. from the linux kernel, refer to: |
| 427 | .. |
| 428 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 429 | .. ------------------------------------------------------------------------------ |