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
7title: Common Properties for Video Receiver and Transmitter Interface Endpoints
8
9maintainers:
10  - Sakari Ailus <sakari.ailus@linux.intel.com>
11  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
12
13description: |
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
74allOf:
75  - $ref: /schemas/graph.yaml#/$defs/endpoint-base
76
77properties:
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
220additionalProperties: true
221