Documentation/devicetree/bindings/graph.txt

   1 Common bindings for device graphs
   2
   3 General concept
   4 ---------------
   5
   6 The hierarchical organisation of the device tree is well suited to describe
   7 control flow to devices, but there can be more complex connections between
   8 devices that work together to form a logical compound device, following an
   9 arbitrarily complex graph.
  10 There already is a simple directed graph between devices tree nodes using
  11 phandle properties pointing to other nodes to describe connections that
  12 can not be inferred from device tree parent-child relationships. The device
  13 tree graph bindings described herein abstract more complex devices that can
  14 have multiple specifiable ports, each of which can be linked to one or more
  15 ports of other devices.
  16
  17 These common bindings do not contain any information about the direction or
  18 type of the connections, they just map their existence. Specific properties
  19 may be described by specialized bindings depending on the type of connection.
  20
  21 To see how this binding applies to video pipelines, for example, see
  22 Documentation/devicetree/bindings/media/video-interfaces.txt.
  23 Here the ports describe data interfaces, and the links between them are
  24 the connecting data buses. A single port with multiple connections can
  25 correspond to multiple devices being connected to the same physical bus.
  26
  27 Organisation of ports and endpoints
  28 -----------------------------------
  29
  30 Ports are described by child 'port' nodes contained in the device node.
  31 Each port node contains an 'endpoint' subnode for each remote device port
  32 connected to this port. If a single port is connected to more than one
  33 remote device, an 'endpoint' child node must be provided for each link.
  34 If more than one port is present in a device node or there is more than one
  35 endpoint at a port, or a port node needs to be associated with a selected
  36 hardware interface, a common scheme using '#address-cells', '#size-cells'
  37 and 'reg' properties is used to number the nodes.
  38
  39 device {
  40         ...
  41         #address-cells = <1>;
  42         #size-cells = <0>;
  43
  44         port@0 {
  45                 #address-cells = <1>;
  46                 #size-cells = <0>;
  47                 reg = <0>;
  48
  49                 endpoint@0 {
  50                         reg = <0>;
  51                         ...
  52                 };
  53                 endpoint@1 {
  54                         reg = <1>;
  55                         ...
  56                 };
  57         };
  58
  59         port@1 {
  60                 reg = <1>;
  61
  62                 endpoint { ... };
  63         };
  64 };
  65
  66 All 'port' nodes can be grouped under an optional 'ports' node, which
  67 allows to specify #address-cells, #size-cells properties for the 'port'
  68 nodes independently from any other child device nodes a device might
  69 have.
  70
  71 device {
  72         ...
  73         ports {
  74                 #address-cells = <1>;
  75                 #size-cells = <0>;
  76
  77                 port@0 {
  78                         ...
  79                         endpoint@0 { ... };
  80                         endpoint@1 { ... };
  81                 };
  82
  83                 port@1 { ... };
  84         };
  85 };
  86
  87 Links between endpoints
  88 -----------------------
  89
  90 Each endpoint should contain a 'remote-endpoint' phandle property that points
  91 to the corresponding endpoint in the port of the remote device. In turn, the
  92 remote endpoint should contain a 'remote-endpoint' property. If it has one, it
  93 must not point to anything other than the local endpoint. Two endpoints with
  94 their 'remote-endpoint' phandles pointing at each other form a link between the
  95 containing ports.
  96
  97 device-1 {
  98         port {
  99                 device_1_output: endpoint {
 100                         remote-endpoint = <&device_2_input>;
 101                 };
 102         };
 103 };
 104
 105 device-2 {
 106         port {
 107                 device_2_input: endpoint {
 108                         remote-endpoint = <&device_1_output>;
 109                 };
 110         };
 111 };
 112
 113 Required properties
 114 -------------------
 115
 116 If there is more than one 'port' or more than one 'endpoint' node or 'reg'
 117 property present in the port and/or endpoint nodes then the following
 118 properties are required in a relevant parent node:
 119
 120  - #address-cells : number of cells required to define port/endpoint
 121                     identifier, should be 1.
 122  - #size-cells    : should be zero.
 123
 124 Optional endpoint properties
 125 ----------------------------
 126
 127 - remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
 128