aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGuennadi Liakhovetski2012-09-11 10:44:18 -0500
committerArthur Philpott2014-03-11 18:23:38 -0500
commita91f5b0f9ef6ee1e4ae7f32453b4786497bf2687 (patch)
treedf94b6e364bf00826564f4d5d4bc274de74f0962
parent275eb95111cb6d55979edf1cb5f619841b033524 (diff)
downloadkernel-video-a91f5b0f9ef6ee1e4ae7f32453b4786497bf2687.tar.gz
kernel-video-a91f5b0f9ef6ee1e4ae7f32453b4786497bf2687.tar.xz
kernel-video-a91f5b0f9ef6ee1e4ae7f32453b4786497bf2687.zip
Add common video interfaces OF bindings documentation
This patch adds a document describing common OF bindings for video capture, output and video processing devices. It is curently mainly focused on video capture devices, with data busses defined by standards such as ITU-R BT.656 or MIPI-CSI2. It also documents a method of describing data links between devices. Change-Id: I4077340ca0c55b049513a1ee56ad698b528da5fb Signed-off-by: Guennadi Liakhovetski <g.liakhovetski@gmx.de> Signed-off-by: Sylwester Nawrocki <s.nawrocki@samsung.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com> Signed-off-by: Nikhil Devshatwar <nikhil.nd@ti.com>
-rw-r--r--Documentation/devicetree/bindings/media/video-interfaces.txt228
1 files changed, 228 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
new file mode 100644
index 00000000000..e022d2dc496
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -0,0 +1,228 @@
1Common bindings for video receiver and transmitter interfaces
2
3General concept
4---------------
5
6Video data pipelines usually consist of external devices, e.g. camera sensors,
7controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including
8video DMA engines and video data processors.
9
10SoC internal blocks are described by DT nodes, placed similarly to other SoC
11blocks. External devices are represented as child nodes of their respective
12bus controller nodes, e.g. I2C.
13
14Data interfaces on all video devices are described by their child 'port' nodes.
15Configuration of a port depends on other devices participating in the data
16transfer and is described by 'endpoint' subnodes.
17
18device {
19 ...
20 ports {
21 #address-cells = <1>;
22 #size-cells = <0>;
23
24 port@0 {
25 ...
26 endpoint@0 { ... };
27 endpoint@1 { ... };
28 };
29 port@1 { ... };
30 };
31};
32
33If a port can be configured to work with more than one remote device on the same
34bus, an 'endpoint' child node must be provided for each of them. If more than
35one port is present in a device node or there is more than one endpoint at a
36port, or port node needs to be associated with a selected hardware interface,
37a common scheme using '#address-cells', '#size-cells' and 'reg' properties is
38used.
39
40All 'port' nodes can be grouped under optional 'ports' node, which allows to
41specify #address-cells, #size-cells properties independently for the 'port'
42and 'endpoint' nodes and any child device nodes a device might have.
43
44Two 'endpoint' nodes are linked with each other through their 'remote-endpoint'
45phandles. An endpoint subnode of a device contains all properties needed for
46configuration of this device for data exchange with other device. In most
47cases properties at the peer 'endpoint' nodes will be identical, however they
48might need to be different when there is any signal modifications on the bus
49between two devices, e.g. there are logic signal inverters on the lines.
50
51It is allowed for multiple endpoints at a port to be active simultaneously,
52where supported by a device. For example, in case where a data interface of
53a device is partitioned into multiple data busses, e.g. 16-bit input port
54divided into two separate ITU-R BT.656 8-bit busses. In such case bus-width
55and data-shift properties can be used to assign physical data lines to each
56endpoint node (logical bus).
57
58
59Required properties
60-------------------
61
62If there is more than one 'port' or more than one 'endpoint' node or 'reg'
63property is present in port and/or endpoint nodes the following properties
64are required in a relevant parent node:
65
66 - #address-cells : number of cells required to define port/endpoint
67 identifier, should be 1.
68 - #size-cells : should be zero.
69
70Optional endpoint properties
71----------------------------
72
73- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
74- slave-mode: a boolean property indicating that the link is run in slave mode.
75 The default when this property is not specified is master mode. In the slave
76 mode horizontal and vertical synchronization signals are provided to the
77 slave device (data source) by the master device (data sink). In the master
78 mode the data source device is also the source of the synchronization signals.
79- bus-width: number of data lines actively used, valid for the parallel busses.
80- data-shift: on the parallel data busses, if bus-width is used to specify the
81 number of data lines, data-shift can be used to specify which data lines are
82 used, e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
83- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
84- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
85 Note, that if HSYNC and VSYNC polarities are not specified, embedded
86 synchronization may be required, where supported.
87- data-active: similar to HSYNC and VSYNC, specifies data line polarity.
88- field-even-active: field signal level during the even field data transmission.
89- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock
90 signal.
91- data-lanes: an array of physical data lane indexes. Position of an entry
92 determines the logical lane number, while the value of an entry indicates
93 physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have
94 "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0.
95 This property is valid for serial busses only (e.g. MIPI CSI-2).
96- clock-lanes: an array of physical clock lane indexes. Position of an entry
97 determines the logical lane number, while the value of an entry indicates
98 physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;",
99 which places the clock lane on hardware lane 0. This property is valid for
100 serial busses only (e.g. MIPI CSI-2). Note that for the MIPI CSI-2 bus this
101 array contains only one entry.
102- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous
103 clock mode.
104
105
106Example
107-------
108
109The example snippet below describes two data pipelines. ov772x and imx074 are
110camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively.
111Both sensors are on the I2C control bus corresponding to the i2c0 controller
112node. ov772x sensor is linked directly to the ceu0 video host interface.
113imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a
114(single) DMA engine writing captured data to memory. ceu0 node has a single
115'port' node which may indicate that at any time only one of the following data
116pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
117
118 ceu0: ceu@0xfe910000 {
119 compatible = "renesas,sh-mobile-ceu";
120 reg = <0xfe910000 0xa0>;
121 interrupts = <0x880>;
122
123 mclk: master_clock {
124 compatible = "renesas,ceu-clock";
125 #clock-cells = <1>;
126 clock-frequency = <50000000>; /* Max clock frequency */
127 clock-output-names = "mclk";
128 };
129
130 port {
131 #address-cells = <1>;
132 #size-cells = <0>;
133
134 /* Parallel bus endpoint */
135 ceu0_1: endpoint@1 {
136 reg = <1>; /* Local endpoint # */
137 remote = <&ov772x_1_1>; /* Remote phandle */
138 bus-width = <8>; /* Used data lines */
139 data-shift = <2>; /* Lines 9:2 are used */
140
141 /* If hsync-active/vsync-active are missing,
142 embedded BT.656 sync is used */
143 hsync-active = <0>; /* Active low */
144 vsync-active = <0>; /* Active low */
145 data-active = <1>; /* Active high */
146 pclk-sample = <1>; /* Rising */
147 };
148
149 /* MIPI CSI-2 bus endpoint */
150 ceu0_0: endpoint@0 {
151 reg = <0>;
152 remote = <&csi2_2>;
153 };
154 };
155 };
156
157 i2c0: i2c@0xfff20000 {
158 ...
159 ov772x_1: camera@0x21 {
160 compatible = "omnivision,ov772x";
161 reg = <0x21>;
162 vddio-supply = <&regulator1>;
163 vddcore-supply = <&regulator2>;
164
165 clock-frequency = <20000000>;
166 clocks = <&mclk 0>;
167 clock-names = "xclk";
168
169 port {
170 /* With 1 endpoint per port no need for addresses. */
171 ov772x_1_1: endpoint {
172 bus-width = <8>;
173 remote-endpoint = <&ceu0_1>;
174 hsync-active = <1>;
175 vsync-active = <0>; /* Who came up with an
176 inverter here ?... */
177 data-active = <1>;
178 pclk-sample = <1>;
179 };
180 };
181 };
182
183 imx074: camera@0x1a {
184 compatible = "sony,imx074";
185 reg = <0x1a>;
186 vddio-supply = <&regulator1>;
187 vddcore-supply = <&regulator2>;
188
189 clock-frequency = <30000000>; /* Shared clock with ov772x_1 */
190 clocks = <&mclk 0>;
191 clock-names = "sysclk"; /* Assuming this is the
192 name in the datasheet */
193 port {
194 imx074_1: endpoint {
195 clock-lanes = <0>;
196 data-lanes = <1 2>;
197 remote-endpoint = <&csi2_1>;
198 };
199 };
200 };
201 };
202
203 csi2: csi2@0xffc90000 {
204 compatible = "renesas,sh-mobile-csi2";
205 reg = <0xffc90000 0x1000>;
206 interrupts = <0x17a0>;
207 #address-cells = <1>;
208 #size-cells = <0>;
209
210 port@1 {
211 compatible = "renesas,csi2c"; /* One of CSI2I and CSI2C. */
212 reg = <1>; /* CSI-2 PHY #1 of 2: PHY_S,
213 PHY_M has port address 0,
214 is unused. */
215 csi2_1: endpoint {
216 clock-lanes = <0>;
217 data-lanes = <2 1>;
218 remote-endpoint = <&imx074_1>;
219 };
220 };
221 port@2 {
222 reg = <2>; /* port 2: link to the CEU */
223
224 csi2_2: endpoint {
225 remote-endpoint = <&ceu0_0>;
226 };
227 };
228 };