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     Pointer to struct :c:type:`v4l2_dv_timings`.
  39
  40
  41 Description
  42 ===========
  43
  44 To set DV timings for the input or output, applications use the
  45 :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
  46 applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
  47 information is filled in using the structure struct
  48 :c:type:`v4l2_dv_timings`. These ioctls take a
  49 pointer to the struct :c:type:`v4l2_dv_timings`
  50 structure as argument. If the ioctl is not supported or the timing
  51 values are not correct, the driver returns ``EINVAL`` error code.
  52
  53 The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
  54 the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
  55 the current input or output does not support DV timings (e.g. if
  56 :ref:`VIDIOC_ENUMINPUT` does not set the
  57 ``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
  58
  59
  60 Return Value
  61 ============
  62
  63 On success 0 is returned, on error -1 and the ``errno`` variable is set
  64 appropriately. The generic error codes are described at the
  65 :ref:`Generic Error Codes <gen-errors>` chapter.
  66
  67 EINVAL
  68     This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
  69     parameter was unsuitable.
  70
  71 ENODATA
  72     Digital video timings are not supported for this input or output.
  73
  74 EBUSY
  75     The device is busy and therefore can not change the timings.
  76
  77
  78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  79
  80 .. c:type:: v4l2_bt_timings
  81
  82 .. flat-table:: struct v4l2_bt_timings
  83     :header-rows:  0
  84     :stub-columns: 0
  85     :widths:       1 1 2
  86
  87     * - __u32
  88       - ``width``
  89       - Width of the active video in pixels.
  90     * - __u32
  91       - ``height``
  92       - Height of the active video frame in lines. So for interlaced
  93         formats the height of the active video in each field is
  94         ``height``/2.
  95     * - __u32
  96       - ``interlaced``
  97       - Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
  98     * - __u32
  99       - ``polarities``
 100       - This is a bit mask that defines polarities of sync signals. bit 0
 101         (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
 102         1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
 103         the bit is set (1) it is positive polarity and if is cleared (0),
 104         it is negative polarity.
 105     * - __u64
 106       - ``pixelclock``
 107       - Pixel clock in Hz. Ex. 74.25MHz->74250000
 108     * - __u32
 109       - ``hfrontporch``
 110       - Horizontal front porch in pixels
 111     * - __u32
 112       - ``hsync``
 113       - Horizontal sync length in pixels
 114     * - __u32
 115       - ``hbackporch``
 116       - Horizontal back porch in pixels
 117     * - __u32
 118       - ``vfrontporch``
 119       - Vertical front porch in lines. For interlaced formats this refers
 120         to the odd field (aka field 1).
 121     * - __u32
 122       - ``vsync``
 123       - Vertical sync length in lines. For interlaced formats this refers
 124         to the odd field (aka field 1).
 125     * - __u32
 126       - ``vbackporch``
 127       - Vertical back porch in lines. For interlaced formats this refers
 128         to the odd field (aka field 1).
 129     * - __u32
 130       - ``il_vfrontporch``
 131       - Vertical front porch in lines for the even field (aka field 2) of
 132         interlaced field formats. Must be 0 for progressive formats.
 133     * - __u32
 134       - ``il_vsync``
 135       - Vertical sync length in lines for the even field (aka field 2) of
 136         interlaced field formats. Must be 0 for progressive formats.
 137     * - __u32
 138       - ``il_vbackporch``
 139       - Vertical back porch in lines for the even field (aka field 2) of
 140         interlaced field formats. Must be 0 for progressive formats.
 141     * - __u32
 142       - ``standards``
 143       - The video standard(s) this format belongs to. This will be filled
 144         in by the driver. Applications must set this to 0. See
 145         :ref:`dv-bt-standards` for a list of standards.
 146     * - __u32
 147       - ``flags``
 148       - Several flags giving more information about the format. See
 149         :ref:`dv-bt-flags` for a description of the flags.
 150     * - struct :c:type:`v4l2_fract`
 151       - ``picture_aspect``
 152       - The picture aspect if the pixels are not square. Only valid if the
 153         ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set.
 154     * - __u8
 155       - ``cea861_vic``
 156       - The Video Identification Code according to the CEA-861 standard.
 157         Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set.
 158     * - __u8
 159       - ``hdmi_vic``
 160       - The Video Identification Code according to the HDMI standard.
 161         Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set.
 162     * - __u8
 163       - ``reserved[46]``
 164       - Reserved for future extensions. Drivers and applications must set
 165         the array to zero.
 166
 167
 168 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.5cm}|
 169
 170 .. c:type:: v4l2_dv_timings
 171
 172 .. flat-table:: struct v4l2_dv_timings
 173     :header-rows:  0
 174     :stub-columns: 0
 175     :widths:       1 1 2 1
 176
 177     * - __u32
 178       - ``type``
 179       -
 180       - Type of DV timings as listed in :ref:`dv-timing-types`.
 181     * - union
 182       -
 183       -
 184     * -
 185       - struct :c:type:`v4l2_bt_timings`
 186       - ``bt``
 187       - Timings defined by BT.656/1120 specifications
 188     * -
 189       - __u32
 190       - ``reserved``\ [32]
 191       -
 192
 193 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 194
 195 .. _dv-timing-types:
 196
 197 .. flat-table:: DV Timing types
 198     :header-rows:  0
 199     :stub-columns: 0
 200     :widths:       1 1 2
 201
 202     * - Timing type
 203       - value
 204       - Description
 205     * -
 206       -
 207       -
 208     * - ``V4L2_DV_BT_656_1120``
 209       - 0
 210       - BT.656/1120 timings
 211
 212 .. tabularcolumns:: |p{4.5cm}|p{12.8cm}|
 213
 214 .. _dv-bt-standards:
 215
 216 .. flat-table:: DV BT Timing standards
 217     :header-rows:  0
 218     :stub-columns: 0
 219
 220     * - Timing standard
 221       - Description
 222     * - ``V4L2_DV_BT_STD_CEA861``
 223       - The timings follow the CEA-861 Digital TV Profile standard
 224     * - ``V4L2_DV_BT_STD_DMT``
 225       - The timings follow the VESA Discrete Monitor Timings standard
 226     * - ``V4L2_DV_BT_STD_CVT``
 227       - The timings follow the VESA Coordinated Video Timings standard
 228     * - ``V4L2_DV_BT_STD_GTF``
 229       - The timings follow the VESA Generalized Timings Formula standard
 230     * - ``V4L2_DV_BT_STD_SDI``
 231       - The timings follow the SDI Timings standard.
 232         There are no horizontal syncs/porches at all in this format.
 233         Total blanking timings must be set in hsync or vsync fields only.
 234
 235 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
 236
 237 .. _dv-bt-flags:
 238
 239 .. flat-table:: DV BT Timing flags
 240     :header-rows:  0
 241     :stub-columns: 0
 242
 243     * - Flag
 244       - Description
 245     * - ``V4L2_DV_FL_REDUCED_BLANKING``
 246       - CVT/GTF specific: the timings use reduced blanking (CVT) or the
 247         'Secondary GTF' curve (GTF). In both cases the horizontal and/or
 248         vertical blanking intervals are reduced, allowing a higher
 249         resolution over the same bandwidth. This is a read-only flag,
 250         applications must not set this.
 251     * - ``V4L2_DV_FL_CAN_REDUCE_FPS``
 252       - CEA-861 specific: set for CEA-861 formats with a framerate that is
 253         a multiple of six. These formats can be optionally played at 1 /
 254         1.001 speed to be compatible with 60 Hz based standards such as
 255         NTSC and PAL-M that use a framerate of 29.97 frames per second. If
 256         the transmitter can't generate such frequencies, then the flag
 257         will also be cleared. This is a read-only flag, applications must
 258         not set this.
 259     * - ``V4L2_DV_FL_REDUCED_FPS``
 260       - CEA-861 specific: only valid for video transmitters, the flag is
 261         cleared by receivers. It is also only valid for formats with the
 262         ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
 263         flag will be cleared by the driver. If the application sets this
 264         flag, then the pixelclock used to set up the transmitter is
 265         divided by 1.001 to make it compatible with NTSC framerates. If
 266         the transmitter can't generate such frequencies, then the flag
 267         will also be cleared.
 268     * - ``V4L2_DV_FL_HALF_LINE``
 269       - Specific to interlaced formats: if set, then the vertical
 270         frontporch of field 1 (aka the odd field) is really one half-line
 271         longer and the vertical backporch of field 2 (aka the even field)
 272         is really one half-line shorter, so each field has exactly the
 273         same number of half-lines. Whether half-lines can be detected or
 274         used depends on the hardware.
 275     * - ``V4L2_DV_FL_IS_CE_VIDEO``
 276       - If set, then this is a Consumer Electronics (CE) video format.
 277         Such formats differ from other formats (commonly called IT
 278         formats) in that if R'G'B' encoding is used then by default the
 279         R'G'B' values use limited range (i.e. 16-235) as opposed to full
 280         range (i.e. 0-255). All formats defined in CEA-861 except for the
 281         640x480p59.94 format are CE formats.
 282     * - ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
 283       - Some formats like SMPTE-125M have an interlaced signal with a odd
 284         total height. For these formats, if this flag is set, the first
 285         field has the extra line. Else, it is the second field.
 286     * - ``V4L2_DV_FL_HAS_PICTURE_ASPECT``
 287       - If set, then the picture_aspect field is valid. Otherwise assume that
 288         the pixels are square, so the picture aspect ratio is the same as the
 289         width to height ratio.
 290     * - ``V4L2_DV_FL_HAS_CEA861_VIC``
 291       - If set, then the cea861_vic field is valid and contains the Video
 292         Identification Code as per the CEA-861 standard.
 293     * - ``V4L2_DV_FL_HAS_HDMI_VIC``
 294       - If set, then the hdmi_vic field is valid and contains the Video
 295         Identification Code as per the HDMI standard (HDMI Vendor Specific
 296         InfoFrame).