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