Documentation/media/uapi/v4l/ext-ctrls-dv.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _dv-controls:
  11
  12 *******************************
  13 Digital Video Control Reference
  14 *******************************
  15
  16 The Digital Video control class is intended to control receivers and
  17 transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
  18 `DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
  19 (Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
  20 (:ref:`dp`). These controls are generally expected to be private to
  21 the receiver or transmitter subdevice that implements them, so they are
  22 only exposed on the ``/dev/v4l-subdev*`` device node.
  23
  24 .. note::
  25
  26    Note that these devices can have multiple input or output pads which are
  27    hooked up to e.g. HDMI connectors. Even though the subdevice will
  28    receive or transmit video from/to only one of those pads, the other pads
  29    can still be active when it comes to EDID (Extended Display
  30    Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
  31    Content Protection System, :ref:`hdcp`) processing, allowing the
  32    device to do the fairly slow EDID/HDCP handling in advance. This allows
  33    for quick switching between connectors.
  34
  35 These pads appear in several of the controls in this section as
  36 bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
  37 1, etc. The maximum value of the control is the set of valid pads.
  38
  39
  40 .. _dv-control-id:
  41
  42 Digital Video Control IDs
  43 =========================
  44
  45 ``V4L2_CID_DV_CLASS (class)``
  46     The Digital Video class descriptor.
  47
  48 ``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
  49     Many connectors have a hotplug pin which is high if EDID information
  50     is available from the source. This control shows the state of the
  51     hotplug pin as seen by the transmitter. Each bit corresponds to an
  52     output pad on the transmitter. If an output pad does not have an
  53     associated hotplug pin, then the bit for that pad will be 0. This
  54     read-only control is applicable to DVI-D, HDMI and DisplayPort
  55     connectors.
  56
  57 ``V4L2_CID_DV_TX_RXSENSE (bitmask)``
  58     Rx Sense is the detection of pull-ups on the TMDS clock lines. This
  59     normally means that the sink has left/entered standby (i.e. the
  60     transmitter can sense that the receiver is ready to receive video).
  61     Each bit corresponds to an output pad on the transmitter. If an
  62     output pad does not have an associated Rx Sense, then the bit for
  63     that pad will be 0. This read-only control is applicable to DVI-D
  64     and HDMI devices.
  65
  66 ``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
  67     When the transmitter sees the hotplug signal from the receiver it
  68     will attempt to read the EDID. If set, then the transmitter has read
  69     at least the first block (= 128 bytes). Each bit corresponds to an
  70     output pad on the transmitter. If an output pad does not support
  71     EDIDs, then the bit for that pad will be 0. This read-only control
  72     is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
  73
  74 ``V4L2_CID_DV_TX_MODE``
  75     (enum)
  76
  77 enum v4l2_dv_tx_mode -
  78     HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
  79     mode (video + audio + auxiliary data). This control selects which
  80     mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
  81     This control is applicable to HDMI connectors.
  82
  83 ``V4L2_CID_DV_TX_RGB_RANGE``
  84     (enum)
  85
  86 enum v4l2_dv_rgb_range -
  87     Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
  88     follows the RGB quantization range specified in the standard for the
  89     video interface (ie. :ref:`cea861` for HDMI).
  90     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
  91     standard to be compatible with sinks that have not implemented the
  92     standard correctly (unfortunately quite common for HDMI and DVI-D).
  93     Full range allows all possible values to be used whereas limited
  94     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
  95     the number of bits per component. This control is applicable to VGA,
  96     DVI-A/D, HDMI and DisplayPort connectors.
  97
  98 ``V4L2_CID_DV_TX_IT_CONTENT_TYPE``
  99     (enum)
 100
 101 enum v4l2_dv_it_content_type -
 102     Configures the IT Content Type of the transmitted video. This
 103     information is sent over HDMI and DisplayPort connectors as part of
 104     the AVI InfoFrame. The term 'IT Content' is used for content that
 105     originates from a computer as opposed to content from a TV broadcast
 106     or an analog source. The enum v4l2_dv_it_content_type defines
 107     the possible content types:
 108
 109 .. tabularcolumns:: |p{7.0cm}|p{10.5cm}|
 110
 111 .. flat-table::
 112     :header-rows:  0
 113     :stub-columns: 0
 114
 115     * - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
 116       - Graphics content. Pixel data should be passed unfiltered and
 117         without analog reconstruction.
 118     * - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
 119       - Photo content. The content is derived from digital still pictures.
 120         The content should be passed through with minimal scaling and
 121         picture enhancements.
 122     * - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
 123       - Cinema content.
 124     * - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
 125       - Game content. Audio and video latency should be minimized.
 126     * - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
 127       - No IT Content information is available and the ITC bit in the AVI
 128         InfoFrame is set to 0.
 129
 130
 131
 132 ``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
 133     Detects whether the receiver receives power from the source (e.g.
 134     HDMI carries 5V on one of the pins). This is often used to power an
 135     eeprom which contains EDID information, such that the source can
 136     read the EDID even if the sink is in standby/power off. Each bit
 137     corresponds to an input pad on the receiver. If an input pad
 138     cannot detect whether power is present, then the bit for that pad
 139     will be 0. This read-only control is applicable to DVI-D, HDMI and
 140     DisplayPort connectors.
 141
 142 ``V4L2_CID_DV_RX_RGB_RANGE``
 143     (enum)
 144
 145 enum v4l2_dv_rgb_range -
 146     Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
 147     follows the RGB quantization range specified in the standard for the
 148     video interface (ie. :ref:`cea861` for HDMI).
 149     V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
 150     standard to be compatible with sources that have not implemented the
 151     standard correctly (unfortunately quite common for HDMI and DVI-D).
 152     Full range allows all possible values to be used whereas limited
 153     range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
 154     the number of bits per component. This control is applicable to VGA,
 155     DVI-A/D, HDMI and DisplayPort connectors.
 156
 157 ``V4L2_CID_DV_RX_IT_CONTENT_TYPE``
 158     (enum)
 159
 160 enum v4l2_dv_it_content_type -
 161     Reads the IT Content Type of the received video. This information is
 162     sent over HDMI and DisplayPort connectors as part of the AVI
 163     InfoFrame. The term 'IT Content' is used for content that originates
 164     from a computer as opposed to content from a TV broadcast or an
 165     analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
 166     available content types.