ext-ctrls-dv.rst

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