Re: [RFC] Adding export-symbols to specification

[Herve Codina <herve.codina@bootlin.com>]

Hi Ayush,

On Mon, 27 Jan 2025 19:15:10 +0530
Ayush Singh <ayush@beagleboard.org> wrote:

> Hello everyone,
> 
> 
> The RFC aims to get feedback and any blockers/objections to adding 
> export-symbols to base devicetree specification to allow for support of 
> base board + runtime connector setups using devicetree overlays. The 
> idea was actually proposed in the linux kernel mailing list by Herve 
> Codina [0] with the devicetree schema and linux kernel implementation. 
> Initial implementations for devicetree compiler [1] and fdtoverlay [2] 
> have also been sent to the mailing lists.
> 
> 
> # Introduction
> 
> There are a lot of setups, especially in embedded systems that consist 
> of a base connector and addon boards that can be connected to this 
> connector. Here are some examples:
> 
> - MikroBus
> 
> - GE SUNH
> 
> - BeagleCapes, etc
> 
> 
> Some of these connectors have runtime detection capabilities (GE SUNH), 
> while some do not (MikroBUS without 1-wire EEPROM). The goal is to 
> decouple the connector on base device tree with the overlay for addon 
> boards. This will allow having 1 overlay for each board that would work 
> with connector devicetree on any board.
> 
> 
> One of the issue was referencing resources available on the base board 
> device tree from the addon overlay device tree. Using a nexus node [3] 
> 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 fail 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 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.
> 
> Note: `export-symbols` properties differ from __symbols__ since they are 
> phandles, not path references. This is much easier to work with in 
> overlays as described in [7].
> 
> 
> 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.
> 

[...]

You have perfectly summarized the export-symbols goal and the benefit of
this new feature.

I am waiting for feedback from other people. I hope we will move forward
on this topic and unblock several users (me included) stuck on this real
issue.

Thanks a lot!

Best regards,
Hervé