Tom Rini | 53633a8 | 2024-02-29 12:33:36 -0500 | [diff] [blame] | 1 | # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) |
| 2 | %YAML 1.2 |
| 3 | --- |
| 4 | $id: http://devicetree.org/schemas/media/video-interfaces.yaml# |
| 5 | $schema: http://devicetree.org/meta-schemas/core.yaml# |
| 6 | |
| 7 | title: Common Properties for Video Receiver and Transmitter Interface Endpoints |
| 8 | |
| 9 | maintainers: |
| 10 | - Sakari Ailus <sakari.ailus@linux.intel.com> |
| 11 | - Laurent Pinchart <laurent.pinchart@ideasonboard.com> |
| 12 | |
| 13 | description: | |
| 14 | Video data pipelines usually consist of external devices, e.g. camera sensors, |
| 15 | controlled over an I2C, SPI or UART bus, and SoC internal IP blocks, including |
| 16 | video DMA engines and video data processors. |
| 17 | |
| 18 | SoC internal blocks are described by DT nodes, placed similarly to other SoC |
| 19 | blocks. External devices are represented as child nodes of their respective |
| 20 | bus controller nodes, e.g. I2C. |
| 21 | |
| 22 | Data interfaces on all video devices are described by their child 'port' nodes. |
| 23 | Configuration of a port depends on other devices participating in the data |
| 24 | transfer and is described by 'endpoint' subnodes. |
| 25 | |
| 26 | device { |
| 27 | ... |
| 28 | ports { |
| 29 | #address-cells = <1>; |
| 30 | #size-cells = <0>; |
| 31 | |
| 32 | port@0 { |
| 33 | ... |
| 34 | endpoint@0 { ... }; |
| 35 | endpoint@1 { ... }; |
| 36 | }; |
| 37 | port@1 { ... }; |
| 38 | }; |
| 39 | }; |
| 40 | |
| 41 | If a port can be configured to work with more than one remote device on the same |
| 42 | bus, an 'endpoint' child node must be provided for each of them. If more than |
| 43 | one port is present in a device node or there is more than one endpoint at a |
| 44 | port, or port node needs to be associated with a selected hardware interface, |
| 45 | a common scheme using '#address-cells', '#size-cells' and 'reg' properties is |
| 46 | used. |
| 47 | |
| 48 | All 'port' nodes can be grouped under optional 'ports' node, which allows to |
| 49 | specify #address-cells, #size-cells properties independently for the 'port' |
| 50 | and 'endpoint' nodes and any child device nodes a device might have. |
| 51 | |
| 52 | Two 'endpoint' nodes are linked with each other through their 'remote-endpoint' |
| 53 | phandles. An endpoint subnode of a device contains all properties needed for |
| 54 | configuration of this device for data exchange with other device. In most |
| 55 | cases properties at the peer 'endpoint' nodes will be identical, however they |
| 56 | might need to be different when there is any signal modifications on the bus |
| 57 | between two devices, e.g. there are logic signal inverters on the lines. |
| 58 | |
| 59 | It is allowed for multiple endpoints at a port to be active simultaneously, |
| 60 | where supported by a device. For example, in case where a data interface of |
| 61 | a device is partitioned into multiple data busses, e.g. 16-bit input port |
| 62 | divided into two separate ITU-R BT.656 8-bit busses. In such case bus-width |
| 63 | and data-shift properties can be used to assign physical data lines to each |
| 64 | endpoint node (logical bus). |
| 65 | |
| 66 | Documenting bindings for devices |
| 67 | -------------------------------- |
| 68 | |
| 69 | All required and optional bindings the device supports shall be explicitly |
| 70 | documented in device DT binding documentation. This also includes port and |
| 71 | endpoint nodes for the device, including unit-addresses and reg properties |
| 72 | where relevant. |
| 73 | |
| 74 | allOf: |
| 75 | - $ref: /schemas/graph.yaml#/$defs/endpoint-base |
| 76 | |
| 77 | properties: |
| 78 | slave-mode: |
| 79 | type: boolean |
| 80 | description: |
| 81 | Indicates that the link is run in slave mode. The default when this |
| 82 | property is not specified is master mode. In the slave mode horizontal and |
| 83 | vertical synchronization signals are provided to the slave device (data |
| 84 | source) by the master device (data sink). In the master mode the data |
| 85 | source device is also the source of the synchronization signals. |
| 86 | |
| 87 | bus-type: |
| 88 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 89 | enum: |
| 90 | - 1 # MIPI CSI-2 C-PHY |
| 91 | - 2 # MIPI CSI1 |
| 92 | - 3 # CCP2 |
| 93 | - 4 # MIPI CSI-2 D-PHY |
| 94 | - 5 # Parallel |
| 95 | - 6 # BT.656 |
| 96 | - 7 # DPI |
| 97 | description: |
| 98 | Data bus type. |
| 99 | |
| 100 | bus-width: |
| 101 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 102 | maximum: 64 |
| 103 | description: |
| 104 | Number of data lines actively used, valid for the parallel busses. |
| 105 | |
| 106 | data-shift: |
| 107 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 108 | maximum: 64 |
| 109 | description: |
| 110 | On the parallel data busses, if bus-width is used to specify the number of |
| 111 | data lines, data-shift can be used to specify which data lines are used, |
| 112 | e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used. |
| 113 | |
| 114 | hsync-active: |
| 115 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 116 | enum: [ 0, 1 ] |
| 117 | description: |
| 118 | Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. |
| 119 | |
| 120 | vsync-active: |
| 121 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 122 | enum: [ 0, 1 ] |
| 123 | description: |
| 124 | Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. Note, |
| 125 | that if HSYNC and VSYNC polarities are not specified, embedded |
| 126 | synchronization may be required, where supported. |
| 127 | |
| 128 | data-active: |
| 129 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 130 | enum: [ 0, 1 ] |
| 131 | description: |
| 132 | Similar to HSYNC and VSYNC, specifies data line polarity. |
| 133 | |
| 134 | data-enable-active: |
| 135 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 136 | enum: [ 0, 1 ] |
| 137 | description: |
| 138 | Similar to HSYNC and VSYNC, specifies the data enable signal polarity. |
| 139 | |
| 140 | field-even-active: |
| 141 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 142 | enum: [ 0, 1 ] |
| 143 | description: |
| 144 | Field signal level during the even field data transmission. |
| 145 | |
| 146 | pclk-sample: |
| 147 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 148 | enum: [ 0, 1, 2 ] |
| 149 | description: |
| 150 | Sample data on falling (0), rising (1) or both (2) edges of the pixel |
| 151 | clock signal. |
| 152 | |
| 153 | sync-on-green-active: |
| 154 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 155 | enum: [ 0, 1 ] |
| 156 | description: |
| 157 | Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively. |
| 158 | |
| 159 | data-lanes: |
| 160 | $ref: /schemas/types.yaml#/definitions/uint32-array |
| 161 | minItems: 1 |
| 162 | maxItems: 8 |
| 163 | uniqueItems: true |
| 164 | items: |
| 165 | # Assume up to 9 physical lane indices |
| 166 | maximum: 8 |
| 167 | description: |
| 168 | An array of physical data lane indexes. Position of an entry determines |
| 169 | the logical lane number, while the value of an entry indicates physical |
| 170 | lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;", |
| 171 | assuming the clock lane is on hardware lane 0. If the hardware does not |
| 172 | support lane reordering, monotonically incremented values shall be used |
| 173 | from 0 or 1 onwards, depending on whether or not there is also a clock |
| 174 | lane. This property is valid for serial busses only (e.g. MIPI CSI-2). |
| 175 | |
| 176 | clock-lanes: |
| 177 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 178 | # Assume up to 9 physical lane indices |
| 179 | maximum: 8 |
| 180 | description: |
| 181 | Physical clock lane index. Position of an entry determines the logical |
| 182 | lane number, while the value of an entry indicates physical lane, e.g. for |
| 183 | a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the |
| 184 | clock lane on hardware lane 0. This property is valid for serial busses |
| 185 | only (e.g. MIPI CSI-2). |
| 186 | |
| 187 | clock-noncontinuous: |
| 188 | type: boolean |
| 189 | description: |
| 190 | Allow MIPI CSI-2 non-continuous clock mode. |
| 191 | |
| 192 | link-frequencies: |
| 193 | $ref: /schemas/types.yaml#/definitions/uint64-array |
| 194 | description: |
| 195 | Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the |
| 196 | actual frequency of the bus, not bits per clock per lane value. An array |
| 197 | of 64-bit unsigned integers. |
| 198 | |
| 199 | lane-polarities: |
| 200 | $ref: /schemas/types.yaml#/definitions/uint32-array |
| 201 | minItems: 1 |
| 202 | maxItems: 9 |
| 203 | items: |
| 204 | enum: [ 0, 1 ] |
| 205 | description: |
| 206 | An array of polarities of the lanes starting from the clock lane and |
| 207 | followed by the data lanes in the same order as in data-lanes. Valid |
| 208 | values are 0 (normal) and 1 (inverted). The length of the array should be |
| 209 | the combined length of data-lanes and clock-lanes properties. If the |
| 210 | lane-polarities property is omitted, the value must be interpreted as 0 |
| 211 | (normal). This property is valid for serial busses only. |
| 212 | |
| 213 | strobe: |
| 214 | $ref: /schemas/types.yaml#/definitions/uint32 |
| 215 | enum: [ 0, 1 ] |
| 216 | description: |
| 217 | Whether the clock signal is used as clock (0) or strobe (1). Used with |
| 218 | CCP2, for instance. |
| 219 | |
| 220 | additionalProperties: true |