Re: [PATCH] Add new `export-symbols` node

On 2/25/25 20:15, Andrew Davis wrote:

> On 2/25/25 12:02 AM, Ayush Singh wrote:
>> `export-symbols` is designed to be a local replacement of global
>> `__symbols__` allowing nodes to define aliases to nodes in a tree, which
>> will take precedence over the aliases defined in the global 
>> `__symbols__`.
>>
>> Having a way to allow node local aliases helps in usecases such as
>> connectors and addon-boards, by allowing decoupling of
>> overlays/devicetree nodes of addon-board from the base connector.
>>
>> Signed-off-by: Ayush Singh <[email protected]>
>> ---
>> This patch series follows the initial RFC [9] sent a few weeks ago. I
>> will be reiterating the RFC here for anyone who might be seeing this the
>> first time, since there was not much feedback in that thread.
>>
>> The patch series adds 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.
>
> How? I feel this gets hand-waved over but is the core issue you are 
> trying
> to solve. Let's say I have the above, 2 of the same connector on a board,
> how do I apply my add-on overlay to one and not the other, or to both?
>
> I believe you have suggested maybe specifying the connector with a hint
> when applying it, so my question is why can't this "hint" just be the
> connector name without the export-symbols indirection?
>
> Maybe a concrete example could help me get the full picture here,
> say I want to do this ahead of time in U-Boot during boot (so I have
> basically just "fdtapply"). I know the name of the base DT and the
> name of the device overlay. What steps do I take here?
>
> Andrew
>
My bad, the example is not great. Selecting the connector for 
application will be done in the following ways depending on the context:

1. Driver: If there is a driver (either doing automatic discovery or 
sysfs), then it will select the target connector since each connector 
will have a separate instance of the driver.

2. fdtoverlay: I will be adding a patch to allow specifying the target 
path in the fdtoverlay. So we can apply the code to the specific 
connector we want.


The `export-symbols` are for nodes that the connector needs to use, like 
the GPIO, I2C, SPI etc. In this particular example, the connector itself 
is the GPIO proxy node. It should probably be written like this:


      connector1: connector1 {
          ...
          export-symbols {
            gpio = <&connector1>;
          };
      };

      connector2: connector2 {
          ...
          export-symbols {
            gpio = <&connector2>;
          };
      };


To clarify, `export-symbols` is not responsible or even useful for 
selecting the connector itself. It is only going to be used to select 
everything else that the connector needs a generic name for.


Best Regards,

Ayush Singh