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