Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / 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.3cm}|p{10.4cm}|
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.