Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 1 | Common bindings for video receiver and transmitter interfaces |
| 2 | |
| 3 | General concept |
| 4 | --------------- |
| 5 | |
| 6 | Video data pipelines usually consist of external devices, e.g. camera sensors, |
| 7 | controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including |
| 8 | video DMA engines and video data processors. |
| 9 | |
| 10 | SoC internal blocks are described by DT nodes, placed similarly to other SoC |
| 11 | blocks. External devices are represented as child nodes of their respective |
| 12 | bus controller nodes, e.g. I2C. |
| 13 | |
| 14 | Data interfaces on all video devices are described by their child 'port' nodes. |
| 15 | Configuration of a port depends on other devices participating in the data |
| 16 | transfer and is described by 'endpoint' subnodes. |
| 17 | |
| 18 | device { |
| 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 | |
| 33 | If a port can be configured to work with more than one remote device on the same |
| 34 | bus, an 'endpoint' child node must be provided for each of them. If more than |
| 35 | one port is present in a device node or there is more than one endpoint at a |
| 36 | port, or port node needs to be associated with a selected hardware interface, |
| 37 | a common scheme using '#address-cells', '#size-cells' and 'reg' properties is |
| 38 | used. |
| 39 | |
| 40 | All 'port' nodes can be grouped under optional 'ports' node, which allows to |
| 41 | specify #address-cells, #size-cells properties independently for the 'port' |
| 42 | and 'endpoint' nodes and any child device nodes a device might have. |
| 43 | |
| 44 | Two 'endpoint' nodes are linked with each other through their 'remote-endpoint' |
| 45 | phandles. An endpoint subnode of a device contains all properties needed for |
| 46 | configuration of this device for data exchange with other device. In most |
| 47 | cases properties at the peer 'endpoint' nodes will be identical, however they |
| 48 | might need to be different when there is any signal modifications on the bus |
| 49 | between two devices, e.g. there are logic signal inverters on the lines. |
| 50 | |
| 51 | It is allowed for multiple endpoints at a port to be active simultaneously, |
| 52 | where supported by a device. For example, in case where a data interface of |
| 53 | a device is partitioned into multiple data busses, e.g. 16-bit input port |
| 54 | divided into two separate ITU-R BT.656 8-bit busses. In such case bus-width |
| 55 | and data-shift properties can be used to assign physical data lines to each |
| 56 | endpoint node (logical bus). |
| 57 | |
Sakari Ailus | a197c7f | 2017-09-18 01:15:53 -0700 | [diff] [blame] | 58 | Documenting bindings for devices |
| 59 | -------------------------------- |
| 60 | |
| 61 | All required and optional bindings the device supports shall be explicitly |
| 62 | documented in device DT binding documentation. This also includes port and |
| 63 | endpoint nodes for the device, including unit-addresses and reg properties where |
| 64 | relevant. |
| 65 | |
| 66 | Please also see Documentation/devicetree/bindings/graph.txt . |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 67 | |
| 68 | Required properties |
| 69 | ------------------- |
| 70 | |
| 71 | If there is more than one 'port' or more than one 'endpoint' node or 'reg' |
| 72 | property is present in port and/or endpoint nodes the following properties |
| 73 | are 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 Ailus | 26baf6d | 2017-03-03 13:14:02 -0500 | [diff] [blame] | 79 | |
| 80 | Optional 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 Ailus | 95293f7 | 2017-03-03 17:07:51 -0500 | [diff] [blame] | 86 | - lens-focus: A phandle to the node of the focus lens controller. |
| 87 | |
Sakari Ailus | 26baf6d | 2017-03-03 13:14:02 -0500 | [diff] [blame] | 88 | |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 89 | Optional 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 Ailus | 4303a0c | 2017-02-06 04:49:57 -0500 | [diff] [blame] | 98 | - 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 Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 103 | - 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, Prabhakar | d1d70aa6 | 2013-08-11 02:02:24 -0300 | [diff] [blame] | 115 | - sync-on-green-active: active state of Sync-on-green (SoG) signal, 0/1 for |
| 116 | LOW/HIGH respectively. |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 117 | - 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 Ailus | 7571358 | 2017-09-18 01:20:59 -0700 | [diff] [blame] | 121 | 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 Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 125 | - 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 Ailus | 0f8e253 | 2014-11-08 08:38:10 -0300 | [diff] [blame] | 133 | - 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 Ailus | 9e1ee1b | 2015-03-25 19:57:36 -0300 | [diff] [blame] | 136 | - 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 Ailus | 48b0132 | 2017-02-08 03:23:31 -0500 | [diff] [blame] | 142 | - strobe: Whether the clock signal is used as clock (0) or strobe (1). Used |
| 143 | with CCP2, for instance. |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 144 | |
| 145 | Example |
| 146 | ------- |
| 147 | |
| 148 | The example snippet below describes two data pipelines. ov772x and imx074 are |
| 149 | camera sensors with a parallel and serial (MIPI CSI-2) video bus respectively. |
| 150 | Both sensors are on the I2C control bus corresponding to the i2c0 controller |
| 151 | node. ov772x sensor is linked directly to the ceu0 video host interface. |
| 152 | imx074 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 |
| 155 | pipelines can be active: ov772x -> ceu0 or imx074 -> csi2 -> ceu0. |
| 156 | |
Mathieu Malaterre | 4c9847b | 2017-11-29 21:55:15 +0100 | [diff] [blame] | 157 | ceu0: ceu@fe910000 { |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 158 | 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 Malaterre | 4c9847b | 2017-11-29 21:55:15 +0100 | [diff] [blame] | 196 | i2c0: i2c@fff20000 { |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 197 | ... |
Mathieu Malaterre | 4c9847b | 2017-11-29 21:55:15 +0100 | [diff] [blame] | 198 | ov772x_1: camera@21 { |
Fabio Estevam | 3cfd590 | 2014-12-02 01:09:04 -0200 | [diff] [blame] | 199 | compatible = "ovti,ov772x"; |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 200 | reg = <0x21>; |
| 201 | vddio-supply = <®ulator1>; |
| 202 | vddcore-supply = <®ulator2>; |
| 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 Malaterre | 4c9847b | 2017-11-29 21:55:15 +0100 | [diff] [blame] | 222 | imx074: camera@1a { |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 223 | compatible = "sony,imx074"; |
| 224 | reg = <0x1a>; |
| 225 | vddio-supply = <®ulator1>; |
| 226 | vddcore-supply = <®ulator2>; |
| 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 Malaterre | 4c9847b | 2017-11-29 21:55:15 +0100 | [diff] [blame] | 242 | csi2: csi2@ffc90000 { |
Guennadi Liakhovetski | 53c5b6c | 2012-09-11 12:44:18 -0300 | [diff] [blame] | 243 | 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 | }; |