Documentation/devicetree/bindings/media/video-interfaces.yaml

   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 bindings 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     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
 217 additionalProperties: true