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    items:
164      # Assume up to 9 physical lane indices
165      maximum: 8
166    description:
167      An array of physical data lane indexes. Position of an entry determines
168      the logical lane number, while the value of an entry indicates physical
169      lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;",
170      assuming the clock lane is on hardware lane 0. If the hardware does not
171      support lane reordering, monotonically incremented values shall be used
172      from 0 or 1 onwards, depending on whether or not there is also a clock
173      lane. This property is valid for serial busses only (e.g. MIPI CSI-2).
174
175  clock-lanes:
176    $ref: /schemas/types.yaml#/definitions/uint32
177    # Assume up to 9 physical lane indices
178    maximum: 8
179    description:
180      Physical clock lane index. Position of an entry determines the logical
181      lane number, while the value of an entry indicates physical lane, e.g. for
182      a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the
183      clock lane on hardware lane 0. This property is valid for serial busses
184      only (e.g. MIPI CSI-2).
185
186  clock-noncontinuous:
187    type: boolean
188    description:
189      Allow MIPI CSI-2 non-continuous clock mode.
190
191  link-frequencies:
192    $ref: /schemas/types.yaml#/definitions/uint64-array
193    description:
194      Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the
195      actual frequency of the bus, not bits per clock per lane value. An array
196      of 64-bit unsigned integers.
197
198  lane-polarities:
199    $ref: /schemas/types.yaml#/definitions/uint32-array
200    minItems: 1
201    maxItems: 9
202    items:
203      enum: [ 0, 1 ]
204    description:
205      An array of polarities of the lanes starting from the clock lane and
206      followed by the data lanes in the same order as in data-lanes. Valid
207      values are 0 (normal) and 1 (inverted). The length of the array should be
208      the combined length of data-lanes and clock-lanes properties. If the
209      lane-polarities property is omitted, the value must be interpreted as 0
210      (normal). This property is valid for serial busses only.
211
212  strobe:
213    $ref: /schemas/types.yaml#/definitions/uint32
214    enum: [ 0, 1 ]
215    description:
216      Whether the clock signal is used as clock (0) or strobe (1). Used with
217      CCP2, for instance.
218
219additionalProperties: true
220