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     * - struct :c:type:`v4l2_fract`
 150       - ``picture_aspect``
 151       - The picture aspect if the pixels are not square. Only valid if the
 152         ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set.
 153     * - __u8
 154       - ``cea861_vic``
 155       - The Video Identification Code according to the CEA-861 standard.
 156         Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set.
 157     * - __u8
 158       - ``hdmi_vic``
 159       - The Video Identification Code according to the HDMI standard.
 160         Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set.
 161     * - __u8
 162       - ``reserved[46]``
 163       - Reserved for future extensions. Drivers and applications must set
 164         the array to zero.
 165
 166
 167 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
 168
 169 .. c:type:: v4l2_dv_timings
 170
 171 .. flat-table:: struct v4l2_dv_timings
 172     :header-rows:  0
 173     :stub-columns: 0
 174     :widths:       1 1 2 1
 175
 176     * - __u32
 177       - ``type``
 178       -
 179       - Type of DV timings as listed in :ref:`dv-timing-types`.
 180     * - union
 181       -
 182       -
 183     * -
 184       - struct :c:type:`v4l2_bt_timings`
 185       - ``bt``
 186       - Timings defined by BT.656/1120 specifications
 187     * -
 188       - __u32
 189       - ``reserved``\ [32]
 190       -
 191
 192 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 193
 194 .. _dv-timing-types:
 195
 196 .. flat-table:: DV Timing types
 197     :header-rows:  0
 198     :stub-columns: 0
 199     :widths:       1 1 2
 200
 201     * - Timing type
 202       - value
 203       - Description
 204     * -
 205       -
 206       -
 207     * - ``V4L2_DV_BT_656_1120``
 208       - 0
 209       - BT.656/1120 timings
 210
 211
 212
 213 .. _dv-bt-standards:
 214
 215 .. flat-table:: DV BT Timing standards
 216     :header-rows:  0
 217     :stub-columns: 0
 218
 219     * - Timing standard
 220       - Description
 221     * - ``V4L2_DV_BT_STD_CEA861``
 222       - The timings follow the CEA-861 Digital TV Profile standard
 223     * - ``V4L2_DV_BT_STD_DMT``
 224       - The timings follow the VESA Discrete Monitor Timings standard
 225     * - ``V4L2_DV_BT_STD_CVT``
 226       - The timings follow the VESA Coordinated Video Timings standard
 227     * - ``V4L2_DV_BT_STD_GTF``
 228       - The timings follow the VESA Generalized Timings Formula standard
 229     * - ``V4L2_DV_BT_STD_SDI``
 230       - The timings follow the SDI Timings standard.
 231         There are no horizontal syncs/porches at all in this format.
 232         Total blanking timings must be set in hsync or vsync fields only.
 233
 234 .. tabularcolumns:: |p{6.0cm}|p{11.5cm}|
 235
 236 .. _dv-bt-flags:
 237
 238 .. flat-table:: DV BT Timing flags
 239     :header-rows:  0
 240     :stub-columns: 0
 241
 242     * - Flag
 243       - Description
 244     * - ``V4L2_DV_FL_REDUCED_BLANKING``
 245       - CVT/GTF specific: the timings use reduced blanking (CVT) or the
 246         'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 247         vertical blanking intervals are reduced, allowing a higher
 248         resolution over the same bandwidth. This is a read-only flag,
 249         applications must not set this.
 250     * - ``V4L2_DV_FL_CAN_REDUCE_FPS``
 251       - CEA-861 specific: set for CEA-861 formats with a framerate that is
 252         a multiple of six. These formats can be optionally played at 1 /
 253         1.001 speed to be compatible with 60 Hz based standards such as
 254         NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 255         the transmitter can't generate such frequencies, then the flag
 256         will also be cleared. This is a read-only flag, applications must
 257         not set this.
 258     * - ``V4L2_DV_FL_REDUCED_FPS``
 259       - CEA-861 specific: only valid for video transmitters, the flag is
 260         cleared by receivers. It is also only valid for formats with the
 261         ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 262         flag will be cleared by the driver. If the application sets this
 263         flag, then the pixelclock used to set up the transmitter is
 264         divided by 1.001 to make it compatible with NTSC framerates. If
 265         the transmitter can't generate such frequencies, then the flag
 266         will also be cleared.
 267     * - ``V4L2_DV_FL_HALF_LINE``
 268       - Specific to interlaced formats: if set, then the vertical
 269         frontporch of field 1 (aka the odd field) is really one half-line
 270         longer and the vertical backporch of field 2 (aka the even field)
 271         is really one half-line shorter, so each field has exactly the
 272         same number of half-lines. Whether half-lines can be detected or
 273         used depends on the hardware.
 274     * - ``V4L2_DV_FL_IS_CE_VIDEO``
 275       - If set, then this is a Consumer Electronics (CE) video format.
 276         Such formats differ from other formats (commonly called IT
 277         formats) in that if R'G'B' encoding is used then by default the
 278         R'G'B' values use limited range (i.e. 16-235) as opposed to full
 279         range (i.e. 0-255). All formats defined in CEA-861 except for the
 280         640x480p59.94 format are CE formats.
 281     * - ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
 282       - Some formats like SMPTE-125M have an interlaced signal with a odd
 283         total height. For these formats, if this flag is set, the first
 284         field has the extra line. Else, it is the second field.
 285     * - ``V4L2_DV_FL_HAS_PICTURE_ASPECT``
 286       - If set, then the picture_aspect field is valid. Otherwise assume that
 287         the pixels are square, so the picture aspect ratio is the same as the
 288         width to height ratio.
 289     * - ``V4L2_DV_FL_HAS_CEA861_VIC``
 290       - If set, then the cea861_vic field is valid and contains the Video
 291         Identification Code as per the CEA-861 standard.
 292     * - ``V4L2_DV_FL_HAS_HDMI_VIC``
 293       - If set, then the hdmi_vic field is valid and contains the Video
 294         Identification Code as per the HDMI standard (HDMI Vendor Specific
 295         InfoFrame).