[RFC] Adding export-symbols to specification

[RFC] Adding export-symbols to specification

[Ayush Singh]

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.


# Alternatives


Some alternative approaches that were considered:



1. Using aliases.

Currently, it is not possible to update aliases in device tree overlays. 
I sent a patch a few weeks ago to add this support [4]. However, as was 
outlined by Rob, this can break existing drivers that used the unused 
indexes for devices not present in the aliases list.


2. Add support for phandles in `__symbols__`

This has been discussed in the following patch series [5]. However, 
since there is no way to distinguish between strings and phandles in 
devicetree (everything is bytestring), the type guessing is awkward. 
Also, the export-symbol solution is much more flexible than extending 
the old `__symbols__` node.


3. Add support for path reference resolution to overlays

An approach using `__symbols__` was proposed by Andrew Davis [6]. 
However, currently, it is difficult to support path reference resolution 
support to overlays [7]. This limitation makes it difficult to support 
connector chaining (MikroBUS -> Grove -> Addon board), which is possible 
in some connectors.


# Some other benefits to export-symbols

1. No need to enable generation of all symbols in base devicetree

Since the nodes used by connector are referenced by properties in 
`export-symbols`, the symbols table entries for these nodes will be 
generated, even if symbols generation is not enabled globally. This can 
help save space, specially in constrained devices.


2. Enables scoping symbol resolution

Does not pollute the global symbols, and can be useful outside addon 
board setups.


# Why add to specification?

I would like the ability to share the addon board overlays with 
ZephyrRTOS, which also has boards that support MikroBUS (like 
BeagleConnect Freedom [8]) and U-Boot. So it would make more sense if 
this node is part of the specification instead of linux specific.


# What's next?

I am also not sure if there is some sort of process that I have to 
follow to make changes to the device tree specification, so please 
inform me if I am missing something, or if there is some documentation 
regarding submitting proposals for new nodes.


[0]: 
https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/

[1]: 
https://lore.kernel.org/all/20250110-export-symbols-v1-1-b6213fcd6c82@beagleboard.org/

[2]: 
https://lore.kernel.org/devicetree-compiler/86a7a08c-d81c-43d4-99fb-d0c4e9777601@beagleboard.org/T/#t

[3] 
https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping

[4]: 
https://lore.kernel.org/all/20241110-of-alias-v2-0-16da9844a93e@beagleboard.org/T/#t

[5]: 
https://lore.kernel.org/devicetree-compiler/44bfc9b3-8282-4cc7-8d9a-7292cac663ef@ti.com/T/#mbbc181b0ef394b85b76b2024d7e209ebe70f7003

[6]: https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/

[7]: 
https://lore.kernel.org/devicetree-compiler/6b2dba90-3c52-4933-88f3-b47f96dc7710@beagleboard.org/T/#m8259c8754f680b9da7b91f7b7dd89f10da91d8ed

[8]: https://www.beagleboard.org/boards/beagleconnect-freedom


Best Regards,

Ayush Singh

Re: [RFC] Adding export-symbols to specification

[Herve Codina]

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é

Re: [RFC] Adding export-symbols to specification

[Ayush Singh]

> 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é

While working on a Patch series to the specification itself, I realized 
that I was missing some edge cases, so wanted to discuss those:

# Scope

Should export-symbols only be used to resolve the properties in parent, 
or should all other children (and their decedents) use the 
`export-symbols` for resolving phandles and path references?

For example, should the following work:


parent {

     sibling {

         led = <&gpio 0 GPIO_ACTIVE_HIGH>

     };


     export-symbols {

         gpio = <&my_gpio1>;

     };

};


This would also mean that bottoms up lookup needs to take place for all 
`export-symbols` that might be present in path to root, before using top 
level `__symbols__` or `/aliases`.


# Export symbols phandles

Can export symbols reference each other? For example is the following valid:


parent {

     export-symbols {

         shadow_gpio = <&my_gpio1>;

         gpio = <&shadow_gpio>;

     };

};


Best regards,

Ayush Singh

Re: [RFC] Adding export-symbols to specification

[Herve Codina]

On Tue, 4 Feb 2025 22:54:52 +0530
Ayush Singh <ayush@beagleboard.org> wrote:

> > 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é  
> 
> While working on a Patch series to the specification itself, I realized 
> that I was missing some edge cases, so wanted to discuss those:
> 
> # Scope
> 
> Should export-symbols only be used to resolve the properties in parent, 
> or should all other children (and their decedents) use the 
> `export-symbols` for resolving phandles and path references?
> 
> For example, should the following work:
> 
> 
> parent {
> 
>      sibling {
> 
>          led = <&gpio 0 GPIO_ACTIVE_HIGH>
> 
>      };
> 
> 
>      export-symbols {
> 
>          gpio = <&my_gpio1>;
> 
>      };
> 
> };
> 
> 
> This would also mean that bottoms up lookup needs to take place for all 
> `export-symbols` that might be present in path to root, before using top 
> level `__symbols__` or `/aliases`.

I restricted the use of export-symbols node when an overlay is applied at a node
which contains an export-symbols sub-node.

In your example, If you apply an overlay at parent node, your export-symbols
is used but if you apply an overlay at sibling node, your export-symbols is
not used.

Of course if your overlay applied at parent node looks like the following:

  __overlay__ {
    sibling {
       prop = <&gpio>;
    };
  };

&gpio will be resolved using your export-symbols. __overlay__ is applied
at parent -> visible in the overlay.

If the base device-tree looks like this:
	parent {
		sibling {
 
			export-symbols {
				gpio = <&my_gpio1>;
			};
		};
	};

The same overlay applied at parent will failed.
Indeed, no export-symbols is available at parent node and so the
gpio symbols used by the overlay will not be resolved even
if an export-symbols exists in the sibling node.
To see this export-symbols from the overlay, the overlay has to be applied
at sibling node and not parent node.

> 
> 
> # Export symbols phandles
> 
> Can export symbols reference each other? For example is the following valid:
> 
> 
> parent {
> 
>      export-symbols {
> 
>          shadow_gpio = <&my_gpio1>;
> 
>          gpio = <&shadow_gpio>;
> 
>      };
> 
> };

For sure, not planned.

Also, maybe I missed something but I am not sure you can have a
phandle referencing a property.

In your example, shadow_gpio is a property, even if we add a label
to this property i.e.
  label_shadow_gpio: shadow_gpio = <&my_gpio1>;

How can we set:
  gpio = <&label_shadow_gpio>;


Best regards,
Hervé

Re: [RFC] Adding export-symbols to specification

[Ayush Singh]

On 2/5/25 00:51, Herve Codina wrote:

> On Tue, 4 Feb 2025 22:54:52 +0530
> Ayush Singh <ayush@beagleboard.org> wrote:
>
>>> 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é
>> While working on a Patch series to the specification itself, I realized
>> that I was missing some edge cases, so wanted to discuss those:
>>
>> # Scope
>>
>> Should export-symbols only be used to resolve the properties in parent,
>> or should all other children (and their decedents) use the
>> `export-symbols` for resolving phandles and path references?
>>
>> For example, should the following work:
>>
>>
>> parent {
>>
>>     sibling {
>>
>>         led = <&gpio 0 GPIO_ACTIVE_HIGH>
>>
>>     };
>>
>>
>>     export-symbols {
>>
>>         gpio = <&my_gpio1>;
>>
>>     };
>>
>> };
>>
>>
>> This would also mean that bottoms up lookup needs to take place for all
>> `export-symbols` that might be present in path to root, before using top
>> level `__symbols__` or `/aliases`.
> I restricted the use of export-symbols node when an overlay is applied 
> at a node
> which contains an export-symbols sub-node.
>
> In your example, If you apply an overlay at parent node, your 
> export-symbols
> is used but if you apply an overlay at sibling node, your 
> export-symbols is
> not used.
>
> Of course if your overlay applied at parent node looks like the following:
>
> __overlay__ {
> sibling {
> prop = <&gpio>;
> };
> };
>
> &gpio will be resolved using your export-symbols. __overlay__ is applied
> at parent -> visible in the overlay.
>
> If the base device-tree looks like this:
> parent {
> sibling {
> export-symbols {
> gpio = <&my_gpio1>;
> };
> };
> };
>
> The same overlay applied at parent will failed.
> Indeed, no export-symbols is available at parent node and so the
> gpio symbols used by the overlay will not be resolved even
> if an export-symbols exists in the sibling node.
> To see this export-symbols from the overlay, the overlay has to be applied
> at sibling node and not parent node.

Yes, but adding export-symbols to specification would mean defining the 
behavior in base devicetree as well.


```

\ {

     parent {

         export-symbols {

             gpio = <&main_gpio0>;

         };

     };

};


&parent {

     led = <&gpio 0 GPIO_ACTIVE_HIGH>

};

```


It might not make sense to add it to devicetree specification if the 
node does not function in normal devicetree context.

>>
>> # Export symbols phandles
>>
>> Can export symbols reference each other? For example is the following 
>> valid:
>>
>>
>> parent {
>>
>>     export-symbols {
>>
>>         shadow_gpio = <&my_gpio1>;
>>
>>         gpio = <&shadow_gpio>;
>>
>>     };
>>
>> };
> For sure, not planned.
>
> Also, maybe I missed something but I am not sure you can have a
> phandle referencing a property.
>
> In your example, shadow_gpio is a property, even if we add a label
> to this property i.e.
> label_shadow_gpio: shadow_gpio = <&my_gpio1>;
>
> How can we set:
> gpio = <&label_shadow_gpio>;

Well, technically, all phandles actually just reference a property since 
they are resolved using the properties defined in `__symbols__` node or 
`/aliases`. So it is pretty simple to add the functionality described above.

> Best regards,
> Hervé
>


I have been thinking about some alternative approaches as well, and 
something that sounds nice is `/ephimeral-symbols`. Let me explain what 
I mean:

`/ephemeral-symbols` can be a global node whose properties have a single 
phandle as value. For example:


/ {
     ephemeral-symbols {
       connector1 = <&connector1>;
       gpio = <&my_gpio1>;
     };
};


This node will take precedence over `__symbols__` and will be used for 
symbol resolution. However, it will never be present in the compiled 
devicetree blob.

In case of base devicetree, it can be used to generate symbols for 
specific nodes:


/ {
     connector1 {
         prop = "1";
     };

     ephemeral-symbols {
         connector1 = <&connector1>;
     };
};


Will compile to:


/ {

     connector1 {
         prop = "1";
     };

     __symbols__ {
         connector1 = "/connector1";
     };

};


In case of addon board overlay setup, it can be used in a similar way to 
the __symbols__ proposal by Andrew [0].


So you have the base devicetree:


/ {

     connector1 {
     };

     connector2 {
     };

     ephemeral-symbols {
         connector1 = <&connector1>;
     };
};


adapter overlay:


/dts-v1/;
/plugin/;

&{/} {
     ephemeral-symbols {
         ABC_CONNECTOR = <&connector1>;
     };
};


addon board overlay:


/dts-v1/;
/plugin/;


&ABC_CONNECTOR {

     prop = "val";

};


Which will end up resolving to:


/ {

     connector1 {
         prop = "val";
     };

     connector2 {
     };

     __symbols__ {
         connector1 = "/connector1";
         connector2 = "/connector2";
     };

};


It does seem like it avoids the pitfalls of [0] (no global __symbols__ 
polluting and chaining is fine since we do not need to resize devicetree 
to resolve path references). But it might have some other flaws I am 
missing right now.



[0]: https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/

Best Regards,

Ayush Singh

Re: [RFC] Adding export-symbols to specification

[Herve Codina]

Hi Ayush,

On Wed, 5 Feb 2025 01:53:54 +0530
Ayush Singh <ayush@beagleboard.org> wrote:

> On 2/5/25 00:51, Herve Codina wrote:
> 
> > On Tue, 4 Feb 2025 22:54:52 +0530
> > Ayush Singh <ayush@beagleboard.org> wrote:
> >  
> >>> 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é  
> >> While working on a Patch series to the specification itself, I realized
> >> that I was missing some edge cases, so wanted to discuss those:
> >>
> >> # Scope
> >>
> >> Should export-symbols only be used to resolve the properties in parent,
> >> or should all other children (and their decedents) use the
> >> `export-symbols` for resolving phandles and path references?
> >>
> >> For example, should the following work:
> >>
> >>
> >> parent {
> >>
> >>     sibling {
> >>
> >>         led = <&gpio 0 GPIO_ACTIVE_HIGH>
> >>
> >>     };
> >>
> >>
> >>     export-symbols {
> >>
> >>         gpio = <&my_gpio1>;
> >>
> >>     };
> >>
> >> };
> >>
> >>
> >> This would also mean that bottoms up lookup needs to take place for all
> >> `export-symbols` that might be present in path to root, before using top
> >> level `__symbols__` or `/aliases`.  
> > I restricted the use of export-symbols node when an overlay is applied 
> > at a node
> > which contains an export-symbols sub-node.
> >
> > In your example, If you apply an overlay at parent node, your 
> > export-symbols
> > is used but if you apply an overlay at sibling node, your 
> > export-symbols is
> > not used.
> >
> > Of course if your overlay applied at parent node looks like the following:
> >
> > __overlay__ {
> > sibling {
> > prop = <&gpio>;
> > };
> > };
> >
> > &gpio will be resolved using your export-symbols. __overlay__ is applied
> > at parent -> visible in the overlay.
> >
> > If the base device-tree looks like this:
> > parent {
> > sibling {
> > export-symbols {
> > gpio = <&my_gpio1>;
> > };
> > };
> > };
> >
> > The same overlay applied at parent will failed.
> > Indeed, no export-symbols is available at parent node and so the
> > gpio symbols used by the overlay will not be resolved even
> > if an export-symbols exists in the sibling node.
> > To see this export-symbols from the overlay, the overlay has to be applied
> > at sibling node and not parent node.  
> 
> Yes, but adding export-symbols to specification would mean defining the 
> behavior in base devicetree as well.
> 
> 
> ```
> 
> \ {
> 
>      parent {
> 
>          export-symbols {
> 
>              gpio = <&main_gpio0>;
> 
>          };
> 
>      };
> 
> };
> 
> 
> &parent {
> 
>      led = <&gpio 0 GPIO_ACTIVE_HIGH>
> 
> };
> 
> ```
> 

In this example, we can consider that 'led = <&gpio 0 GPIO_ACTIVE_HIGH>' is
applied to the parent node (&parent).

Suppose:
 \ {
      node-one {
	  export-symbols {
		gpio = <&main_gpio0>;
          };
 
	  node-two {
          	export-symbols {
              		gpio = <&main_gpio1>;
          	};
	  };
      };
 };

&node-one {  <--- Applied to node-one
	my-gpio = <&gpio>;   <--- &main_gpio0 from node-one.export-symbols
};

&node-one { <--- Applied to node-one
	node-two {
		my-gpio = <&gpio>;   <--- &main_gpio0 from node-one.export-symbols
	};
};

&node-two { <--- Applied to node-two
	my-gpio = <&gpio>;   <--- &main_gpio1 from node-two.export-symbols
};

Suppose this other base DT
\ {
	node-one {
		export-symbols {
			gpio = <&main_gpio0>;
		};
		my-gpio = <&gpio>;  <--- Not allowed as there is no notion of
				         fragment applied. my-gpio was not
					 "applied" but already present in the
					 node description
	};
 };

Two questions:
- Does it make sense ?
- Is it easily implementable ?

> 
> It might not make sense to add it to devicetree specification if the 
> node does not function in normal devicetree context.
> 
> >>
> >> # Export symbols phandles
> >>
> >> Can export symbols reference each other? For example is the following 
> >> valid:
> >>
> >>
> >> parent {
> >>
> >>     export-symbols {
> >>
> >>         shadow_gpio = <&my_gpio1>;
> >>
> >>         gpio = <&shadow_gpio>;
> >>
> >>     };
> >>
> >> };  
> > For sure, not planned.
> >
> > Also, maybe I missed something but I am not sure you can have a
> > phandle referencing a property.
> >
> > In your example, shadow_gpio is a property, even if we add a label
> > to this property i.e.
> > label_shadow_gpio: shadow_gpio = <&my_gpio1>;
> >
> > How can we set:
> > gpio = <&label_shadow_gpio>;  
> 
> Well, technically, all phandles actually just reference a property since 
> they are resolved using the properties defined in `__symbols__` node or 
> `/aliases`. So it is pretty simple to add the functionality described above.

I think in __symbols__ we have labels not phandles.
At runtime, in the end, a phandles are numbers.

  some-node {
	phandle = <0x12>;
  };

  other-node {
	ref-to-some-node = <0x12>; <--- It references a node which has phandle == 0x12
  };

> 
> > Best regards,
> > Hervé
> >  
> 
> 
> I have been thinking about some alternative approaches as well, and 
> something that sounds nice is `/ephimeral-symbols`. Let me explain what 
> I mean:
> 
> `/ephemeral-symbols` can be a global node whose properties have a single 
> phandle as value. For example:
> 
> 
> / {
>      ephemeral-symbols {
>        connector1 = <&connector1>;
>        gpio = <&my_gpio1>;
>      };
> };
> 
> 
> This node will take precedence over `__symbols__` and will be used for 
> symbol resolution. However, it will never be present in the compiled 
> devicetree blob.
> 
> In case of base devicetree, it can be used to generate symbols for 
> specific nodes:
> 
> 
> / {
>      connector1 {
>          prop = "1";
>      };
> 
>      ephemeral-symbols {
>          connector1 = <&connector1>;
>      };
> };
> 
> 
> Will compile to:
> 
> 
> / {
> 
>      connector1 {
>          prop = "1";
>      };
> 
>      __symbols__ {
>          connector1 = "/connector1";
>      };
> 
> };
> 
> 
> In case of addon board overlay setup, it can be used in a similar way to 
> the __symbols__ proposal by Andrew [0].
> 
> 
> So you have the base devicetree:
> 
> 
> / {
> 
>      connector1 {
>      };
> 
>      connector2 {
>      };
> 
>      ephemeral-symbols {
>          connector1 = <&connector1>;
>      };
> };
> 
> 
> adapter overlay:
> 
> 
> /dts-v1/;
> /plugin/;
> 
> &{/} {
>      ephemeral-symbols {
>          ABC_CONNECTOR = <&connector1>;
>      };
> };
> 
> 
> addon board overlay:
> 
> 
> /dts-v1/;
> /plugin/;
> 
> 
> &ABC_CONNECTOR {
> 
>      prop = "val";
> 
> };
> 
> 
> Which will end up resolving to:
> 
> 
> / {
> 
>      connector1 {
>          prop = "val";
>      };
> 
>      connector2 {
>      };
> 
>      __symbols__ {
>          connector1 = "/connector1";
>          connector2 = "/connector2";
>      };
> 
> };

You need 2 overlays and you need to have both overlay applied in an atomic
way.

adapter-connector1.dtso then addon.dtso

You should avoid this kind of non atomic flow:
  adapter-connector1.dtso
  adapter-connector2.dtso  <--- ABC_CONNECTOR changed
  addon.dtso <--- ABC_CONNECTOR from adapter-connector2.dtso: Ok
  addon.dtso <-- ABC_CONNECTOR is no more from adapter-connector1.dtso

I really wanted to avoid this extra complexity (runtime and maintenance)
involving two overlays.

With epheral-symbols, you need to use ABC_CONNECTOR as a reference and not
a phandle. I mean:
in the overlay:
  &ABC_CONNECTOR {   <--- Use a reference: ok
      some-thing;
  };

  node {
    phandle-to-connector = <&ABC_CONNECTOR>; <--- Use as phandle: ko
  };

To use a phandle, you need to have a phandle = <0x??> property set in the node
the phandle is pointing to. In your base dt:
> / {
> 
>      connector1 {
>      };
> 
>      connector2 {
>      };
> 
>      ephemeral-symbols {
>          connector1 = <&connector1>;
>      };
> };

connector2 will not have its phandle property set unless you
  - set a label and use that label in a phandle reference in your base DT.
or
  - set a label and compile with -@ flag

On my use case, my connector node is not referenced by a phandle in my
base DT, except export-symbols.
I really don't need and don't want to export all possible symbols of my
base DT (I don't use -@ option).

An other rule we try to follow on our side (me and Luca) is:
Overlays are supposed to add or remove descriptions of new or removed
hardwares and so overlays add or remove nodes and not properties in
existing node (which means modify existing hardware).

> 
> 
> It does seem like it avoids the pitfalls of [0] (no global __symbols__ 
> polluting and chaining is fine since we do not need to resize devicetree 
> to resolve path references). But it might have some other flaws I am 
> missing right now.

I don't think we pollute the global __symbols__ with export-symbols
solution :)

Related to implementation details (resizing devicetree), my turn :)

At runtime the implementation constraint is that adding a property in an
already existing node leads to a memory leak and so adding connector2 in
__symbols__ node at runtime is an issue.

Best regards,
Hervé

Re: [RFC] Adding export-symbols to specification

[Herve Codina]

Hi Rob, David,

The export-symbols topic is a blocking point on my side to provide the
support for addon board hot-plugged on connector [0].

Can you provide some feedback on this topic in order for us (me and Ayush)
to move forward.

Best regards,
Hervé

[0]: https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/


On Wed, 5 Feb 2025 10:32:04 +0100
Herve Codina <herve.codina@bootlin.com> wrote:

> Hi Ayush,
> 
> On Wed, 5 Feb 2025 01:53:54 +0530
> Ayush Singh <ayush@beagleboard.org> wrote:
> 
> > On 2/5/25 00:51, Herve Codina wrote:
> >   
> > > On Tue, 4 Feb 2025 22:54:52 +0530
> > > Ayush Singh <ayush@beagleboard.org> wrote:
> > >    
> > >>> 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é    
> > >> While working on a Patch series to the specification itself, I realized
> > >> that I was missing some edge cases, so wanted to discuss those:
> > >>
> > >> # Scope
> > >>
> > >> Should export-symbols only be used to resolve the properties in parent,
> > >> or should all other children (and their decedents) use the
> > >> `export-symbols` for resolving phandles and path references?
> > >>
> > >> For example, should the following work:
> > >>
> > >>
> > >> parent {
> > >>
> > >>     sibling {
> > >>
> > >>         led = <&gpio 0 GPIO_ACTIVE_HIGH>
> > >>
> > >>     };
> > >>
> > >>
> > >>     export-symbols {
> > >>
> > >>         gpio = <&my_gpio1>;
> > >>
> > >>     };
> > >>
> > >> };
> > >>
> > >>
> > >> This would also mean that bottoms up lookup needs to take place for all
> > >> `export-symbols` that might be present in path to root, before using top
> > >> level `__symbols__` or `/aliases`.    
> > > I restricted the use of export-symbols node when an overlay is applied 
> > > at a node
> > > which contains an export-symbols sub-node.
> > >
> > > In your example, If you apply an overlay at parent node, your 
> > > export-symbols
> > > is used but if you apply an overlay at sibling node, your 
> > > export-symbols is
> > > not used.
> > >
> > > Of course if your overlay applied at parent node looks like the following:
> > >
> > > __overlay__ {
> > > sibling {
> > > prop = <&gpio>;
> > > };
> > > };
> > >
> > > &gpio will be resolved using your export-symbols. __overlay__ is applied
> > > at parent -> visible in the overlay.
> > >
> > > If the base device-tree looks like this:
> > > parent {
> > > sibling {
> > > export-symbols {
> > > gpio = <&my_gpio1>;
> > > };
> > > };
> > > };
> > >
> > > The same overlay applied at parent will failed.
> > > Indeed, no export-symbols is available at parent node and so the
> > > gpio symbols used by the overlay will not be resolved even
> > > if an export-symbols exists in the sibling node.
> > > To see this export-symbols from the overlay, the overlay has to be applied
> > > at sibling node and not parent node.    
> > 
> > Yes, but adding export-symbols to specification would mean defining the 
> > behavior in base devicetree as well.
> > 
> > 
> > ```
> > 
> > \ {
> > 
> >      parent {
> > 
> >          export-symbols {
> > 
> >              gpio = <&main_gpio0>;
> > 
> >          };
> > 
> >      };
> > 
> > };
> > 
> > 
> > &parent {
> > 
> >      led = <&gpio 0 GPIO_ACTIVE_HIGH>
> > 
> > };
> > 
> > ```
> >   
> 
> In this example, we can consider that 'led = <&gpio 0 GPIO_ACTIVE_HIGH>' is
> applied to the parent node (&parent).
> 
> Suppose:
>  \ {
>       node-one {
> 	  export-symbols {
> 		gpio = <&main_gpio0>;
>           };
>  
> 	  node-two {
>           	export-symbols {
>               		gpio = <&main_gpio1>;
>           	};
> 	  };
>       };
>  };
> 
> &node-one {  <--- Applied to node-one
> 	my-gpio = <&gpio>;   <--- &main_gpio0 from node-one.export-symbols
> };
> 
> &node-one { <--- Applied to node-one
> 	node-two {
> 		my-gpio = <&gpio>;   <--- &main_gpio0 from node-one.export-symbols
> 	};
> };
> 
> &node-two { <--- Applied to node-two
> 	my-gpio = <&gpio>;   <--- &main_gpio1 from node-two.export-symbols
> };
> 
> Suppose this other base DT
> \ {
> 	node-one {
> 		export-symbols {
> 			gpio = <&main_gpio0>;
> 		};
> 		my-gpio = <&gpio>;  <--- Not allowed as there is no notion of
> 				         fragment applied. my-gpio was not
> 					 "applied" but already present in the
> 					 node description
> 	};
>  };
> 
> Two questions:
> - Does it make sense ?
> - Is it easily implementable ?
> 
> > 
> > It might not make sense to add it to devicetree specification if the 
> > node does not function in normal devicetree context.
> >   
> > >>
> > >> # Export symbols phandles
> > >>
> > >> Can export symbols reference each other? For example is the following 
> > >> valid:
> > >>
> > >>
> > >> parent {
> > >>
> > >>     export-symbols {
> > >>
> > >>         shadow_gpio = <&my_gpio1>;
> > >>
> > >>         gpio = <&shadow_gpio>;
> > >>
> > >>     };
> > >>
> > >> };    
> > > For sure, not planned.
> > >
> > > Also, maybe I missed something but I am not sure you can have a
> > > phandle referencing a property.
> > >
> > > In your example, shadow_gpio is a property, even if we add a label
> > > to this property i.e.
> > > label_shadow_gpio: shadow_gpio = <&my_gpio1>;
> > >
> > > How can we set:
> > > gpio = <&label_shadow_gpio>;    
> > 
> > Well, technically, all phandles actually just reference a property since 
> > they are resolved using the properties defined in `__symbols__` node or 
> > `/aliases`. So it is pretty simple to add the functionality described above.  
> 
> I think in __symbols__ we have labels not phandles.
> At runtime, in the end, a phandles are numbers.
> 
>   some-node {
> 	phandle = <0x12>;
>   };
> 
>   other-node {
> 	ref-to-some-node = <0x12>; <--- It references a node which has phandle == 0x12
>   };
> 
> >   
> > > Best regards,
> > > Hervé
> > >    
> > 
> > 
> > I have been thinking about some alternative approaches as well, and 
> > something that sounds nice is `/ephimeral-symbols`. Let me explain what 
> > I mean:
> > 
> > `/ephemeral-symbols` can be a global node whose properties have a single 
> > phandle as value. For example:
> > 
> > 
> > / {
> >      ephemeral-symbols {
> >        connector1 = <&connector1>;
> >        gpio = <&my_gpio1>;
> >      };
> > };
> > 
> > 
> > This node will take precedence over `__symbols__` and will be used for 
> > symbol resolution. However, it will never be present in the compiled 
> > devicetree blob.
> > 
> > In case of base devicetree, it can be used to generate symbols for 
> > specific nodes:
> > 
> > 
> > / {
> >      connector1 {
> >          prop = "1";
> >      };
> > 
> >      ephemeral-symbols {
> >          connector1 = <&connector1>;
> >      };
> > };
> > 
> > 
> > Will compile to:
> > 
> > 
> > / {
> > 
> >      connector1 {
> >          prop = "1";
> >      };
> > 
> >      __symbols__ {
> >          connector1 = "/connector1";
> >      };
> > 
> > };
> > 
> > 
> > In case of addon board overlay setup, it can be used in a similar way to 
> > the __symbols__ proposal by Andrew [0].
> > 
> > 
> > So you have the base devicetree:
> > 
> > 
> > / {
> > 
> >      connector1 {
> >      };
> > 
> >      connector2 {
> >      };
> > 
> >      ephemeral-symbols {
> >          connector1 = <&connector1>;
> >      };
> > };
> > 
> > 
> > adapter overlay:
> > 
> > 
> > /dts-v1/;
> > /plugin/;
> > 
> > &{/} {
> >      ephemeral-symbols {
> >          ABC_CONNECTOR = <&connector1>;
> >      };
> > };
> > 
> > 
> > addon board overlay:
> > 
> > 
> > /dts-v1/;
> > /plugin/;
> > 
> > 
> > &ABC_CONNECTOR {
> > 
> >      prop = "val";
> > 
> > };
> > 
> > 
> > Which will end up resolving to:
> > 
> > 
> > / {
> > 
> >      connector1 {
> >          prop = "val";
> >      };
> > 
> >      connector2 {
> >      };
> > 
> >      __symbols__ {
> >          connector1 = "/connector1";
> >          connector2 = "/connector2";
> >      };
> > 
> > };  
> 
> You need 2 overlays and you need to have both overlay applied in an atomic
> way.
> 
> adapter-connector1.dtso then addon.dtso
> 
> You should avoid this kind of non atomic flow:
>   adapter-connector1.dtso
>   adapter-connector2.dtso  <--- ABC_CONNECTOR changed
>   addon.dtso <--- ABC_CONNECTOR from adapter-connector2.dtso: Ok
>   addon.dtso <-- ABC_CONNECTOR is no more from adapter-connector1.dtso
> 
> I really wanted to avoid this extra complexity (runtime and maintenance)
> involving two overlays.
> 
> With epheral-symbols, you need to use ABC_CONNECTOR as a reference and not
> a phandle. I mean:
> in the overlay:
>   &ABC_CONNECTOR {   <--- Use a reference: ok
>       some-thing;
>   };
> 
>   node {
>     phandle-to-connector = <&ABC_CONNECTOR>; <--- Use as phandle: ko
>   };
> 
> To use a phandle, you need to have a phandle = <0x??> property set in the node
> the phandle is pointing to. In your base dt:
> > / {
> > 
> >      connector1 {
> >      };
> > 
> >      connector2 {
> >      };
> > 
> >      ephemeral-symbols {
> >          connector1 = <&connector1>;
> >      };
> > };  
> 
> connector2 will not have its phandle property set unless you
>   - set a label and use that label in a phandle reference in your base DT.
> or
>   - set a label and compile with -@ flag
> 
> On my use case, my connector node is not referenced by a phandle in my
> base DT, except export-symbols.
> I really don't need and don't want to export all possible symbols of my
> base DT (I don't use -@ option).
> 
> An other rule we try to follow on our side (me and Luca) is:
> Overlays are supposed to add or remove descriptions of new or removed
> hardwares and so overlays add or remove nodes and not properties in
> existing node (which means modify existing hardware).
> 
> > 
> > 
> > It does seem like it avoids the pitfalls of [0] (no global __symbols__ 
> > polluting and chaining is fine since we do not need to resize devicetree 
> > to resolve path references). But it might have some other flaws I am 
> > missing right now.  
> 
> I don't think we pollute the global __symbols__ with export-symbols
> solution :)
> 
> Related to implementation details (resizing devicetree), my turn :)
> 
> At runtime the implementation constraint is that adding a property in an
> already existing node leads to a memory leak and so adding connector2 in
> __symbols__ node at runtime is an issue.
> 
> Best regards,
> Hervé



-- 
Hervé Codina, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [RFC] Adding export-symbols to specification

[Ayush Singh]

On 2/5/25 15:02, Herve Codina wrote:

> [snip]
>
> Best regards,
> Hervé


Thanks for the clarification. After thinking about it, a ghost node 
which does not appear in the tree can make it very difficult for 
debugging as well. So I think export-symbols are the way to go.


I will just send a patch series adding it to the spec since no one has 
raised any objections


Best regards,

Ayush Singh

Re: [RFC] Adding export-symbols to specification

[Quentin Schulz]

Hi Ayush,

This is actually quite interesting. I don't know exactly how far we 
could push this.

FYI, we have a Q7 carrierboard which supports three different modules 
today. This carrierboard currently has two adapter boards that are 
compatible with all three modules. One is Haikou Video Demo, see patch 
here: 
https://lore.kernel.org/linux-rockchip/20241127143719.660658-4-heiko@sntech.de/

We could resolve differences in i2c bus by adding another label to the 
bus node that is exposed on the connector, so that isn't much of an 
issue. MIPI DSI PHY and controller may be a different story as those may 
have different bindings that would make it difficult to support with one 
overlay? Haven't checked yet though. See [1] and [2] for the DTS (not 
yet overlays...) of the other two SoM that this adapter works with. 
However, this would resolve the issue of having different GPIOs for 
reset and interrupt lines. Anyway, I'm not sure this export-symbols 
stuff would actually help us, just being curious here, will keep an eye 
on it but probably won't be able to help much.

[1] 
https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/px30-ringneck-haikou-video-demo.dts?h=v6.6.39-puma
[2] 
https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/rk3399-puma-haikou-video-demo.dts?h=v6.6.39-puma

On 1/27/25 2:45 PM, Ayush Singh wrote:
[...]
> 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'm not sure to understand how the tooling would figure out to which 
connector of the baseboard should the overlay be applied?

In the case of a single connector and a single overlay, that's fine. But 
in the case of 2+ connectors, 2+ adapters but a single overlay, how does 
the system know which connector it should resolve the "connector" part 
in the overlay? Is there some tooling involved? E.g. providing an 
argument (like which connector from the board to use?). Or are you 
expecting that applying the overlay once will pick connector1 and 
applying the overlay a second time would pick connector2? If you have 
multiple overlays for different adapters using this connector 
abstraction, the first one to be applied would be the on the first 
connector and then the second on the second one? What if I have nothing 
connected on connector 1 but on connector 2, how do I specify to which 
connector the overlay should apply?

Cheers,
Quentin

Re: [RFC] Adding export-symbols to specification

[Herve Codina]

Hi Quentin,

On Thu, 30 Jan 2025 17:47:16 +0100
Quentin Schulz <quentin.schulz@cherry.de> wrote:

> Hi Ayush,
> 
> This is actually quite interesting. I don't know exactly how far we 
> could push this.
> 
> FYI, we have a Q7 carrierboard which supports three different modules 
> today. This carrierboard currently has two adapter boards that are 
> compatible with all three modules. One is Haikou Video Demo, see patch 
> here: 
> https://lore.kernel.org/linux-rockchip/20241127143719.660658-4-heiko@sntech.de/
> 
> We could resolve differences in i2c bus by adding another label to the 
> bus node that is exposed on the connector, so that isn't much of an 
> issue. MIPI DSI PHY and controller may be a different story as those may 
> have different bindings that would make it difficult to support with one 
> overlay? Haven't checked yet though. See [1] and [2] for the DTS (not 
> yet overlays...) of the other two SoM that this adapter works with. 
> However, this would resolve the issue of having different GPIOs for 
> reset and interrupt lines. Anyway, I'm not sure this export-symbols 
> stuff would actually help us, just being curious here, will keep an eye 
> on it but probably won't be able to help much.
> 
> [1] 
> https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/px30-ringneck-haikou-video-demo.dts?h=v6.6.39-puma
> [2] 
> https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/rk3399-puma-haikou-video-demo.dts?h=v6.6.39-puma
> 

Related to buses like i2c or even DSI, we are working on it.

We have presented the big picture in
  https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-0-bc4dfee61be6@bootlin.com/
When this series was sent, export-symbols and nexus node were not present.
A talk has been done at Plumbers:
  https://lpc.events/event/18/contributions/1696/
An the nexus node came from Plumbers discussion and export-symbols came right
after in order to solve symbols resolution.

Back to i2c bus, we have proposed the following:
  https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-5-bc4dfee61be6@bootlin.com/

I recently took the i2c topic and I plan to send an updated iteration with
issue fixed using the 'i2c-parent' and 'i2c-bus-extension'.

On DSI bus, my colleague Luca is working on it. He already extracted specific
DRM modification out of the big picture and sent a dedicated series:
  https://lore.kernel.org/all/20241231-hotplug-drm-bridge-v5-0-173065a1ece1@bootlin.com/

I hope those pointers will show you the direction we take and maybe help
in your issues.

> On 1/27/25 2:45 PM, Ayush Singh wrote:
> [...]
> > 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'm not sure to understand how the tooling would figure out to which 
> connector of the baseboard should the overlay be applied?
> 
> In the case of a single connector and a single overlay, that's fine. But 
> in the case of 2+ connectors, 2+ adapters but a single overlay, how does 
> the system know which connector it should resolve the "connector" part 
> in the overlay? Is there some tooling involved? E.g. providing an 
> argument (like which connector from the board to use?). Or are you 
> expecting that applying the overlay once will pick connector1 and 
> applying the overlay a second time would pick connector2? If you have 
> multiple overlays for different adapters using this connector 
> abstraction, the first one to be applied would be the on the first 
> connector and then the second on the second one? What if I have nothing 
> connected on connector 1 but on connector 2, how do I specify to which 
> connector the overlay should apply?

In my case, I have a driver for the connector and our driver apply the
overlay.

The symbol resolution is done at runtime by the kernel when the overlay is
applied by the driver.
  https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/

The related driver applying the overlay:
  https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-8-bc4dfee61be6@bootlin.com/
Even if some modification are still needed in this driver, the base ideas are
already present.

Best regards,
Hervé

Re: [RFC] Adding export-symbols to specification

[Ayush Singh]

On 1/30/25 23:37, Herve Codina wrote:

> Hi Quentin,
>
> On Thu, 30 Jan 2025 17:47:16 +0100
> Quentin Schulz <quentin.schulz@cherry.de> wrote:
>
>> Hi Ayush,
>>
>> This is actually quite interesting. I don't know exactly how far we
>> could push this.
>>
>> FYI, we have a Q7 carrierboard which supports three different modules
>> today. This carrierboard currently has two adapter boards that are
>> compatible with all three modules. One is Haikou Video Demo, see patch
>> here:
>> https://lore.kernel.org/linux-rockchip/20241127143719.660658-4-heiko@sntech.de/
>>
>> We could resolve differences in i2c bus by adding another label to the
>> bus node that is exposed on the connector, so that isn't much of an
>> issue. MIPI DSI PHY and controller may be a different story as those may
>> have different bindings that would make it difficult to support with one
>> overlay? Haven't checked yet though. See [1] and [2] for the DTS (not
>> yet overlays...) of the other two SoM that this adapter works with.
>> However, this would resolve the issue of having different GPIOs for
>> reset and interrupt lines. Anyway, I'm not sure this export-symbols
>> stuff would actually help us, just being curious here, will keep an eye
>> on it but probably won't be able to help much.
>>
>> [1]
>> https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/px30-ringneck-haikou-video-demo.dts?h=v6.6.39-puma
>> [2]
>> https://git.theobroma-systems.com/puma-linux.git/tree/arch/arm64/boot/dts/rockchip/rk3399-puma-haikou-video-demo.dts?h=v6.6.39-puma
>>
> Related to buses like i2c or even DSI, we are working on it.
>
> We have presented the big picture in
>    https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-0-bc4dfee61be6@bootlin.com/
> When this series was sent, export-symbols and nexus node were not present.
> A talk has been done at Plumbers:
>    https://lpc.events/event/18/contributions/1696/
> An the nexus node came from Plumbers discussion and export-symbols came right
> after in order to solve symbols resolution.
>
> Back to i2c bus, we have proposed the following:
>    https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-5-bc4dfee61be6@bootlin.com/
>
> I recently took the i2c topic and I plan to send an updated iteration with
> issue fixed using the 'i2c-parent' and 'i2c-bus-extension'.
>
> On DSI bus, my colleague Luca is working on it. He already extracted specific
> DRM modification out of the big picture and sent a dedicated series:
>    https://lore.kernel.org/all/20241231-hotplug-drm-bridge-v5-0-173065a1ece1@bootlin.com/
>
> I hope those pointers will show you the direction we take and maybe help
> in your issues.
>
>> On 1/27/25 2:45 PM, Ayush Singh wrote:
>> [...]
>>> 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'm not sure to understand how the tooling would figure out to which
>> connector of the baseboard should the overlay be applied?
>>
>> In the case of a single connector and a single overlay, that's fine. But
>> in the case of 2+ connectors, 2+ adapters but a single overlay, how does
>> the system know which connector it should resolve the "connector" part
>> in the overlay? Is there some tooling involved? E.g. providing an
>> argument (like which connector from the board to use?). Or are you
>> expecting that applying the overlay once will pick connector1 and
>> applying the overlay a second time would pick connector2? If you have
>> multiple overlays for different adapters using this connector
>> abstraction, the first one to be applied would be the on the first
>> connector and then the second on the second one? What if I have nothing
>> connected on connector 1 but on connector 2, how do I specify to which
>> connector the overlay should apply?
> In my case, I have a driver for the connector and our driver apply the
> overlay.
>
> The symbol resolution is done at runtime by the kernel when the overlay is
> applied by the driver.
>    https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/
>
> The related driver applying the overlay:
>    https://lore.kernel.org/all/20240917-hotplug-drm-bridge-v4-8-bc4dfee61be6@bootlin.com/
> Even if some modification are still needed in this driver, the base ideas are
> already present.
>
> Best regards,
> Hervé


I am also planning to add argument for specifying target in fdtoverlay 
(to support application using uboot, etc). So something like:


fdtoverlay overlay.dtbo --target "/path/to/connector"


Best regards,

Ayush Singh