On 12/9/24 9:18 AM, Herve Codina wrote:
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.
I might be missing something, but how is the correct connector (connector1
or connector2) selected? Let's say I connect my addon board to connector2,
then I apply the addon board's overlay to the base DTB. What connector
just got referenced?
Andrew
This current series add support for the export-symbols node feature:
- Patch 1 describes the export-symbols binding
- Patches 2 to 6 prepare and add the support for the export-symbols
feature
- Patch 7 adds an unittest for the export-symbols feature
Best regards,
Hervé
[1] https://lpc.events/event/18/contributions/1696/
[2] https://lore.kernel.org/lkml/20240917-hotplug-drm-bridge-v4-0-bc4dfee61be6@xxxxxxxxxxx/
[3] https://lore.kernel.org/lkml/20240702164403.29067-1-afd@xxxxxx/
[4] https://lore.kernel.org/lkml/20240627-mikrobus-scratch-spi-v5-0-9e6c148bf5f0@xxxxxxxxxxxxxxx/
[5] https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
Herve Codina (7):
dt-bindings: Add support for export-symbols node
of: resolver: Introduce get_phandle_from_symbols_node()
of: resolver: Add export_symbols in of_resolve_phandles() parameters
of: resolver: Add support for the export symbols node
of: overlay: Add export_symbols_name in of_overlay_fdt_apply()
parameters
of: overlay: Add support for the export symbols node
of: unittest: Add tests for export symbols
.../devicetree/bindings/export-symbols.yaml | 43 ++++++++++
drivers/misc/lan966x_pci.c | 3 +-
drivers/of/of_kunit_helpers.c | 2 +-
drivers/of/of_private.h | 2 +-
drivers/of/overlay.c | 30 ++++++-
drivers/of/resolver.c | 80 ++++++++++++++-----
drivers/of/unittest-data/Makefile | 5 ++
.../unittest-data/overlay_export_symbols.dtso | 15 ++++
.../of/unittest-data/testcases_common.dtsi | 1 +
.../unittest-data/tests-export-symbols.dtsi | 30 +++++++
drivers/of/unittest.c | 76 ++++++++++++++++--
include/linux/of.h | 6 +-
12 files changed, 259 insertions(+), 34 deletions(-)
create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
create mode 100644 drivers/of/unittest-data/overlay_export_symbols.dtso
create mode 100644 drivers/of/unittest-data/tests-export-symbols.dtsi
