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     * - __u32
  87       - ``width``
  88       - Width of the active video in pixels.
  89     * - __u32
  90       - ``height``
  91       - Height of the active video frame in lines. So for interlaced
  92         formats the height of the active video in each field is
  93         ``height``/2.
  94     * - __u32
  95       - ``interlaced``
  96       - Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
  97     * - __u32
  98       - ``polarities``
  99       - This is a bit mask that defines polarities of sync signals. bit 0
 100         (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
 101         1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
 102         the bit is set (1) it is positive polarity and if is cleared (0),
 103         it is negative polarity.
 104     * - __u64
 105       - ``pixelclock``
 106       - Pixel clock in Hz. Ex. 74.25MHz->74250000
 107     * - __u32
 108       - ``hfrontporch``
 109       - Horizontal front porch in pixels
 110     * - __u32
 111       - ``hsync``
 112       - Horizontal sync length in pixels
 113     * - __u32
 114       - ``hbackporch``
 115       - Horizontal back porch in pixels
 116     * - __u32
 117       - ``vfrontporch``
 118       - Vertical front porch in lines. For interlaced formats this refers
 119         to the odd field (aka field 1).
 120     * - __u32
 121       - ``vsync``
 122       - Vertical sync length in lines. For interlaced formats this refers
 123         to the odd field (aka field 1).
 124     * - __u32
 125       - ``vbackporch``
 126       - Vertical back porch in lines. For interlaced formats this refers
 127         to the odd field (aka field 1).
 128     * - __u32
 129       - ``il_vfrontporch``
 130       - Vertical front porch in lines for the even field (aka field 2) of
 131         interlaced field formats. Must be 0 for progressive formats.
 132     * - __u32
 133       - ``il_vsync``
 134       - Vertical sync length in lines for the even field (aka field 2) of
 135         interlaced field formats. Must be 0 for progressive formats.
 136     * - __u32
 137       - ``il_vbackporch``
 138       - Vertical back porch in lines for the even field (aka field 2) of
 139         interlaced field formats. Must be 0 for progressive formats.
 140     * - __u32
 141       - ``standards``
 142       - The video standard(s) this format belongs to. This will be filled
 143         in by the driver. Applications must set this to 0. See
 144         :ref:`dv-bt-standards` for a list of standards.
 145     * - __u32
 146       - ``flags``
 147       - Several flags giving more information about the format. See
 148         :ref:`dv-bt-flags` for a description of the flags.
 149     * - __u32
 150       - ``reserved[14]``
 151       - Reserved for future extensions. Drivers and applications must set
 152         the array to zero.
 153
 154
 155 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
 156
 157 .. c:type:: v4l2_dv_timings
 158
 159 .. flat-table:: struct v4l2_dv_timings
 160     :header-rows:  0
 161     :stub-columns: 0
 162     :widths:       1 1 2 1
 163
 164     * - __u32
 165       - ``type``
 166       -
 167       - Type of DV timings as listed in :ref:`dv-timing-types`.
 168     * - union
 169       -
 170       -
 171     * -
 172       - struct :c:type:`v4l2_bt_timings`
 173       - ``bt``
 174       - Timings defined by BT.656/1120 specifications
 175     * -
 176       - __u32
 177       - ``reserved``\ [32]
 178       -
 179
 180 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 181
 182 .. _dv-timing-types:
 183
 184 .. flat-table:: DV Timing types
 185     :header-rows:  0
 186     :stub-columns: 0
 187     :widths:       1 1 2
 188
 189     * - Timing type
 190       - value
 191       - Description
 192     * -
 193       -
 194       -
 195     * - ``V4L2_DV_BT_656_1120``
 196       - 0
 197       - BT.656/1120 timings
 198
 199
 200
 201 .. _dv-bt-standards:
 202
 203 .. flat-table:: DV BT Timing standards
 204     :header-rows:  0
 205     :stub-columns: 0
 206
 207     * - Timing standard
 208       - Description
 209     * - ``V4L2_DV_BT_STD_CEA861``
 210       - The timings follow the CEA-861 Digital TV Profile standard
 211     * - ``V4L2_DV_BT_STD_DMT``
 212       - The timings follow the VESA Discrete Monitor Timings standard
 213     * - ``V4L2_DV_BT_STD_CVT``
 214       - The timings follow the VESA Coordinated Video Timings standard
 215     * - ``V4L2_DV_BT_STD_GTF``
 216       - The timings follow the VESA Generalized Timings Formula standard
 217     * - ``V4L2_DV_BT_STD_SDI``
 218       - The timings follow the SDI Timings standard.
 219         There are no horizontal syncs/porches at all in this format.
 220         Total blanking timings must be set in hsync or vsync fields only.
 221
 222 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
 223
 224 .. _dv-bt-flags:
 225
 226 .. flat-table:: DV BT Timing flags
 227     :header-rows:  0
 228     :stub-columns: 0
 229
 230     * - Flag
 231       - Description
 232     * - ``V4L2_DV_FL_REDUCED_BLANKING``
 233       - CVT/GTF specific: the timings use reduced blanking (CVT) or the
 234         'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 235         vertical blanking intervals are reduced, allowing a higher
 236         resolution over the same bandwidth. This is a read-only flag,
 237         applications must not set this.
 238     * - ``V4L2_DV_FL_CAN_REDUCE_FPS``
 239       - CEA-861 specific: set for CEA-861 formats with a framerate that is
 240         a multiple of six. These formats can be optionally played at 1 /
 241         1.001 speed to be compatible with 60 Hz based standards such as
 242         NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 243         the transmitter can't generate such frequencies, then the flag
 244         will also be cleared. This is a read-only flag, applications must
 245         not set this.
 246     * - ``V4L2_DV_FL_REDUCED_FPS``
 247       - CEA-861 specific: only valid for video transmitters, the flag is
 248         cleared by receivers. It is also only valid for formats with the
 249         ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 250         flag will be cleared by the driver. If the application sets this
 251         flag, then the pixelclock used to set up the transmitter is
 252         divided by 1.001 to make it compatible with NTSC framerates. If
 253         the transmitter can't generate such frequencies, then the flag
 254         will also be cleared.
 255     * - ``V4L2_DV_FL_HALF_LINE``
 256       - Specific to interlaced formats: if set, then the vertical
 257         frontporch of field 1 (aka the odd field) is really one half-line
 258         longer and the vertical backporch of field 2 (aka the even field)
 259         is really one half-line shorter, so each field has exactly the
 260         same number of half-lines. Whether half-lines can be detected or
 261         used depends on the hardware.
 262     * - ``V4L2_DV_FL_IS_CE_VIDEO``
 263       - If set, then this is a Consumer Electronics (CE) video format.
 264         Such formats differ from other formats (commonly called IT
 265         formats) in that if R'G'B' encoding is used then by default the
 266         R'G'B' values use limited range (i.e. 16-235) as opposed to full
 267         range (i.e. 0-255). All formats defined in CEA-861 except for the
 268         640x480p59.94 format are CE formats.
 269     * - ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
 270       - Some formats like SMPTE-125M have an interlaced signal with a odd
 271         total height. For these formats, if this flag is set, the first
 272         field has the extra line. Else, it is the second field.