![Kieran Bingham](/assets/img/avatar_default.png)
Some minor tweaks to the language and formatting used in the documentation identified while I was reading up on the subject matter. Signed-off-by: Kieran Bingham <kieran.bingham+renesas@ideasonboard.com> Acked-by: Philipp Zabel <p.zabel@pengutronix.de> Signed-off-by: Rob Herring <robh@kernel.org>
129 lines
4 KiB
Plaintext
129 lines
4 KiB
Plaintext
Common bindings for device graphs
|
|
|
|
General concept
|
|
---------------
|
|
|
|
The hierarchical organisation of the device tree is well suited to describe
|
|
control flow to devices, but there can be more complex connections between
|
|
devices that work together to form a logical compound device, following an
|
|
arbitrarily complex graph.
|
|
There already is a simple directed graph between devices tree nodes using
|
|
phandle properties pointing to other nodes to describe connections that
|
|
can not be inferred from device tree parent-child relationships. The device
|
|
tree graph bindings described herein abstract more complex devices that can
|
|
have multiple specifiable ports, each of which can be linked to one or more
|
|
ports of other devices.
|
|
|
|
These common bindings do not contain any information about the direction or
|
|
type of the connections, they just map their existence. Specific properties
|
|
may be described by specialized bindings depending on the type of connection.
|
|
|
|
To see how this binding applies to video pipelines, for example, see
|
|
Documentation/devicetree/bindings/media/video-interfaces.txt.
|
|
Here the ports describe data interfaces, and the links between them are
|
|
the connecting data buses. A single port with multiple connections can
|
|
correspond to multiple devices being connected to the same physical bus.
|
|
|
|
Organisation of ports and endpoints
|
|
-----------------------------------
|
|
|
|
Ports are described by child 'port' nodes contained in the device node.
|
|
Each port node contains an 'endpoint' subnode for each remote device port
|
|
connected to this port. If a single port is connected to more than one
|
|
remote device, an 'endpoint' child node must be provided for each link.
|
|
If more than one port is present in a device node or there is more than one
|
|
endpoint at a port, or a port node needs to be associated with a selected
|
|
hardware interface, a common scheme using '#address-cells', '#size-cells'
|
|
and 'reg' properties is used to number the nodes.
|
|
|
|
device {
|
|
...
|
|
#address-cells = <1>;
|
|
#size-cells = <0>;
|
|
|
|
port@0 {
|
|
#address-cells = <1>;
|
|
#size-cells = <0>;
|
|
reg = <0>;
|
|
|
|
endpoint@0 {
|
|
reg = <0>;
|
|
...
|
|
};
|
|
endpoint@1 {
|
|
reg = <1>;
|
|
...
|
|
};
|
|
};
|
|
|
|
port@1 {
|
|
reg = <1>;
|
|
|
|
endpoint { ... };
|
|
};
|
|
};
|
|
|
|
All 'port' nodes can be grouped under an optional 'ports' node, which
|
|
allows to specify #address-cells, #size-cells properties for the 'port'
|
|
nodes independently from any other child device nodes a device might
|
|
have.
|
|
|
|
device {
|
|
...
|
|
ports {
|
|
#address-cells = <1>;
|
|
#size-cells = <0>;
|
|
|
|
port@0 {
|
|
...
|
|
endpoint@0 { ... };
|
|
endpoint@1 { ... };
|
|
};
|
|
|
|
port@1 { ... };
|
|
};
|
|
};
|
|
|
|
Links between endpoints
|
|
-----------------------
|
|
|
|
Each endpoint should contain a 'remote-endpoint' phandle property that points
|
|
to the corresponding endpoint in the port of the remote device. In turn, the
|
|
remote endpoint should contain a 'remote-endpoint' property. If it has one, it
|
|
must not point to anything other than the local endpoint. Two endpoints with
|
|
their 'remote-endpoint' phandles pointing at each other form a link between the
|
|
containing ports.
|
|
|
|
device-1 {
|
|
port {
|
|
device_1_output: endpoint {
|
|
remote-endpoint = <&device_2_input>;
|
|
};
|
|
};
|
|
};
|
|
|
|
device-2 {
|
|
port {
|
|
device_2_input: endpoint {
|
|
remote-endpoint = <&device_1_output>;
|
|
};
|
|
};
|
|
};
|
|
|
|
Required properties
|
|
-------------------
|
|
|
|
If there is more than one 'port' or more than one 'endpoint' node or 'reg'
|
|
property present in the port and/or endpoint nodes then the following
|
|
properties are required in a relevant parent node:
|
|
|
|
- #address-cells : number of cells required to define port/endpoint
|
|
identifier, should be 1.
|
|
- #size-cells : should be zero.
|
|
|
|
Optional endpoint properties
|
|
----------------------------
|
|
|
|
- remote-endpoint: phandle to an 'endpoint' subnode of a remote device node.
|
|
|