blob: 258b8dfddf48c1e218b5e3e1a8a41b70b4baeeec [file] [log] [blame]
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -03001Common 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
Sakari Ailusa197c7f2017-09-18 01:15:53 -070058Documenting bindings for devices
59--------------------------------
60
61All required and optional bindings the device supports shall be explicitly
62documented in device DT binding documentation. This also includes port and
63endpoint nodes for the device, including unit-addresses and reg properties where
64relevant.
65
66Please also see Documentation/devicetree/bindings/graph.txt .
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -030067
68Required properties
69-------------------
70
71If there is more than one 'port' or more than one 'endpoint' node or 'reg'
72property is present in port and/or endpoint nodes the following properties
73are required in a relevant parent node:
74
75 - #address-cells : number of cells required to define port/endpoint
76 identifier, should be 1.
77 - #size-cells : should be zero.
78
Sakari Ailus26baf6d2017-03-03 13:14:02 -050079
80Optional properties
81-------------------
82
83- flash-leds: An array of phandles, each referring to a flash LED, a sub-node
84 of the LED driver device node.
85
Sakari Ailus95293f72017-03-03 17:07:51 -050086- lens-focus: A phandle to the node of the focus lens controller.
87
Sakari Ailus26baf6d2017-03-03 13:14:02 -050088
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -030089Optional endpoint properties
90----------------------------
91
92- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
93- slave-mode: a boolean property indicating that the link is run in slave mode.
94 The default when this property is not specified is master mode. In the slave
95 mode horizontal and vertical synchronization signals are provided to the
96 slave device (data source) by the master device (data sink). In the master
97 mode the data source device is also the source of the synchronization signals.
Sakari Ailus4303a0c2017-02-06 04:49:57 -050098- bus-type: data bus type. Possible values are:
99 0 - autodetect based on other properties (MIPI CSI-2 D-PHY, parallel or Bt656)
100 1 - MIPI CSI-2 C-PHY
101 2 - MIPI CSI1
102 3 - CCP2
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300103- bus-width: number of data lines actively used, valid for the parallel busses.
104- data-shift: on the parallel data busses, if bus-width is used to specify the
105 number of data lines, data-shift can be used to specify which data lines are
106 used, e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
107- hsync-active: active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
108- vsync-active: active state of the VSYNC signal, 0/1 for LOW/HIGH respectively.
109 Note, that if HSYNC and VSYNC polarities are not specified, embedded
110 synchronization may be required, where supported.
111- data-active: similar to HSYNC and VSYNC, specifies data line polarity.
112- field-even-active: field signal level during the even field data transmission.
113- pclk-sample: sample data on rising (1) or falling (0) edge of the pixel clock
114 signal.
Lad, Prabhakard1d70aa62013-08-11 02:02:24 -0300115- sync-on-green-active: active state of Sync-on-green (SoG) signal, 0/1 for
116 LOW/HIGH respectively.
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300117- data-lanes: an array of physical data lane indexes. Position of an entry
118 determines the logical lane number, while the value of an entry indicates
119 physical lane, e.g. for 2-lane MIPI CSI-2 bus we could have
120 "data-lanes = <1 2>;", assuming the clock lane is on hardware lane 0.
Sakari Ailus75713582017-09-18 01:20:59 -0700121 If the hardware does not support lane reordering, monotonically
122 incremented values shall be used from 0 or 1 onwards, depending on
123 whether or not there is also a clock lane. This property is valid for
124 serial busses only (e.g. MIPI CSI-2).
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300125- clock-lanes: an array of physical clock lane indexes. Position of an entry
126 determines the logical lane number, while the value of an entry indicates
127 physical lane, e.g. for a MIPI CSI-2 bus we could have "clock-lanes = <0>;",
128 which places the clock lane on hardware lane 0. This property is valid for
129 serial busses only (e.g. MIPI CSI-2). Note that for the MIPI CSI-2 bus this
130 array contains only one entry.
131- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous
132 clock mode.
Sakari Ailus0f8e2532014-11-08 08:38:10 -0300133- link-frequencies: Allowed data bus frequencies. For MIPI CSI-2, for
134 instance, this is the actual frequency of the bus, not bits per clock per
135 lane value. An array of 64-bit unsigned integers.
Sakari Ailus9e1ee1b2015-03-25 19:57:36 -0300136- lane-polarities: an array of polarities of the lanes starting from the clock
137 lane and followed by the data lanes in the same order as in data-lanes.
138 Valid values are 0 (normal) and 1 (inverted). The length of the array
139 should be the combined length of data-lanes and clock-lanes properties.
140 If the lane-polarities property is omitted, the value must be interpreted
141 as 0 (normal). This property is valid for serial busses only.
Sakari Ailus48b01322017-02-08 03:23:31 -0500142- strobe: Whether the clock signal is used as clock (0) or strobe (1). Used
143 with CCP2, for instance.
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300144
145Example
146-------
147
148The example snippet below describes two data pipelines. ov772x and imx074 are
149camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively.
150Both sensors are on the I2C control bus corresponding to the i2c0 controller
151node. ov772x sensor is linked directly to the ceu0 video host interface.
152imx074 is linked to ceu0 through the MIPI CSI-2 receiver (csi2). ceu0 has a
153(single) DMA engine writing captured data to memory. ceu0 node has a single
154'port' node which may indicate that at any time only one of the following data
155pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0.
156
Mathieu Malaterre4c9847b2017-11-29 21:55:15 +0100157 ceu0: ceu@fe910000 {
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300158 compatible = "renesas,sh-mobile-ceu";
159 reg = <0xfe910000 0xa0>;
160 interrupts = <0x880>;
161
162 mclk: master_clock {
163 compatible = "renesas,ceu-clock";
164 #clock-cells = <1>;
165 clock-frequency = <50000000>; /* Max clock frequency */
166 clock-output-names = "mclk";
167 };
168
169 port {
170 #address-cells = <1>;
171 #size-cells = <0>;
172
173 /* Parallel bus endpoint */
174 ceu0_1: endpoint@1 {
175 reg = <1>; /* Local endpoint # */
176 remote = <&ov772x_1_1>; /* Remote phandle */
177 bus-width = <8>; /* Used data lines */
178 data-shift = <2>; /* Lines 9:2 are used */
179
180 /* If hsync-active/vsync-active are missing,
181 embedded BT.656 sync is used */
182 hsync-active = <0>; /* Active low */
183 vsync-active = <0>; /* Active low */
184 data-active = <1>; /* Active high */
185 pclk-sample = <1>; /* Rising */
186 };
187
188 /* MIPI CSI-2 bus endpoint */
189 ceu0_0: endpoint@0 {
190 reg = <0>;
191 remote = <&csi2_2>;
192 };
193 };
194 };
195
Mathieu Malaterre4c9847b2017-11-29 21:55:15 +0100196 i2c0: i2c@fff20000 {
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300197 ...
Mathieu Malaterre4c9847b2017-11-29 21:55:15 +0100198 ov772x_1: camera@21 {
Fabio Estevam3cfd5902014-12-02 01:09:04 -0200199 compatible = "ovti,ov772x";
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300200 reg = <0x21>;
201 vddio-supply = <&regulator1>;
202 vddcore-supply = <&regulator2>;
203
204 clock-frequency = <20000000>;
205 clocks = <&mclk 0>;
206 clock-names = "xclk";
207
208 port {
209 /* With 1 endpoint per port no need for addresses. */
210 ov772x_1_1: endpoint {
211 bus-width = <8>;
212 remote-endpoint = <&ceu0_1>;
213 hsync-active = <1>;
214 vsync-active = <0>; /* Who came up with an
215 inverter here ?... */
216 data-active = <1>;
217 pclk-sample = <1>;
218 };
219 };
220 };
221
Mathieu Malaterre4c9847b2017-11-29 21:55:15 +0100222 imx074: camera@1a {
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300223 compatible = "sony,imx074";
224 reg = <0x1a>;
225 vddio-supply = <&regulator1>;
226 vddcore-supply = <&regulator2>;
227
228 clock-frequency = <30000000>; /* Shared clock with ov772x_1 */
229 clocks = <&mclk 0>;
230 clock-names = "sysclk"; /* Assuming this is the
231 name in the datasheet */
232 port {
233 imx074_1: endpoint {
234 clock-lanes = <0>;
235 data-lanes = <1 2>;
236 remote-endpoint = <&csi2_1>;
237 };
238 };
239 };
240 };
241
Mathieu Malaterre4c9847b2017-11-29 21:55:15 +0100242 csi2: csi2@ffc90000 {
Guennadi Liakhovetski53c5b6c2012-09-11 12:44:18 -0300243 compatible = "renesas,sh-mobile-csi2";
244 reg = <0xffc90000 0x1000>;
245 interrupts = <0x17a0>;
246 #address-cells = <1>;
247 #size-cells = <0>;
248
249 port@1 {
250 compatible = "renesas,csi2c"; /* One of CSI2I and CSI2C. */
251 reg = <1>; /* CSI-2 PHY #1 of 2: PHY_S,
252 PHY_M has port address 0,
253 is unused. */
254 csi2_1: endpoint {
255 clock-lanes = <0>;
256 data-lanes = <2 1>;
257 remote-endpoint = <&imx074_1>;
258 };
259 };
260 port@2 {
261 reg = <2>; /* port 2: link to the CEU */
262
263 csi2_2: endpoint {
264 remote-endpoint = <&ceu0_0>;
265 };
266 };
267 };