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 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, 93it must not point to another than the local endpoint. Two endpoints with their 94'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 113 114Required properties 115------------------- 116 117If there is more than one 'port' or more than one 'endpoint' node or 'reg' 118property is present in port and/or endpoint nodes the following properties 119are required in a relevant parent node: 120 121 - #address-cells : number of cells required to define port/endpoint 122 identifier, should be 1. 123 - #size-cells : should be zero. 124 125Optional endpoint properties 126---------------------------- 127 128- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node. 129 130