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