Hi,
At Linux Plumbers Conference 2024, we (me and Luca Ceresolli) talked
about issues we have with runtime hotplug on non-discoverable busses
with device tree overlays [1].
On our system, a base board has a connector and addon boards can be
connected to this connector. Both boards are described using device
tree. The base board is described by a base device tree and addon
boards
are describe by overlays device tree. More details can be found at [2].
This kind of use case can be found also on:
- Grove Sunlight Sensor [3]
- mikroBUS [4]
One of the issue we were facing on was referencing resources available
on the base board device tree from the addon overlay device tree.
Using a nexus node [5] helps decoupling resources and avoid the
knowledge of the full base board from the overlay. Indeed, with nexus
node, the overlay need to know only about the nexus node itself.
For instance, suppose a connector where a GPIO is connected at PinA. On
the base board this GPIO is connected to the GPIO 12 of the SoC GPIO
controller.
The base board can describe this GPIO using a nexus node:
soc_gpio: gpio-controller {
#gpio-cells = <2>;
};
connector1: connector1 {
/*
* Nexus node for the GPIO available on the connector.
* GPIO 0 (Pin A GPIO) is connected to GPIO 12 of the SoC
gpio
* controller
*/
#gpio-cells = <2>;
gpio-map = <0 0 &soc_gpio 12 0>;
gpio-map-mask = <0xf 0x0>;
gpio-map-pass-thru = <0x0 0xf>;
};
The connector pin A GPIO can be referenced using:
<&connector1 0 GPIO_ACTIVE_HIGH>
This implies that the overlay needs to know about exact label that
references the connector. This label can be different on a different
board and so applying the overlay could failed even if it is used to
describe the exact same addon board. Further more, a given base board
can have several connectors where the exact same addon board can be
connected. In that case, the same overlay cannot be used on both
connector. Indeed, the connector labels have to be different.
The export-symbols node introduced by this current series solves this
issue.
The idea of export-symbols is to have something similar to the global
__symbols__ node but local to a specific node. Symbols listed in this
export-symbols are local and visible only when an overlay is applied on
a node having an export-symbols subnode.
Using export-symbols, our example becomes:
soc_gpio: gpio-controller {
#gpio-cells = <2>;
};
connector1: connector1 {
/*
* Nexus node for the GPIO available on the connector.
* GPIO 0 (Pin A GPIO) is connected to GPIO 12 of the SoC
gpio
* controller
*/
#gpio-cells = <2>;
gpio-map = <0 0 &soc_gpio 12 0>;
gpio-map-mask = <0xf 0x0>;
gpio-map-pass-thru = <0x0 0xf>;
export-symbols {
connector = <&connector1>;
};
};
With that export-symbols node, an overlay applied on connector1 node
can
have the symbol named 'connector' resolved to connector1. Indeed, the
export-symbols node available at connector1 node is used when the
overlay is applied. If the overlay has an unresolved 'connector'
symbol,
it will be resolved to connector1 thanks to export-symbols.
Our overlay using the nexus node can contains:
node {
foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
};
It used the GPIO 0 from the connector it is applied on.
A board with two connectors can be described with:
connector1: connector1 {
...
export-symbols {
connector = <&connector1>;
};
};
connector2: connector2 {
...
export-symbols {
connector = <&connector2>;
};
};
In that case, the same overlay with unresolved 'connector' symbol
can be
applied on both connectors and the correct symbol resolution
(connector1
or connector2) will be done.
