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    description:
97      Data bus type.
98
99  bus-width:
100    $ref: /schemas/types.yaml#/definitions/uint32
101    maximum: 64
102    description:
103      Number of data lines actively used, valid for the parallel busses.
104
105  data-shift:
106    $ref: /schemas/types.yaml#/definitions/uint32
107    maximum: 64
108    description:
109      On the parallel data busses, if bus-width is used to specify the number of
110      data lines, data-shift can be used to specify which data lines are used,
111      e.g. "bus-width=<8>; data-shift=<2>;" means, that lines 9:2 are used.
112
113  hsync-active:
114    $ref: /schemas/types.yaml#/definitions/uint32
115    enum: [ 0, 1 ]
116    description:
117      Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively.
118
119  vsync-active:
120    $ref: /schemas/types.yaml#/definitions/uint32
121    enum: [ 0, 1 ]
122    description:
123      Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. Note,
124      that if HSYNC and VSYNC polarities are not specified, embedded
125      synchronization may be required, where supported.
126
127  data-active:
128    $ref: /schemas/types.yaml#/definitions/uint32
129    enum: [ 0, 1 ]
130    description:
131      Similar to HSYNC and VSYNC, specifies data line polarity.
132
133  data-enable-active:
134    $ref: /schemas/types.yaml#/definitions/uint32
135    enum: [ 0, 1 ]
136    description:
137      Similar to HSYNC and VSYNC, specifies the data enable signal polarity.
138
139  field-even-active:
140    $ref: /schemas/types.yaml#/definitions/uint32
141    enum: [ 0, 1 ]
142    description:
143      Field signal level during the even field data transmission.
144
145  pclk-sample:
146    $ref: /schemas/types.yaml#/definitions/uint32
147    enum: [ 0, 1 ]
148    description:
149      Sample data on rising (1) or falling (0) edge of the pixel clock signal.
150
151  sync-on-green-active:
152    $ref: /schemas/types.yaml#/definitions/uint32
153    enum: [ 0, 1 ]
154    description:
155      Active state of Sync-on-green (SoG) signal, 0/1 for LOW/HIGH respectively.
156
157  data-lanes:
158    $ref: /schemas/types.yaml#/definitions/uint32-array
159    minItems: 1
160    maxItems: 8
161    items:
162      # Assume up to 9 physical lane indices
163      maximum: 8
164    description:
165      An array of physical data lane indexes. Position of an entry determines
166      the logical lane number, while the value of an entry indicates physical
167      lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1 2>;",
168      assuming the clock lane is on hardware lane 0. If the hardware does not
169      support lane reordering, monotonically incremented values shall be used
170      from 0 or 1 onwards, depending on whether or not there is also a clock
171      lane. This property is valid for serial busses only (e.g. MIPI CSI-2).
172
173  clock-lanes:
174    $ref: /schemas/types.yaml#/definitions/uint32
175    # Assume up to 9 physical lane indices
176    maximum: 8
177    description:
178      Physical clock lane index. Position of an entry determines the logical
179      lane number, while the value of an entry indicates physical lane, e.g. for
180      a MIPI CSI-2 bus we could have "clock-lanes = <0>;", which places the
181      clock lane on hardware lane 0. This property is valid for serial busses
182      only (e.g. MIPI CSI-2).
183
184  clock-noncontinuous:
185    type: boolean
186    description:
187      Allow MIPI CSI-2 non-continuous clock mode.
188
189  link-frequencies:
190    $ref: /schemas/types.yaml#/definitions/uint64-array
191    description:
192      Allowed data bus frequencies. For MIPI CSI-2, for instance, this is the
193      actual frequency of the bus, not bits per clock per lane value. An array
194      of 64-bit unsigned integers.
195
196  lane-polarities:
197    $ref: /schemas/types.yaml#/definitions/uint32-array
198    minItems: 1
199    maxItems: 9
200    items:
201      enum: [ 0, 1 ]
202    description:
203      An array of polarities of the lanes starting from the clock lane and
204      followed by the data lanes in the same order as in data-lanes. Valid
205      values are 0 (normal) and 1 (inverted). The length of the array should be
206      the combined length of data-lanes and clock-lanes properties. If the
207      lane-polarities property is omitted, the value must be interpreted as 0
208      (normal). This property is valid for serial busses only.
209
210  strobe:
211    $ref: /schemas/types.yaml#/definitions/uint32
212    enum: [ 0, 1 ]
213    description:
214      Whether the clock signal is used as clock (0) or strobe (1). Used with
215      CCP2, for instance.
216
217additionalProperties: true
218