[PATCH v3] Add new `export-symbols` node

[PATCH v3] Add new `export-symbols` node

[Ayush Singh]

`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.

Reviewed-by: Herve Codina <herve.codina@bootlin.com>
Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Ayush Singh <ayush@beagleboard.org>
---
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.

Linux kernel already provides APIs to apply overlays at specific nodes
[10], and I have a patch series to have similar functionality in
fdtoverlay [11]. This is to allow writing overlays for addon-boards,
that will be expected to be applied to the connector nodes, instead of
on the global tree.

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 some resources like GPIO and PWM from the overlay.
However, that still leaves things like pinmux, i2c adapter, etc.

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. This allows specifying the
phandles to i2c adapter, pinmux, etc, per connector. Since the names
used for these phandles for each connector can be standardized, it would
allow having the same addon-board overaly work for connectors on
different boards (or multiple connectors on the same board).

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 {
	    GPIO_CONNECTOR = <&connector1>;
	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
        };
    };

Our overlay can use thi

   leds {
      pinctrl-names = "default";
      pinctrl-0 = <&PIN_33_GPIO_PINMUX>;

      led-1 {
          gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
      };
   };

It used the P1_33 pin in the connector it is applied on.

A board with two connectors can be described with:

    connector1: connector1 {
        ...
        export-symbols {
	    GPIO_CONNECTOR = <&connector1>;
	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
        };
    };

    connector2: connector2 {
        ...
        export-symbols {
	    GPIO_CONNECTOR = <&connector2>;
	    PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
        };
    };

In that case, the same overlay with unresolved `GPIO_CONNECTOR` and 
`PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the 
correct symbol resolution 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.

[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
[9]: https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
[10]: https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
[11]: https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t

Best Regards,
Ayush Singh
---
Changes in v3:
- Add trailer
- CC linux-devicetree
- Link to v2: https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org

Changes in v2:
- Improve examples. More focus on export-symbols and less on nexus nodes
- Fix typo.
- Link to v1: https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
---
 source/chapter3-devicenodes.rst | 89 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
index 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 100644
--- a/source/chapter3-devicenodes.rst
+++ b/source/chapter3-devicenodes.rst
@@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
             };
         };
     };
+
+``*/export-symbols`` node
+-------------------------
+A devicetree node may have an export-symbols child node
+(`*/export-symbols`) that defines one or more export-symbol properties.
+
+Each property of the `export-symbols` node defines an alias local to it's
+parent. The property name specifies the alias name. The property value
+specifies the phandle to a node in the devicetree. For example, the
+property ``serial0 = <&main_uart0>`` defines ``serial0`` as the local alias
+to ``main_uart0``.
+
+Alias names shall be lowercase text strings of 1 to 31 characters from the
+following set of characters.
+
+.. tabularcolumns:: | c p{8cm} |
+.. table:: Valid characters for alias names
+
+   ========= ================
+   Character Description
+   ========= ================
+   0-9       digit
+   a-z       lowercase letter
+   \-        dash
+   ========= ================
+
+An alias value is a phandle to a node in the devicetree.
+
+Resolution of nodes using `export-symbols` follows the following rules
+depending on the context:
+
+No target involved
+~~~~~~~~~~~~~~~~~~~
+Properties of parent node use symbols from ``export-symbols``, but none of
+the subnodes will be able to use them. For example, the following code will
+resolve properly:
+
+.. code-block:: dts
+
+    / {
+        parent {
+            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
+
+            export-symbols {
+                local_gpio = <&gpio0>;
+            };
+        };
+    }
+
+However, the code below is not valid:
+
+.. code-block:: dts
+
+    / {
+        parent {
+            child {
+                /* child node cannot access export-symbols */
+                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
+            };
+
+            export-symbols {
+                local_gpio = <&gpio0>;
+            };
+        };
+    }
+
+Target is used in the base devicetree or overlays
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Any node/subnode property is free to use symbols from ``export-symbols``
+defined in the parent. To provide a concrete exampe, the following is
+valid:
+
+.. code-block:: dts
+
+    / {
+        parent {
+            export-symbols {
+                local_gpio = <&gpio0>;
+            };
+        };
+    }
+
+    &parent {
+        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
+
+        child {
+            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
+        };
+    };

---
base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
change-id: 20250225-export-symbols-3524f124cd93

Best regards,
-- 
Ayush Singh <ayush@beagleboard.org>

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

[Andrew Davis]

On 4/11/25 3:00 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.
> 
> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
> ---
> 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.
> 

I think this is a useful tool in the effort to build a complete addon-board
solution. But I'm still missing how it all fits together, do you have a real
working overlay making use of this somewhere I could take a look at? Maybe
an overlay for one of the addon-boards you list below (one of the BeagleCapes
for instance).

Andrew

> 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.
> 
> Linux kernel already provides APIs to apply overlays at specific nodes
> [10], and I have a patch series to have similar functionality in
> fdtoverlay [11]. This is to allow writing overlays for addon-boards,
> that will be expected to be applied to the connector nodes, instead of
> on the global tree.
> 
> 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 some resources like GPIO and PWM from the overlay.
> However, that still leaves things like pinmux, i2c adapter, etc.
> 
> 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. This allows specifying the
> phandles to i2c adapter, pinmux, etc, per connector. Since the names
> used for these phandles for each connector can be standardized, it would
> allow having the same addon-board overaly work for connectors on
> different boards (or multiple connectors on the same board).
> 
> 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 {
> 	    GPIO_CONNECTOR = <&connector1>;
> 	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>          };
>      };
> 
> Our overlay can use thi
> 
>     leds {
>        pinctrl-names = "default";
>        pinctrl-0 = <&PIN_33_GPIO_PINMUX>;
> 
>        led-1 {
>            gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
>        };
>     };
> 
> It used the P1_33 pin in the connector it is applied on.
> 
> A board with two connectors can be described with:
> 
>      connector1: connector1 {
>          ...
>          export-symbols {
> 	    GPIO_CONNECTOR = <&connector1>;
> 	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>          };
>      };
> 
>      connector2: connector2 {
>          ...
>          export-symbols {
> 	    GPIO_CONNECTOR = <&connector2>;
> 	    PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
>          };
>      };
> 
> In that case, the same overlay with unresolved `GPIO_CONNECTOR` and
> `PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the
> correct symbol resolution 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.
> 
> [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
> [9]: https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
> [10]: https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
> [11]: https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t
> 
> Best Regards,
> Ayush Singh
> ---
> Changes in v3:
> - Add trailer
> - CC linux-devicetree
> - Link to v2: https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org
> 
> Changes in v2:
> - Improve examples. More focus on export-symbols and less on nexus nodes
> - Fix typo.
> - Link to v1: https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
> ---
>   source/chapter3-devicenodes.rst | 89 +++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 89 insertions(+)
> 
> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> index 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 100644
> --- a/source/chapter3-devicenodes.rst
> +++ b/source/chapter3-devicenodes.rst
> @@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
>               };
>           };
>       };
> +
> +``*/export-symbols`` node
> +-------------------------
> +A devicetree node may have an export-symbols child node
> +(`*/export-symbols`) that defines one or more export-symbol properties.
> +
> +Each property of the `export-symbols` node defines an alias local to it's
> +parent. The property name specifies the alias name. The property value
> +specifies the phandle to a node in the devicetree. For example, the
> +property ``serial0 = <&main_uart0>`` defines ``serial0`` as the local alias
> +to ``main_uart0``.
> +
> +Alias names shall be lowercase text strings of 1 to 31 characters from the
> +following set of characters.
> +
> +.. tabularcolumns:: | c p{8cm} |
> +.. table:: Valid characters for alias names
> +
> +   ========= ================
> +   Character Description
> +   ========= ================
> +   0-9       digit
> +   a-z       lowercase letter
> +   \-        dash
> +   ========= ================
> +
> +An alias value is a phandle to a node in the devicetree.
> +
> +Resolution of nodes using `export-symbols` follows the following rules
> +depending on the context:
> +
> +No target involved
> +~~~~~~~~~~~~~~~~~~~
> +Properties of parent node use symbols from ``export-symbols``, but none of
> +the subnodes will be able to use them. For example, the following code will
> +resolve properly:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +However, the code below is not valid:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            child {
> +                /* child node cannot access export-symbols */
> +                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +            };
> +
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +Target is used in the base devicetree or overlays
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Any node/subnode property is free to use symbols from ``export-symbols``
> +defined in the parent. To provide a concrete exampe, the following is
> +valid:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +    &parent {
> +        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +
> +        child {
> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +        };
> +    };
> 
> ---
> base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
> change-id: 20250225-export-symbols-3524f124cd93
> 
> Best regards,

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

[Ayush Singh]

On 4/11/25 23:09, Andrew Davis wrote:

> On 4/11/25 3:00 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.
>>
>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>> ---
>> 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.
>>
>
> I think this is a useful tool in the effort to build a complete 
> addon-board
> solution. But I'm still missing how it all fits together, do you have 
> a real
> working overlay making use of this somewhere I could take a look at? 
> Maybe
> an overlay for one of the addon-boards you list below (one of the 
> BeagleCapes
> for instance).
>
> Andrew


Well, I do not have a completely working for MikroBUS right now, but I 
think Herve Codina and Luca Ceresolli should have some working overlays 
for their addon-board setups, so maybe they can link those here. I have 
mostly been working on devicetree side of things to make it more general 
devicetree thing rather just a Linux thing (Zephyr also needs MikroBUS 
support). Additionally, I have been trying to get the support in base 
fdtoverlay, so that static use-cases are also covered.

I will try posting a MikroBUS patch based on the kernel export-symbols 
support patches [0] soon to maybe provide a better picture regarding how 
all the pieces fit together. The spec patch series was supposed to be 
for getting initial feedback regarding this particular direction, but I 
guess to get real feedback, I need some more concrete prototypes.


Best Regards,

Ayush Singh


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

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

[Herve Codina]

Hi Ayush, David,

On Sat, 12 Apr 2025 00:19:16 +0530
Ayush Singh <ayush@beagleboard.org> wrote:

> On 4/11/25 23:09, Andrew Davis wrote:
> 
> > On 4/11/25 3:00 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.
> >>
> >> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> >> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> >> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
> >> ---
> >> 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.
> >>  
> >
> > I think this is a useful tool in the effort to build a complete 
> > addon-board
> > solution. But I'm still missing how it all fits together, do you have 
> > a real
> > working overlay making use of this somewhere I could take a look at? 
> > Maybe
> > an overlay for one of the addon-boards you list below (one of the 
> > BeagleCapes
> > for instance).
> >

We (me and Luca) have a working device-tree and overlay.

Our base device tree is the following (simplified but relevant part for
this topic are available):
/ {
	...

	addon_connector0: addon-connector0 {
		compatible = "gehc,sunhv1-addon-connector";

		/*
		 * addon-connector node is a nexus node
		 *  - 2 interupt lines are wired to the connector
		 *  - 1 gpio line is wired to the connector
		 *  - 1 PWM is wired to the connector
		 */
		#interrupt-cells = <2>;
		#address-cells = <0>;
		interrupt-map = <0 IRQ_TYPE_LEVEL_LOW    &gpio4 1 IRQ_TYPE_LEVEL_LOW>,
				<0 IRQ_TYPE_EDGE_FALLING &gpio4 1 IRQ_TYPE_EDGE_FALLING>,
				<1 IRQ_TYPE_LEVEL_LOW    &i2c3_mux 1 1 IRQ_TYPE_LEVEL_LOW>,
				<1 IRQ_TYPE_EDGE_FALLING &i2c3_mux 1 1 IRQ_TYPE_EDGE_FALLING>;
		#gpio-cells = <2>;
		gpio-map-mask = <0xf 0x0>;
		gpio-map-pass-thru = <0x0 0xf>;
		gpio-map = <0 0 &gpio4 1 0>;
		#pwm-cells = <3>;
		pwm-map-mask = <0xffffffff 0 0>;
		pwm-map-pass-thru = <0 0xffffffff 0xffffffff>;
		pwm-map = <0 0 0 &pwm1 0 57000 0>;


		devices {
			/*
			 * 'no bus' devices such as fixed-regulators or
			 * fixed-clocks will be added in this node by the
			 * overlay.
			 */
			#address-cells = <0>;
			#size-cells = <0>;
		};

		/*
		 * This is the i2c bus wired at the connector. It is
		 * handled by the i2c5 adapter available in the SoC.
		 * The overlay will add devices in this node. Those
		 * devices are devices available on the addon-board and
		 * connected to this i2c bus
		 */
		i2c-addon {
			i2c-parent = <&i2c5>;
			#address-cells = <1>;
			#size-cells = <0>;
		};

		export-symbols {
			/*
			 * The 'addon_connector' symbol can be used from the
			 * overlay to reference this connector
			 */
			addon_connector = <&addon_connector0>;
		};
	};
};


Then following overlay is applied at the addon-connector0 node and described
the addon board connected to the connector:

/ {
	fragment@0 {
		target-path = "";

		__overlay__ {
			devices {
				reg_addon_3v3: regulator-addon-3v3 {
					compatible = "regulator-fixed";
					regulator-name = "3V3_ADDON";
					regulator-min-microvolt = <15000000>;
					regulator-max-microvolt = <15000000>;
					regulator-always-on;
				};

				reg_addon_12v0: regulator-addon-12v0 {
					compatible = "regulator-fixed";
					regulator-name = "12V0_ADDON";
					vin-supply = <&reg_addon_3v3>;
					regulator-min-microvolt = <12000000>;
					regulator-max-microvolt = <12000000>;
					gpios = <&tca6424_addon 12 GPIO_ACTIVE_HIGH>;
					enable-active-high;
				};

				/*
				 * This backligh is a PWM driven backlight.
				 * It uses the PWM #0 available at the connector
				 */
				backlight_addon: backlight-addon {
					compatible = "pwm-backlight";
					power-supply = <&reg_addon_12v0>;
					pwms = <&addon_connector 0 57000 0>;
					brightness-levels = <0 255>;
					num-interpolated-steps = <255>;
					default-brightness-level = <255>;
				};
			};

			i2c-addon {
				#address-cells = <1>;
				#size-cells = <0>;

				/*
				 * This IO expander uses the interrupt #0
				 * available at the connector.
				 * It is a device connected to the i2c-addon bus
				 * available at the connector.
				 */
				tca6424_addon: gpio@23 {
					compatible = "ti,tca6424";
					status = "okay";
					reg = <0x23>;
					gpio-controller;
					#gpio-cells = <2>;
					interrupt-parent = <&addon_connector>;
					interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
					interrupt-controller;
					#interrupt-cells = <2>;
					vcc-supply = <&reg_addon_3v3>;
				};
			};
		};
	};
};


Best regards,
Hervé

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

[Andrew Davis]

On 4/14/25 9:46 AM, Herve Codina wrote:
> Hi Ayush, David,
> 
> On Sat, 12 Apr 2025 00:19:16 +0530
> Ayush Singh <ayush@beagleboard.org> wrote:
> 
>> On 4/11/25 23:09, Andrew Davis wrote:
>>
>>> On 4/11/25 3:00 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.
>>>>
>>>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>>>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>>>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>>>> ---
>>>> 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.
>>>>   
>>>
>>> I think this is a useful tool in the effort to build a complete
>>> addon-board
>>> solution. But I'm still missing how it all fits together, do you have
>>> a real
>>> working overlay making use of this somewhere I could take a look at?
>>> Maybe
>>> an overlay for one of the addon-boards you list below (one of the
>>> BeagleCapes
>>> for instance).
>>>
> 
> We (me and Luca) have a working device-tree and overlay.
> 
> Our base device tree is the following (simplified but relevant part for
> this topic are available):
> / {
> 	...
> 
> 	addon_connector0: addon-connector0 {
> 		compatible = "gehc,sunhv1-addon-connector";
> 
> 		/*
> 		 * addon-connector node is a nexus node
> 		 *  - 2 interupt lines are wired to the connector
> 		 *  - 1 gpio line is wired to the connector
> 		 *  - 1 PWM is wired to the connector
> 		 */
> 		#interrupt-cells = <2>;
> 		#address-cells = <0>;
> 		interrupt-map = <0 IRQ_TYPE_LEVEL_LOW    &gpio4 1 IRQ_TYPE_LEVEL_LOW>,
> 				<0 IRQ_TYPE_EDGE_FALLING &gpio4 1 IRQ_TYPE_EDGE_FALLING>,
> 				<1 IRQ_TYPE_LEVEL_LOW    &i2c3_mux 1 1 IRQ_TYPE_LEVEL_LOW>,
> 				<1 IRQ_TYPE_EDGE_FALLING &i2c3_mux 1 1 IRQ_TYPE_EDGE_FALLING>;
> 		#gpio-cells = <2>;
> 		gpio-map-mask = <0xf 0x0>;
> 		gpio-map-pass-thru = <0x0 0xf>;
> 		gpio-map = <0 0 &gpio4 1 0>;

This isn't a thing, or do you plan to add nexus nodes / map bindings for all possible
enumerated items in DT? Not sure this will scale well :/

> 		#pwm-cells = <3>;
> 		pwm-map-mask = <0xffffffff 0 0>;
> 		pwm-map-pass-thru = <0 0xffffffff 0xffffffff>;
> 		pwm-map = <0 0 0 &pwm1 0 57000 0>;
> 
> 
> 		devices {

What is this node? I'm assuming this is something the "connector driver" for
this connector will look for and populate subnodes? What about simple connectors
where no driver should be needed?

> 			/*
> 			 * 'no bus' devices such as fixed-regulators or
> 			 * fixed-clocks will be added in this node by the
> 			 * overlay.
> 			 */
> 			#address-cells = <0>;
> 			#size-cells = <0>;
> 		};
> 
> 		/*
> 		 * This is the i2c bus wired at the connector. It is
> 		 * handled by the i2c5 adapter available in the SoC.
> 		 * The overlay will add devices in this node. Those
> 		 * devices are devices available on the addon-board and
> 		 * connected to this i2c bus
> 		 */
> 		i2c-addon {
> 			i2c-parent = <&i2c5>;

What if this I2C instance is not enabled (maybe not an issue for I2C,
but some devices should have their status left disabled unless something
is connected, SPI for instance).

And this (I2C) only works because there is this `i2c-parent` thing, but that
isn't the case for most (e.g. there is no spi-parent, mdio-parent, etc..)
My proposal[0] handles that by giving standard names to the provider phandles
that conforming add-on board overlays can reference directly.

> 			#address-cells = <1>;
> 			#size-cells = <0>;
> 		};
> 
> 		export-symbols {
> 			/*
> 			 * The 'addon_connector' symbol can be used from the
> 			 * overlay to reference this connector
> 			 */
> 			addon_connector = <&addon_connector0>;
> 		};
> 	};
> };
> 
> 
> Then following overlay is applied at the addon-connector0 node and described

*How* is this "applied at the addon-connector0 node"?

Again I'm going to guess this is if we are able to modify the `fdtapply` tool
to accept connection points as a new command line parameter. And then somehow
do the same for all other projects that apply DT overlays (U-Boot, Zephyr, etc.).

And in that case, we would have to pass in the name of the connector anyway,
so having that name be the only item in `export-symbols` doesn't get us anything
new, we could have just passed the connector name directly.

BTW, this is solved in my proposal[0] with adapter/shim overlays. Which allow for
this to work without any modifying the overlay tooling. Maybe there is a way we
can put this new `export-symbols` node in the adapter overlay to avoid passing
in the connector name directly to the tooling.. I have to think on this.

> the addon board connected to the connector:
> 
> / {
> 	fragment@0 {
> 		target-path = "";
> 
> 		__overlay__ {
> 			devices {
> 				reg_addon_3v3: regulator-addon-3v3 {
> 					compatible = "regulator-fixed";

Is this really a fixed regulator on the add-on board or is this being feed
from the main board's PMIC but you have no good way to model that connection
with this scheme? This breaks the regulator/power dependency graph. If a
device on the add-on board powers down, that information is no longer sent
back to the parent PMIC and the power rail will be needlessly left enabled.

This is why I was looking for a full complete example, not a simplified one.
I'm having to make too many assumptions here to give this `export-symbols`
thing a proper review.

Andrew

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

> 					regulator-name = "3V3_ADDON";
> 					regulator-min-microvolt = <15000000>;
> 					regulator-max-microvolt = <15000000>;
> 					regulator-always-on;
> 				};
> 
> 				reg_addon_12v0: regulator-addon-12v0 {
> 					compatible = "regulator-fixed";
> 					regulator-name = "12V0_ADDON";
> 					vin-supply = <&reg_addon_3v3>;
> 					regulator-min-microvolt = <12000000>;
> 					regulator-max-microvolt = <12000000>;
> 					gpios = <&tca6424_addon 12 GPIO_ACTIVE_HIGH>;
> 					enable-active-high;
> 				};
> 
> 				/*
> 				 * This backligh is a PWM driven backlight.
> 				 * It uses the PWM #0 available at the connector
> 				 */
> 				backlight_addon: backlight-addon {
> 					compatible = "pwm-backlight";
> 					power-supply = <&reg_addon_12v0>;
> 					pwms = <&addon_connector 0 57000 0>;
> 					brightness-levels = <0 255>;
> 					num-interpolated-steps = <255>;
> 					default-brightness-level = <255>;
> 				};
> 			};
> 
> 			i2c-addon {
> 				#address-cells = <1>;
> 				#size-cells = <0>;
> 
> 				/*
> 				 * This IO expander uses the interrupt #0
> 				 * available at the connector.
> 				 * It is a device connected to the i2c-addon bus
> 				 * available at the connector.
> 				 */
> 				tca6424_addon: gpio@23 {
> 					compatible = "ti,tca6424";
> 					status = "okay";
> 					reg = <0x23>;
> 					gpio-controller;
> 					#gpio-cells = <2>;
> 					interrupt-parent = <&addon_connector>;
> 					interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
> 					interrupt-controller;
> 					#interrupt-cells = <2>;
> 					vcc-supply = <&reg_addon_3v3>;
> 				};
> 			};
> 		};
> 	};
> };
> 
> 
> Best regards,
> Hervé
> 

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

[Ayush Singh]

On 4/14/25 22:04, Andrew Davis wrote:
> On 4/14/25 9:46 AM, Herve Codina wrote:
>> Hi Ayush, David,
>>
>> On Sat, 12 Apr 2025 00:19:16 +0530
>> Ayush Singh <ayush@beagleboard.org> wrote:
>>
>>> On 4/11/25 23:09, Andrew Davis wrote:
>>>
>>>> On 4/11/25 3:00 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.
>>>>>
>>>>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>>>>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>>>>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>>>>> ---
>>>>> 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.
>>>>
>>>> I think this is a useful tool in the effort to build a complete
>>>> addon-board
>>>> solution. But I'm still missing how it all fits together, do you have
>>>> a real
>>>> working overlay making use of this somewhere I could take a look at?
>>>> Maybe
>>>> an overlay for one of the addon-boards you list below (one of the
>>>> BeagleCapes
>>>> for instance).
>>>>
>>
>> We (me and Luca) have a working device-tree and overlay.
>>
>> Our base device tree is the following (simplified but relevant part for
>> this topic are available):
>> / {
>>     ...
>>
>>     addon_connector0: addon-connector0 {
>>         compatible = "gehc,sunhv1-addon-connector";
>>
>>         /*
>>          * addon-connector node is a nexus node
>>          *  - 2 interupt lines are wired to the connector
>>          *  - 1 gpio line is wired to the connector
>>          *  - 1 PWM is wired to the connector
>>          */
>>         #interrupt-cells = <2>;
>>         #address-cells = <0>;
>>         interrupt-map = <0 IRQ_TYPE_LEVEL_LOW    &gpio4 1 
>> IRQ_TYPE_LEVEL_LOW>,
>>                 <0 IRQ_TYPE_EDGE_FALLING &gpio4 1 
>> IRQ_TYPE_EDGE_FALLING>,
>>                 <1 IRQ_TYPE_LEVEL_LOW    &i2c3_mux 1 1 
>> IRQ_TYPE_LEVEL_LOW>,
>>                 <1 IRQ_TYPE_EDGE_FALLING &i2c3_mux 1 1 
>> IRQ_TYPE_EDGE_FALLING>;
>>         #gpio-cells = <2>;
>>         gpio-map-mask = <0xf 0x0>;
>>         gpio-map-pass-thru = <0x0 0xf>;
>>         gpio-map = <0 0 &gpio4 1 0>;
>
> This isn't a thing, or do you plan to add nexus nodes / map bindings 
> for all possible
> enumerated items in DT? Not sure this will scale well :/
>
>>         #pwm-cells = <3>;
>>         pwm-map-mask = <0xffffffff 0 0>;
>>         pwm-map-pass-thru = <0 0xffffffff 0xffffffff>;
>>         pwm-map = <0 0 0 &pwm1 0 57000 0>;
>>
>>
>>         devices {
>
> What is this node? I'm assuming this is something the "connector 
> driver" for
> this connector will look for and populate subnodes? What about simple 
> connectors
> where no driver should be needed?

Well, I don't think there are many connectors that do not need a driver. 
Or well, as long as the connector wants to use nexus nodes, it needs a 
driver. At least for GPIOs and PWMs, nexus nodes work pretty well.

The reason nexus nodes cannot be used without driver is well they appear 
as gpio-controller, which means without a driver, any device using them 
enters differed probing.

>
>>             /*
>>              * 'no bus' devices such as fixed-regulators or
>>              * fixed-clocks will be added in this node by the
>>              * overlay.
>>              */
>>             #address-cells = <0>;
>>             #size-cells = <0>;
>>         };
>>
>>         /*
>>          * This is the i2c bus wired at the connector. It is
>>          * handled by the i2c5 adapter available in the SoC.
>>          * The overlay will add devices in this node. Those
>>          * devices are devices available on the addon-board and
>>          * connected to this i2c bus
>>          */
>>         i2c-addon {
>>             i2c-parent = <&i2c5>;
>
> What if this I2C instance is not enabled (maybe not an issue for I2C,
> but some devices should have their status left disabled unless something
> is connected, SPI for instance).
>
> And this (I2C) only works because there is this `i2c-parent` thing, 
> but that
> isn't the case for most (e.g. there is no spi-parent, mdio-parent, etc..)
> My proposal[0] handles that by giving standard names to the provider 
> phandles
> that conforming add-on board overlays can reference directly.
>
>>             #address-cells = <1>;
>>             #size-cells = <0>;
>>         };
>>
>>         export-symbols {
>>             /*
>>              * The 'addon_connector' symbol can be used from the
>>              * overlay to reference this connector
>>              */
>>             addon_connector = <&addon_connector0>;
>>         };
>>     };
>> };
>>
>>
>> Then following overlay is applied at the addon-connector0 node and 
>> described
>
> *How* is this "applied at the addon-connector0 node"?
>
> Again I'm going to guess this is if we are able to modify the 
> `fdtapply` tool
> to accept connection points as a new command line parameter. And then 
> somehow
> do the same for all other projects that apply DT overlays (U-Boot, 
> Zephyr, etc.).

I do have patches that add it to fdtoverlay. But most driver based 
solutions will probably rely on some EEPROM or sysfs entry as well.


>
> And in that case, we would have to pass in the name of the connector 
> anyway,
> so having that name be the only item in `export-symbols` doesn't get 
> us anything
> new, we could have just passed the connector name directly.
>
> BTW, this is solved in my proposal[0] with adapter/shim overlays. 
> Which allow for
> this to work without any modifying the overlay tooling. Maybe there is 
> a way we
> can put this new `export-symbols` node in the adapter overlay to avoid 
> passing
> in the connector name directly to the tooling.. I have to think on this.

The problem with the __symbols__ proposal is the following:

1. Path references are not supported in overlays.

I have tried to add them as well, but full support for path references 
is not possible in overlays, at least right now. The reason for this can 
be found here [0].

There is a possibility of adding a new node: `__symbols_phandle__`, but 
that seems too linux specific.

Note: It is not possible to use aliases due to the reasons discussed 
here [1].


2. Global modification

The __symbols__ based approach directly adds nodes to different parts of 
the devicetree, outside of the connector. That is a security problem. We 
need a way to isolate any devicetree modification to a single node.

I had a discussion here [2] regarding why the sysfs based interface for 
overlays is not merged in mainline, and at least to me, it seems for 
mainline support, the modifications need to be strictly isolated as much 
as possible. But of course, maybe I misunderstood something.


3. Pollutes the global symbols

Export-symbols are local to the connector node, which brings a lot of 
benefits since it is not possible to accidentally refer to the wrong 
phandle. Can be avoided with careful naming.

Additionally, I am not completely sure how connector versioning would be 
handled here. Maybe the symbols should have naming convention that 
accounts for the version, but that seems like it can get difficult to 
scale pretty fast.


4. It requires all symbols to be generated

I don't personally have a problem with this, but it has come up in some 
other discussions.


>
>> the addon board connected to the connector:
>>
>> / {
>>     fragment@0 {
>>         target-path = "";
>>
>>         __overlay__ {
>>             devices {
>>                 reg_addon_3v3: regulator-addon-3v3 {
>>                     compatible = "regulator-fixed";
>
> Is this really a fixed regulator on the add-on board or is this being 
> feed
> from the main board's PMIC but you have no good way to model that 
> connection
> with this scheme? This breaks the regulator/power dependency graph. If a
> device on the add-on board powers down, that information is no longer 
> sent
> back to the parent PMIC and the power rail will be needlessly left 
> enabled.
>
> This is why I was looking for a full complete example, not a 
> simplified one.
> I'm having to make too many assumptions here to give this 
> `export-symbols`
> thing a proper review.


I will try sending patches for PocketBeagle 2 connector since that is 
probably complex enough to catch the corner cases. But well, it will be 
at least a bit simplified (SPI devices will be missing). The reason 
being there are other open items outside of export-symbols:

1. SPI chipselect.

- That is a required property for SPI devices in dt, but there is no way 
(that I know of) to decouple that in a connector addon-board setup


TechLab cape also exposes a MikroBUS connector on it, so I guess I can 
test how board chaining looks like as well.


>
> Andrew
>
> [0] https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/
>
>>                     regulator-name = "3V3_ADDON";
>>                     regulator-min-microvolt = <15000000>;
>>                     regulator-max-microvolt = <15000000>;
>>                     regulator-always-on;
>>                 };
>>
>>                 reg_addon_12v0: regulator-addon-12v0 {
>>                     compatible = "regulator-fixed";
>>                     regulator-name = "12V0_ADDON";
>>                     vin-supply = <&reg_addon_3v3>;
>>                     regulator-min-microvolt = <12000000>;
>>                     regulator-max-microvolt = <12000000>;
>>                     gpios = <&tca6424_addon 12 GPIO_ACTIVE_HIGH>;
>>                     enable-active-high;
>>                 };
>>
>>                 /*
>>                  * This backligh is a PWM driven backlight.
>>                  * It uses the PWM #0 available at the connector
>>                  */
>>                 backlight_addon: backlight-addon {
>>                     compatible = "pwm-backlight";
>>                     power-supply = <&reg_addon_12v0>;
>>                     pwms = <&addon_connector 0 57000 0>;
>>                     brightness-levels = <0 255>;
>>                     num-interpolated-steps = <255>;
>>                     default-brightness-level = <255>;
>>                 };
>>             };
>>
>>             i2c-addon {
>>                 #address-cells = <1>;
>>                 #size-cells = <0>;
>>
>>                 /*
>>                  * This IO expander uses the interrupt #0
>>                  * available at the connector.
>>                  * It is a device connected to the i2c-addon bus
>>                  * available at the connector.
>>                  */
>>                 tca6424_addon: gpio@23 {
>>                     compatible = "ti,tca6424";
>>                     status = "okay";
>>                     reg = <0x23>;
>>                     gpio-controller;
>>                     #gpio-cells = <2>;
>>                     interrupt-parent = <&addon_connector>;
>>                     interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
>>                     interrupt-controller;
>>                     #interrupt-cells = <2>;
>>                     vcc-supply = <&reg_addon_3v3>;
>>                 };
>>             };
>>         };
>>     };
>> };
>>
>>
>> Best regards,
>> Hervé
>>

Best Regards

Ayush Singh


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

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

[2]: 
https://lore.kernel.org/all/9c326bb7-e09a-4c21-944f-006b3fad1870@beagleboard.org/

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

[Herve Codina]

Hi Andrew,

In complement of Ayush comments, here are mine.

On Mon, 14 Apr 2025 22:43:29 +0530
Ayush Singh <ayush@beagleboard.org> wrote:

> On 4/14/25 22:04, Andrew Davis wrote:
> > On 4/14/25 9:46 AM, Herve Codina wrote:  
> >> Hi Ayush, David,
> >>
> >> On Sat, 12 Apr 2025 00:19:16 +0530
> >> Ayush Singh <ayush@beagleboard.org> wrote:
> >>  
> >>> On 4/11/25 23:09, Andrew Davis wrote:
> >>>  
> >>>> On 4/11/25 3:00 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.
> >>>>>
> >>>>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> >>>>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> >>>>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
> >>>>> ---
> >>>>> 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.  
> >>>>
> >>>> I think this is a useful tool in the effort to build a complete
> >>>> addon-board
> >>>> solution. But I'm still missing how it all fits together, do you have
> >>>> a real
> >>>> working overlay making use of this somewhere I could take a look at?
> >>>> Maybe
> >>>> an overlay for one of the addon-boards you list below (one of the
> >>>> BeagleCapes
> >>>> for instance).
> >>>>  
> >>
> >> We (me and Luca) have a working device-tree and overlay.
> >>
> >> Our base device tree is the following (simplified but relevant part for
> >> this topic are available):
> >> / {
> >>     ...
> >>
> >>     addon_connector0: addon-connector0 {
> >>         compatible = "gehc,sunhv1-addon-connector";
> >>
> >>         /*
> >>          * addon-connector node is a nexus node
> >>          *  - 2 interupt lines are wired to the connector
> >>          *  - 1 gpio line is wired to the connector
> >>          *  - 1 PWM is wired to the connector
> >>          */
> >>         #interrupt-cells = <2>;
> >>         #address-cells = <0>;
> >>         interrupt-map = <0 IRQ_TYPE_LEVEL_LOW    &gpio4 1   
> >> IRQ_TYPE_LEVEL_LOW>,  
> >>                 <0 IRQ_TYPE_EDGE_FALLING &gpio4 1   
> >> IRQ_TYPE_EDGE_FALLING>,  
> >>                 <1 IRQ_TYPE_LEVEL_LOW    &i2c3_mux 1 1   
> >> IRQ_TYPE_LEVEL_LOW>,  
> >>                 <1 IRQ_TYPE_EDGE_FALLING &i2c3_mux 1 1   
> >> IRQ_TYPE_EDGE_FALLING>;  
> >>         #gpio-cells = <2>;
> >>         gpio-map-mask = <0xf 0x0>;
> >>         gpio-map-pass-thru = <0x0 0xf>;
> >>         gpio-map = <0 0 &gpio4 1 0>;  
> >
> > This isn't a thing, or do you plan to add nexus nodes / map bindings 
> > for all possible
> > enumerated items in DT? Not sure this will scale well :/

I map using nexus nodes only resources (gpio, pwm, ...) connected to
the connector. What do you mean by all possible enumerated items in DT?

> >  
> >>         #pwm-cells = <3>;
> >>         pwm-map-mask = <0xffffffff 0 0>;
> >>         pwm-map-pass-thru = <0 0xffffffff 0xffffffff>;
> >>         pwm-map = <0 0 0 &pwm1 0 57000 0>;
> >>
> >>
> >>         devices {  
> >
> > What is this node? I'm assuming this is something the "connector 
> > driver" for
> > this connector will look for and populate subnodes? What about simple 

This node ('devices') is here to offer an entry point to fixed-regulators,
fixed-clocks, ... Those device are soldered on the addon board and are not
connected to any busses (i2c, spi, ...). They need to be described and this
node allows to describe them. It was proposed in our connector binding:
   https://lore.kernel.org/lkml/20240813151901.GA953664-robh@kernel.org/

This node indeed, is taken into account by the connector driver with a call
to of_platform_default_populate().

Where do you put your fixed-clock and fixed-regulator soldered on your addon
board in your DT description (overlay) proposal ?


> > connectors
> > where no driver should be needed?  

A connector needs a driver. This point has been confirmed by Rob Herring:
  https://lore.kernel.org/all/CAL_JsqKg0NpDi1Zf1T+f2rYw5UuVfK7+kjWj1_edFWH8EStjXw@mail.gmail.com/

> 
> Well, I don't think there are many connectors that do not need a driver. 
> Or well, as long as the connector wants to use nexus nodes, it needs a 
> driver. At least for GPIOs and PWMs, nexus nodes work pretty well.

Nexus node are not handled by the connector driver.
The related translation is handled by the core OF with
of_parse_phandle_with_args_map():
  https://elixir.bootlin.com/linux/v6.14-rc6/source/drivers/of/base.c#L1441

> 
> The reason nexus nodes cannot be used without driver is well they appear 
> as gpio-controller, which means without a driver, any device using them 
> enters differed probing.

Nexus node can be used without drivers. They are just a translation described
in the DT. The connector driver itself has nothing to do to have nexus node
translation working.

> 
> >  
> >>             /*
> >>              * 'no bus' devices such as fixed-regulators or
> >>              * fixed-clocks will be added in this node by the
> >>              * overlay.
> >>              */
> >>             #address-cells = <0>;
> >>             #size-cells = <0>;
> >>         };
> >>
> >>         /*
> >>          * This is the i2c bus wired at the connector. It is
> >>          * handled by the i2c5 adapter available in the SoC.
> >>          * The overlay will add devices in this node. Those
> >>          * devices are devices available on the addon-board and
> >>          * connected to this i2c bus
> >>          */
> >>         i2c-addon {
> >>             i2c-parent = <&i2c5>;  
> >
> > What if this I2C instance is not enabled (maybe not an issue for I2C,
> > but some devices should have their status left disabled unless something
> > is connected, SPI for instance).

No, why do you need to disable SPI controller if nothing is connected to the
SPI busses. Again this bus is wired to the connector and once an addon board
is connected, a device can be connected to the bus.

For a SPI controller, set in low power (suspend/resume) when nothing is
connected and so the bus is not used, I understand.
Set to 'disabled' status seems to me incorrect.

The meaning of 'disabled' status in my understanding is the device is not used.
As the related bus connected to the connector and available for any addon board,
the device is "used".

Can you clarify this point?

> >
> > And this (I2C) only works because there is this `i2c-parent` thing, 
> > but that
> > isn't the case for most (e.g. there is no spi-parent, mdio-parent, etc..)

Yes and it can be easily extended to SPI and other busses.
I don't see any blocking point with this point.

This 'i2c-parent' handling is part of 'i2c bus extension' series, I sent.
SPI and other can be updated to follow the exact same strategy.
   https://lore.kernel.org/lkml/20250205173918.600037-1-herve.codina@bootlin.com/

> > My proposal[0] handles that by giving standard names to the provider 
> > phandles
> > that conforming add-on board overlays can reference directly.
> >  
> >>             #address-cells = <1>;
> >>             #size-cells = <0>;
> >>         };
> >>
> >>         export-symbols {
> >>             /*
> >>              * The 'addon_connector' symbol can be used from the
> >>              * overlay to reference this connector
> >>              */
> >>             addon_connector = <&addon_connector0>;
> >>         };
> >>     };
> >> };
> >>
> >>
> >> Then following overlay is applied at the addon-connector0 node and 
> >> described  
> >
> > *How* is this "applied at the addon-connector0 node"?

In my use-case, this overlay is applied by the connector driver using
of_overlay_fdt_apply(). The target node (the connector of_node) is passed 
as parameter to the function.
   https://elixir.bootlin.com/linux/v6.14-rc6/source/drivers/of/overlay.c#L981

> >
> > Again I'm going to guess this is if we are able to modify the 
> > `fdtapply` tool
> > to accept connection points as a new command line parameter. And then 
> > somehow
> > do the same for all other projects that apply DT overlays (U-Boot, 
> > Zephyr, etc.).  
> 
> I do have patches that add it to fdtoverlay. But most driver based 
> solutions will probably rely on some EEPROM or sysfs entry as well.

Exactly, in our case, we have an EEPROM soldered on all kind of addon-board
we support for our vendor specific connector.

We load a first overlay describing needed hardware to access this EEPROM.
All supported addon-board used the same EEPROM and need the same hardware
to access it.

Thanks to this EEPROM, we can identify the addon board and so apply a
second overlay to describe the specific hardware available on the addon
board we identified.

> 
> 
> >
> > And in that case, we would have to pass in the name of the connector 
> > anyway,
> > so having that name be the only item in `export-symbols` doesn't get 
> > us anything
> > new, we could have just passed the connector name directly.

See below my example involving power supplies.

> >
> > BTW, this is solved in my proposal[0] with adapter/shim overlays. 
> > Which allow for
> > this to work without any modifying the overlay tooling. Maybe there is 
> > a way we
> > can put this new `export-symbols` node in the adapter overlay to avoid 
> > passing
> > in the connector name directly to the tooling.. I have to think on this.  
> 
> The problem with the __symbols__ proposal is the following:
> 
> 1. Path references are not supported in overlays.
> 
> I have tried to add them as well, but full support for path references 
> is not possible in overlays, at least right now. The reason for this can 
> be found here [0].
> 
> There is a possibility of adding a new node: `__symbols_phandle__`, but 
> that seems too linux specific.
> 
> Note: It is not possible to use aliases due to the reasons discussed 
> here [1].
> 
> 
> 2. Global modification
> 
> The __symbols__ based approach directly adds nodes to different parts of 
> the devicetree, outside of the connector. That is a security problem. We 
> need a way to isolate any devicetree modification to a single node.
> 
> I had a discussion here [2] regarding why the sysfs based interface for 
> overlays is not merged in mainline, and at least to me, it seems for 
> mainline support, the modifications need to be strictly isolated as much 
> as possible. But of course, maybe I misunderstood something.
> 
> 
> 3. Pollutes the global symbols
> 
> Export-symbols are local to the connector node, which brings a lot of 
> benefits since it is not possible to accidentally refer to the wrong 
> phandle. Can be avoided with careful naming.
> 
> Additionally, I am not completely sure how connector versioning would be 
> handled here. Maybe the symbols should have naming convention that 
> accounts for the version, but that seems like it can get difficult to 
> scale pretty fast.
> 
> 
> 4. It requires all symbols to be generated
> 
> I don't personally have a problem with this, but it has come up in some 
> other discussions.
> 
> 
> >  
> >> the addon board connected to the connector:
> >>
> >> / {
> >>     fragment@0 {
> >>         target-path = "";
> >>
> >>         __overlay__ {
> >>             devices {
> >>                 reg_addon_3v3: regulator-addon-3v3 {
> >>                     compatible = "regulator-fixed";  
> >
> > Is this really a fixed regulator on the add-on board or is this being 
> > feed
> > from the main board's PMIC but you have no good way to model that 
> > connection
> > with this scheme? This breaks the regulator/power dependency graph. If a
> > device on the add-on board powers down, that information is no longer 
> > sent
> > back to the parent PMIC and the power rail will be needlessly left 
> > enabled.

A power-supply from the base board is wired to the connector ?
Right:

--- Base DT ---
	/* The regulator used or can also be a child node of the PMIC */
	regulator_wired_to_addon: regulator_3v3 {
		compatible = "xxxx"
		regulator-min-microvolt = <330000>;
		regulator-max-microvolt = <330000>;
        }

        addon_connector0: addon-connector0 {
		...
		export-symbols {
			/*
			 * The 'addon_connector' symbol can be used from the
			 * overlay to reference this connector
			 */
			addon_connector = <&addon_connector0>;
			
			/*
			 * The 3v3 power supply available at the connector */
			 */
			addon_connector_pwr_3v3: <&regulator_wired_to_addon>;

		};


The addon board has a device that use this 3v3 provided at the connector

--- Overlay ---

	fragment@0 {
		target-path = "";

		__overlay__ {
			...
			i2c-addon {
				/*
				 * An I2C device that is powered by the 3v3
				 * available at the connector
				 */
				foo@10 {
					compatible = "bar,foo";
					reg = <0x10>;
					...
					vcc-supply = <&addon_connector_pwr_3v3>;
				};
			};
		};
	};

I don't see anything incorrect or blocking in that description.
involving export-symbols.

> >
> > This is why I was looking for a full complete example, not a 
> > simplified one.
> > I'm having to make too many assumptions here to give this 
> > `export-symbols`
> > thing a proper review.  
> 
> 
> I will try sending patches for PocketBeagle 2 connector since that is 
> probably complex enough to catch the corner cases. But well, it will be 
> at least a bit simplified (SPI devices will be missing). The reason 
> being there are other open items outside of export-symbols:
> 
> 1. SPI chipselect.
> 
> - That is a required property for SPI devices in dt, but there is no way 
> (that I know of) to decouple that in a connector addon-board setup

Chip select are described at SPI controller node -> described in the base dts.

The SPI lines wired to the connector should be described as a "SPI bus
extension". This extension described at SPI controller node similar to
"I2C bus extension".
Note: For I2C bus extension sent upstream, the extension is also described
      at the I2C controller node) see
        https://lore.kernel.org/lkml/20250205173918.600037-1-herve.codina@bootlin.com/

For SPI, a description for translating SPI chip selects from the controller
point of view to the connector can be doable easily.
Something to tell: "The chip-select number 5 of this controller is wired to
the chip-select number 0 defined by the pin 'SPI CS' at the connector"

And then, devices added in the SPI extension at the connector will used this
chip-select.


In other words, something like the following:

--- base board ---
	spi0: spi@1000 {
		comptible = "xxxxx":
		reg = 0x1000;

		spi-bus-extension@0 {
			cs-map = <5 0>	/* For this extension, CS number 5
					 * from the controller point of view
					 * becomes CS number 0 from the addon
					 * board point of view
					 */
          		spi-bus = <&spi_addon>;
		};
	};

	addon_connector0: addon-connector0 {
		...
		/*
		 * This is the SPI bus wired at the connector. It is
		 * handled by the spi@1000 controller available in the SoC.
		 * The overlay will add devices in this node. Those
		 * devices are devices available on the addon-board and
		 * connected to this SPI bus
		 */
		spi-addon {
			spi-parent = <&spi0>;
			#address-cells = <1>;
			#size-cells = <0>;
		};
	};


--- Overlay ---

	fragment@0 {
		target-path = "";

		__overlay__ {
			...
			spi-addon {
				/*
				 * An SPI device in the addon board using
				 * at the CS number 0 of the connector
				 */
				flash@0 {
					compatible = "jedec,spi-nor";
					reg = <0>;
					spi-max-frequency = <40000000>;
				};
			};
		};
	};

Andrew, with your proposal how can you decouple the Chip Select?
I didn't see anything about SPI in your "Add generic Overlay for Grove
Sunlight Sensor" series you pointed out.
Maybe I missed it.

Do you have any other idea to do that?

Best regards,
Hervé

> 
> 
> TechLab cape also exposes a MikroBUS connector on it, so I guess I can 
> test how board chaining looks like as well.
> 
> 
> >
> > Andrew
> >
> > [0] https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/
> >  
> >>                     regulator-name = "3V3_ADDON";
> >>                     regulator-min-microvolt = <15000000>;
> >>                     regulator-max-microvolt = <15000000>;
> >>                     regulator-always-on;
> >>                 };
> >>
> >>                 reg_addon_12v0: regulator-addon-12v0 {
> >>                     compatible = "regulator-fixed";
> >>                     regulator-name = "12V0_ADDON";
> >>                     vin-supply = <&reg_addon_3v3>;
> >>                     regulator-min-microvolt = <12000000>;
> >>                     regulator-max-microvolt = <12000000>;
> >>                     gpios = <&tca6424_addon 12 GPIO_ACTIVE_HIGH>;
> >>                     enable-active-high;
> >>                 };
> >>
> >>                 /*
> >>                  * This backligh is a PWM driven backlight.
> >>                  * It uses the PWM #0 available at the connector
> >>                  */
> >>                 backlight_addon: backlight-addon {
> >>                     compatible = "pwm-backlight";
> >>                     power-supply = <&reg_addon_12v0>;
> >>                     pwms = <&addon_connector 0 57000 0>;
> >>                     brightness-levels = <0 255>;
> >>                     num-interpolated-steps = <255>;
> >>                     default-brightness-level = <255>;
> >>                 };
> >>             };
> >>
> >>             i2c-addon {
> >>                 #address-cells = <1>;
> >>                 #size-cells = <0>;
> >>
> >>                 /*
> >>                  * This IO expander uses the interrupt #0
> >>                  * available at the connector.
> >>                  * It is a device connected to the i2c-addon bus
> >>                  * available at the connector.
> >>                  */
> >>                 tca6424_addon: gpio@23 {
> >>                     compatible = "ti,tca6424";
> >>                     status = "okay";
> >>                     reg = <0x23>;
> >>                     gpio-controller;
> >>                     #gpio-cells = <2>;
> >>                     interrupt-parent = <&addon_connector>;
> >>                     interrupts = <0 IRQ_TYPE_EDGE_FALLING>;
> >>                     interrupt-controller;
> >>                     #interrupt-cells = <2>;
> >>                     vcc-supply = <&reg_addon_3v3>;
> >>                 };
> >>             };
> >>         };
> >>     };
> >> };
> >>
> >>
> >> Best regards,
> >> Hervé
> >>  
> 
> Best Regards
> 
> Ayush Singh
> 
> 
> [0]: 
> https://lore.kernel.org/devicetree-compiler/6b2dba90-3c52-4933-88f3-b47f96dc7710@beagleboard.org/T/#m8259c8754f680b9da7b91f7b7dd89f10da91d8ed
> 
> [1]: 
> https://lore.kernel.org/all/20241110-of-alias-v2-0-16da9844a93e@beagleboard.org/T/#t
> 
> [2]: 
> https://lore.kernel.org/all/9c326bb7-e09a-4c21-944f-006b3fad1870@beagleboard.org/
> 

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

[Ayush Singh]

On 4/11/25 13:30, 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.
>
> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
> ---
> 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.
>
> Linux kernel already provides APIs to apply overlays at specific nodes
> [10], and I have a patch series to have similar functionality in
> fdtoverlay [11]. This is to allow writing overlays for addon-boards,
> that will be expected to be applied to the connector nodes, instead of
> on the global tree.
>
> 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 some resources like GPIO and PWM from the overlay.
> However, that still leaves things like pinmux, i2c adapter, etc.
>
> 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. This allows specifying the
> phandles to i2c adapter, pinmux, etc, per connector. Since the names
> used for these phandles for each connector can be standardized, it would
> allow having the same addon-board overaly work for connectors on
> different boards (or multiple connectors on the same board).
>
> 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 {
> 	    GPIO_CONNECTOR = <&connector1>;
> 	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>          };
>      };
>
> Our overlay can use thi
>
>     leds {
>        pinctrl-names = "default";
>        pinctrl-0 = <&PIN_33_GPIO_PINMUX>;
>
>        led-1 {
>            gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
>        };
>     };
>
> It used the P1_33 pin in the connector it is applied on.
>
> A board with two connectors can be described with:
>
>      connector1: connector1 {
>          ...
>          export-symbols {
> 	    GPIO_CONNECTOR = <&connector1>;
> 	    PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>          };
>      };
>
>      connector2: connector2 {
>          ...
>          export-symbols {
> 	    GPIO_CONNECTOR = <&connector2>;
> 	    PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
>          };
>      };
>
> In that case, the same overlay with unresolved `GPIO_CONNECTOR` and
> `PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the
> correct symbol resolution 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.
>
> [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
> [9]: https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
> [10]: https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
> [11]: https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t
>
> Best Regards,
> Ayush Singh
> ---
> Changes in v3:
> - Add trailer
> - CC linux-devicetree
> - Link to v2: https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org
>
> Changes in v2:
> - Improve examples. More focus on export-symbols and less on nexus nodes
> - Fix typo.
> - Link to v1: https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
> ---
>   source/chapter3-devicenodes.rst | 89 +++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 89 insertions(+)
>
> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
> index 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 100644
> --- a/source/chapter3-devicenodes.rst
> +++ b/source/chapter3-devicenodes.rst
> @@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
>               };
>           };
>       };
> +
> +``*/export-symbols`` node
> +-------------------------
> +A devicetree node may have an export-symbols child node
> +(`*/export-symbols`) that defines one or more export-symbol properties.
> +
> +Each property of the `export-symbols` node defines an alias local to it's
> +parent. The property name specifies the alias name. The property value
> +specifies the phandle to a node in the devicetree. For example, the
> +property ``serial0 = <&main_uart0>`` defines ``serial0`` as the local alias
> +to ``main_uart0``.
> +
> +Alias names shall be lowercase text strings of 1 to 31 characters from the
> +following set of characters.
> +
> +.. tabularcolumns:: | c p{8cm} |
> +.. table:: Valid characters for alias names
> +
> +   ========= ================
> +   Character Description
> +   ========= ================
> +   0-9       digit
> +   a-z       lowercase letter
> +   \-        dash
> +   ========= ================
> +
> +An alias value is a phandle to a node in the devicetree.
> +
> +Resolution of nodes using `export-symbols` follows the following rules
> +depending on the context:
> +
> +No target involved
> +~~~~~~~~~~~~~~~~~~~
> +Properties of parent node use symbols from ``export-symbols``, but none of
> +the subnodes will be able to use them. For example, the following code will
> +resolve properly:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +However, the code below is not valid:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            child {
> +                /* child node cannot access export-symbols */
> +                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +            };
> +
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +Target is used in the base devicetree or overlays
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Any node/subnode property is free to use symbols from ``export-symbols``
> +defined in the parent. To provide a concrete exampe, the following is
> +valid:
> +
> +.. code-block:: dts
> +
> +    / {
> +        parent {
> +            export-symbols {
> +                local_gpio = <&gpio0>;
> +            };
> +        };
> +    }
> +
> +    &parent {
> +        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +
> +        child {
> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
> +        };
> +    };
>
> ---
> base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
> change-id: 20250225-export-symbols-3524f124cd93
>
> Best regards,


I have a very basic pocketbeagle2 connector driver with overlay for 
techlab cape [0]. It only uses export-symbols for pinmuxes for now, but 
might provide an example of use outside of nexus nodes.


[0]: https://github.com/Ayush1325/linux/tree/b4/beagle-cape


Best Regards,

Ayush Singh

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

[Andrew Davis]

On 4/29/25 2:15 PM, Ayush Singh wrote:
> On 4/11/25 13:30, 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.
>>
>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>> ---
>> 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.
>>
>> Linux kernel already provides APIs to apply overlays at specific nodes
>> [10], and I have a patch series to have similar functionality in
>> fdtoverlay [11]. This is to allow writing overlays for addon-boards,
>> that will be expected to be applied to the connector nodes, instead of
>> on the global tree.
>>
>> 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 some resources like GPIO and PWM from the overlay.
>> However, that still leaves things like pinmux, i2c adapter, etc.
>>
>> 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. This allows specifying the
>> phandles to i2c adapter, pinmux, etc, per connector. Since the names
>> used for these phandles for each connector can be standardized, it would
>> allow having the same addon-board overaly work for connectors on
>> different boards (or multiple connectors on the same board).
>>
>> 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 {
>>         GPIO_CONNECTOR = <&connector1>;
>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>          };
>>      };
>>
>> Our overlay can use thi
>>
>>     leds {
>>        pinctrl-names = "default";
>>        pinctrl-0 = <&PIN_33_GPIO_PINMUX>;
>>
>>        led-1 {
>>            gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
>>        };
>>     };
>>
>> It used the P1_33 pin in the connector it is applied on.
>>
>> A board with two connectors can be described with:
>>
>>      connector1: connector1 {
>>          ...
>>          export-symbols {
>>         GPIO_CONNECTOR = <&connector1>;
>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>          };
>>      };
>>
>>      connector2: connector2 {
>>          ...
>>          export-symbols {
>>         GPIO_CONNECTOR = <&connector2>;
>>         PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
>>          };
>>      };
>>
>> In that case, the same overlay with unresolved `GPIO_CONNECTOR` and
>> `PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the
>> correct symbol resolution 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.
>>
>> [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
>> [9]: https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
>> [10]: https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
>> [11]: https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t
>>
>> Best Regards,
>> Ayush Singh
>> ---
>> Changes in v3:
>> - Add trailer
>> - CC linux-devicetree
>> - Link to v2: https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org
>>
>> Changes in v2:
>> - Improve examples. More focus on export-symbols and less on nexus nodes
>> - Fix typo.
>> - Link to v1: https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
>> ---
>>   source/chapter3-devicenodes.rst | 89 +++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 89 insertions(+)
>>
>> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
>> index 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 100644
>> --- a/source/chapter3-devicenodes.rst
>> +++ b/source/chapter3-devicenodes.rst
>> @@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
>>               };
>>           };
>>       };
>> +
>> +``*/export-symbols`` node
>> +-------------------------
>> +A devicetree node may have an export-symbols child node
>> +(`*/export-symbols`) that defines one or more export-symbol properties.
>> +
>> +Each property of the `export-symbols` node defines an alias local to it's
>> +parent. The property name specifies the alias name. The property value
>> +specifies the phandle to a node in the devicetree. For example, the
>> +property ``serial0 = <&main_uart0>`` defines ``serial0`` as the local alias
>> +to ``main_uart0``.
>> +
>> +Alias names shall be lowercase text strings of 1 to 31 characters from the
>> +following set of characters.
>> +
>> +.. tabularcolumns:: | c p{8cm} |
>> +.. table:: Valid characters for alias names
>> +
>> +   ========= ================
>> +   Character Description
>> +   ========= ================
>> +   0-9       digit
>> +   a-z       lowercase letter
>> +   \-        dash
>> +   ========= ================
>> +
>> +An alias value is a phandle to a node in the devicetree.
>> +
>> +Resolution of nodes using `export-symbols` follows the following rules
>> +depending on the context:
>> +
>> +No target involved
>> +~~~~~~~~~~~~~~~~~~~
>> +Properties of parent node use symbols from ``export-symbols``, but none of
>> +the subnodes will be able to use them. For example, the following code will
>> +resolve properly:
>> +
>> +.. code-block:: dts
>> +
>> +    / {
>> +        parent {
>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>> +
>> +            export-symbols {
>> +                local_gpio = <&gpio0>;
>> +            };
>> +        };
>> +    }
>> +
>> +However, the code below is not valid:
>> +
>> +.. code-block:: dts
>> +
>> +    / {
>> +        parent {
>> +            child {
>> +                /* child node cannot access export-symbols */
>> +                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>> +            };
>> +
>> +            export-symbols {
>> +                local_gpio = <&gpio0>;
>> +            };
>> +        };
>> +    }
>> +
>> +Target is used in the base devicetree or overlays
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +Any node/subnode property is free to use symbols from ``export-symbols``
>> +defined in the parent. To provide a concrete exampe, the following is
>> +valid:
>> +
>> +.. code-block:: dts
>> +
>> +    / {
>> +        parent {
>> +            export-symbols {
>> +                local_gpio = <&gpio0>;
>> +            };
>> +        };
>> +    }
>> +
>> +    &parent {
>> +        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>> +
>> +        child {
>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>> +        };
>> +    };
>>
>> ---
>> base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
>> change-id: 20250225-export-symbols-3524f124cd93
>>
>> Best regards,
> 
> 
> I have a very basic pocketbeagle2 connector driver with overlay for techlab cape [0]. It only uses export-symbols for pinmuxes for now, but might provide an example of use outside of nexus nodes.
> 
> 
> [0]: https://github.com/Ayush1325/linux/tree/b4/beagle-cape
> 

You have proven my point here. You were only able to model the GPIO
attached devices: buttons and LEDs. Nothing else of this cape was
modeled, nor could it be modeled with this solution.

Your example fails to do even the most fundamental task: the overlay
is still specific to just one host board. Go connect this cape to
an original PocketBeagle and try to apply the overlay to its DTS..

What you did with "export-symbols" in this example could have been
done exactly the same with normal overlays. These "examples" keep
showing "what" the "export-symbols" node does, not "why" it is
needed or better than just normal __symbols__.

Andrew

> 
> Best Regards,
> 
> Ayush Singh
> 

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

[Ayush Singh]

On 4/30/25 01:21, Andrew Davis wrote:

> On 4/29/25 2:15 PM, Ayush Singh wrote:
>> On 4/11/25 13:30, 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.
>>>
>>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>>> ---
>>> 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.
>>>
>>> Linux kernel already provides APIs to apply overlays at specific nodes
>>> [10], and I have a patch series to have similar functionality in
>>> fdtoverlay [11]. This is to allow writing overlays for addon-boards,
>>> that will be expected to be applied to the connector nodes, instead of
>>> on the global tree.
>>>
>>> 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 some resources like GPIO and PWM from the overlay.
>>> However, that still leaves things like pinmux, i2c adapter, etc.
>>>
>>> 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. This allows specifying the
>>> phandles to i2c adapter, pinmux, etc, per connector. Since the names
>>> used for these phandles for each connector can be standardized, it 
>>> would
>>> allow having the same addon-board overaly work for connectors on
>>> different boards (or multiple connectors on the same board).
>>>
>>> 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 {
>>>         GPIO_CONNECTOR = <&connector1>;
>>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>>          };
>>>      };
>>>
>>> Our overlay can use thi
>>>
>>>     leds {
>>>        pinctrl-names = "default";
>>>        pinctrl-0 = <&PIN_33_GPIO_PINMUX>;
>>>
>>>        led-1 {
>>>            gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
>>>        };
>>>     };
>>>
>>> It used the P1_33 pin in the connector it is applied on.
>>>
>>> A board with two connectors can be described with:
>>>
>>>      connector1: connector1 {
>>>          ...
>>>          export-symbols {
>>>         GPIO_CONNECTOR = <&connector1>;
>>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>>          };
>>>      };
>>>
>>>      connector2: connector2 {
>>>          ...
>>>          export-symbols {
>>>         GPIO_CONNECTOR = <&connector2>;
>>>         PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
>>>          };
>>>      };
>>>
>>> In that case, the same overlay with unresolved `GPIO_CONNECTOR` and
>>> `PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the
>>> correct symbol resolution 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.
>>>
>>> [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
>>> [9]: 
>>> https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
>>> [10]: 
>>> https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
>>> [11]: 
>>> https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t
>>>
>>> Best Regards,
>>> Ayush Singh
>>> ---
>>> Changes in v3:
>>> - Add trailer
>>> - CC linux-devicetree
>>> - Link to v2: 
>>> https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org
>>>
>>> Changes in v2:
>>> - Improve examples. More focus on export-symbols and less on nexus 
>>> nodes
>>> - Fix typo.
>>> - Link to v1: 
>>> https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
>>> ---
>>>   source/chapter3-devicenodes.rst | 89 
>>> +++++++++++++++++++++++++++++++++++++++++
>>>   1 file changed, 89 insertions(+)
>>>
>>> diff --git a/source/chapter3-devicenodes.rst 
>>> b/source/chapter3-devicenodes.rst
>>> index 
>>> 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 
>>> 100644
>>> --- a/source/chapter3-devicenodes.rst
>>> +++ b/source/chapter3-devicenodes.rst
>>> @@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
>>>               };
>>>           };
>>>       };
>>> +
>>> +``*/export-symbols`` node
>>> +-------------------------
>>> +A devicetree node may have an export-symbols child node
>>> +(`*/export-symbols`) that defines one or more export-symbol 
>>> properties.
>>> +
>>> +Each property of the `export-symbols` node defines an alias local 
>>> to it's
>>> +parent. The property name specifies the alias name. The property value
>>> +specifies the phandle to a node in the devicetree. For example, the
>>> +property ``serial0 = <&main_uart0>`` defines ``serial0`` as the 
>>> local alias
>>> +to ``main_uart0``.
>>> +
>>> +Alias names shall be lowercase text strings of 1 to 31 characters 
>>> from the
>>> +following set of characters.
>>> +
>>> +.. tabularcolumns:: | c p{8cm} |
>>> +.. table:: Valid characters for alias names
>>> +
>>> +   ========= ================
>>> +   Character Description
>>> +   ========= ================
>>> +   0-9       digit
>>> +   a-z       lowercase letter
>>> +   \-        dash
>>> +   ========= ================
>>> +
>>> +An alias value is a phandle to a node in the devicetree.
>>> +
>>> +Resolution of nodes using `export-symbols` follows the following rules
>>> +depending on the context:
>>> +
>>> +No target involved
>>> +~~~~~~~~~~~~~~~~~~~
>>> +Properties of parent node use symbols from ``export-symbols``, but 
>>> none of
>>> +the subnodes will be able to use them. For example, the following 
>>> code will
>>> +resolve properly:
>>> +
>>> +.. code-block:: dts
>>> +
>>> +    / {
>>> +        parent {
>>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>> +
>>> +            export-symbols {
>>> +                local_gpio = <&gpio0>;
>>> +            };
>>> +        };
>>> +    }
>>> +
>>> +However, the code below is not valid:
>>> +
>>> +.. code-block:: dts
>>> +
>>> +    / {
>>> +        parent {
>>> +            child {
>>> +                /* child node cannot access export-symbols */
>>> +                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>> +            };
>>> +
>>> +            export-symbols {
>>> +                local_gpio = <&gpio0>;
>>> +            };
>>> +        };
>>> +    }
>>> +
>>> +Target is used in the base devicetree or overlays
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +Any node/subnode property is free to use symbols from 
>>> ``export-symbols``
>>> +defined in the parent. To provide a concrete exampe, the following is
>>> +valid:
>>> +
>>> +.. code-block:: dts
>>> +
>>> +    / {
>>> +        parent {
>>> +            export-symbols {
>>> +                local_gpio = <&gpio0>;
>>> +            };
>>> +        };
>>> +    }
>>> +
>>> +    &parent {
>>> +        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>> +
>>> +        child {
>>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>> +        };
>>> +    };
>>>
>>> ---
>>> base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
>>> change-id: 20250225-export-symbols-3524f124cd93
>>>
>>> Best regards,
>>
>>
>> I have a very basic pocketbeagle2 connector driver with overlay for 
>> techlab cape [0]. It only uses export-symbols for pinmuxes for now, 
>> but might provide an example of use outside of nexus nodes.
>>
>>
>> [0]: https://github.com/Ayush1325/linux/tree/b4/beagle-cape
>>
>
> You have proven my point here. You were only able to model the GPIO
> attached devices: buttons and LEDs. Nothing else of this cape was
> modeled, nor could it be modeled with this solution.


For i2c, I first need to implement the i2c bus extensions [0]. Something 
similar for SPI, UART, etc. Somewhat long list of things.


>
> Your example fails to do even the most fundamental task: the overlay
> is still specific to just one host board. Go connect this cape to
> an original PocketBeagle and try to apply the overlay to its DTS..


Once I make the connector node a gpio and pwm nexus node, it will not be 
specific to just one host board. But yes, the current one is like that.


>
> What you did with "export-symbols" in this example could have been
> done exactly the same with normal overlays. These "examples" keep
> showing "what" the "export-symbols" node does, not "why" it is
> needed or better than just normal __symbols__.
>
> Andrew


No, it cannot be. When using `__symbols__`, the changes are not 
contained to a single devicetree nodes. As you can see even in the 
current form of the overlay, any modifications happen inside the 
connector node. Nothing outside of the connector node is modified at 
runtime.

I am not here to argue whether runtime global devicetree manipulation is 
an okay thing to do. I would be fine with it if upstream is okay with 
it. But neither sysfs based, nor configfs based patches for dynamic 
devicetree are being considered for that exact reason.

I am working from the assumption that upstream will not accept a global 
devicetree manipulation solution. So for local node based solution, 
export-symbols are essential. If I misunderstood something in this very 
basic assumption, then feel free to correct me.

Do note, that any solution cannot just stay as a static, apply using 
fdtoverlay kind of thing. It needs to allow for dynamic discovery using 
both EEPROM or something similar, and a fallback using sysfs or configfs.


Best Regards,

Ayush Singh


[0]: 
https://lore.kernel.org/devicetree-spec/20250401081041.114333-1-herve.codina@bootlin.com/T/#m5ae5b64b0e7fcae709127b99c8aa10fc28fb1ea8

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

[Andrew Davis]

On 4/30/25 2:32 AM, Ayush Singh wrote:
> On 4/30/25 01:21, Andrew Davis wrote:
> 
>> On 4/29/25 2:15 PM, Ayush Singh wrote:
>>> On 4/11/25 13:30, 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.
>>>>
>>>> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
>>>> Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
>>>> Signed-off-by: Ayush Singh <ayush@beagleboard.org>
>>>> ---
>>>> 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.
>>>>
>>>> Linux kernel already provides APIs to apply overlays at specific nodes
>>>> [10], and I have a patch series to have similar functionality in
>>>> fdtoverlay [11]. This is to allow writing overlays for addon-boards,
>>>> that will be expected to be applied to the connector nodes, instead of
>>>> on the global tree.
>>>>
>>>> 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 some resources like GPIO and PWM from the overlay.
>>>> However, that still leaves things like pinmux, i2c adapter, etc.
>>>>
>>>> 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. This allows specifying the
>>>> phandles to i2c adapter, pinmux, etc, per connector. Since the names
>>>> used for these phandles for each connector can be standardized, it would
>>>> allow having the same addon-board overaly work for connectors on
>>>> different boards (or multiple connectors on the same board).
>>>>
>>>> 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 {
>>>>         GPIO_CONNECTOR = <&connector1>;
>>>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>>>          };
>>>>      };
>>>>
>>>> Our overlay can use thi
>>>>
>>>>     leds {
>>>>        pinctrl-names = "default";
>>>>        pinctrl-0 = <&PIN_33_GPIO_PINMUX>;
>>>>
>>>>        led-1 {
>>>>            gpios = <&GPIO_CONNECTOR 33 GPIO_ACTIVE_HIGH>;
>>>>        };
>>>>     };
>>>>
>>>> It used the P1_33 pin in the connector it is applied on.
>>>>
>>>> A board with two connectors can be described with:
>>>>
>>>>      connector1: connector1 {
>>>>          ...
>>>>          export-symbols {
>>>>         GPIO_CONNECTOR = <&connector1>;
>>>>         PIN_33_GPIO_PINMUX = <&p1_33_gpio>;
>>>>          };
>>>>      };
>>>>
>>>>      connector2: connector2 {
>>>>          ...
>>>>          export-symbols {
>>>>         GPIO_CONNECTOR = <&connector2>;
>>>>         PIN_33_GPIO_PINMUX = <&p3_33_gpio>;
>>>>          };
>>>>      };
>>>>
>>>> In that case, the same overlay with unresolved `GPIO_CONNECTOR` and
>>>> `PIN_33_GPIO_PINMUX` symbol can be applied on both connectors and the
>>>> correct symbol resolution 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.
>>>>
>>>> [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
>>>> [9]: https://lore.kernel.org/devicetree-spec/edaa1378-c871-4c55-ab99-21ef6656f35a@beagleboard.org/T/#mc339a0ae0c886ca46da0f7bb679518fa8b0b3007
>>>> [10]: https://docs.kernel.org/devicetree/kernel-api.html#c.of_overlay_fdt_apply
>>>> [11]: https://lore.kernel.org/devicetree-compiler/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/T/#t
>>>>
>>>> Best Regards,
>>>> Ayush Singh
>>>> ---
>>>> Changes in v3:
>>>> - Add trailer
>>>> - CC linux-devicetree
>>>> - Link to v2: https://lore.kernel.org/r/20250323-export-symbols-v2-1-f0ae1748b244@beagleboard.org
>>>>
>>>> Changes in v2:
>>>> - Improve examples. More focus on export-symbols and less on nexus nodes
>>>> - Fix typo.
>>>> - Link to v1: https://lore.kernel.org/r/20250225-export-symbols-v1-1-693049e3e187@beagleboard.org
>>>> ---
>>>>   source/chapter3-devicenodes.rst | 89 +++++++++++++++++++++++++++++++++++++++++
>>>>   1 file changed, 89 insertions(+)
>>>>
>>>> diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst
>>>> index 8080321d6e60d6b1e86c81af86c6850246a0223b..2c3bbc2c81bacd71fcf3b389a31237344f995ba7 100644
>>>> --- a/source/chapter3-devicenodes.rst
>>>> +++ b/source/chapter3-devicenodes.rst
>>>> @@ -988,3 +988,92 @@ each with their own on-chip L2 and a shared L3.
>>>>               };
>>>>           };
>>>>       };
>>>> +
>>>> +``*/export-symbols`` node
>>>> +-------------------------
>>>> +A devicetree node may have an export-symbols child node
>>>> +(`*/export-symbols`) that defines one or more export-symbol properties.
>>>> +
>>>> +Each property of the `export-symbols` node defines an alias local to it's
>>>> +parent. The property name specifies the alias name. The property value
>>>> +specifies the phandle to a node in the devicetree. For example, the
>>>> +property ``serial0 = <&main_uart0>`` defines ``serial0`` as the local alias
>>>> +to ``main_uart0``.
>>>> +
>>>> +Alias names shall be lowercase text strings of 1 to 31 characters from the
>>>> +following set of characters.
>>>> +
>>>> +.. tabularcolumns:: | c p{8cm} |
>>>> +.. table:: Valid characters for alias names
>>>> +
>>>> +   ========= ================
>>>> +   Character Description
>>>> +   ========= ================
>>>> +   0-9       digit
>>>> +   a-z       lowercase letter
>>>> +   \-        dash
>>>> +   ========= ================
>>>> +
>>>> +An alias value is a phandle to a node in the devicetree.
>>>> +
>>>> +Resolution of nodes using `export-symbols` follows the following rules
>>>> +depending on the context:
>>>> +
>>>> +No target involved
>>>> +~~~~~~~~~~~~~~~~~~~
>>>> +Properties of parent node use symbols from ``export-symbols``, but none of
>>>> +the subnodes will be able to use them. For example, the following code will
>>>> +resolve properly:
>>>> +
>>>> +.. code-block:: dts
>>>> +
>>>> +    / {
>>>> +        parent {
>>>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>>> +
>>>> +            export-symbols {
>>>> +                local_gpio = <&gpio0>;
>>>> +            };
>>>> +        };
>>>> +    }
>>>> +
>>>> +However, the code below is not valid:
>>>> +
>>>> +.. code-block:: dts
>>>> +
>>>> +    / {
>>>> +        parent {
>>>> +            child {
>>>> +                /* child node cannot access export-symbols */
>>>> +                led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>>> +            };
>>>> +
>>>> +            export-symbols {
>>>> +                local_gpio = <&gpio0>;
>>>> +            };
>>>> +        };
>>>> +    }
>>>> +
>>>> +Target is used in the base devicetree or overlays
>>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>> +Any node/subnode property is free to use symbols from ``export-symbols``
>>>> +defined in the parent. To provide a concrete exampe, the following is
>>>> +valid:
>>>> +
>>>> +.. code-block:: dts
>>>> +
>>>> +    / {
>>>> +        parent {
>>>> +            export-symbols {
>>>> +                local_gpio = <&gpio0>;
>>>> +            };
>>>> +        };
>>>> +    }
>>>> +
>>>> +    &parent {
>>>> +        led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>>> +
>>>> +        child {
>>>> +            led = <&local_gpio 0 GPIO_ACTIVE_HIGH>;
>>>> +        };
>>>> +    };
>>>>
>>>> ---
>>>> base-commit: 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f
>>>> change-id: 20250225-export-symbols-3524f124cd93
>>>>
>>>> Best regards,
>>>
>>>
>>> I have a very basic pocketbeagle2 connector driver with overlay for techlab cape [0]. It only uses export-symbols for pinmuxes for now, but might provide an example of use outside of nexus nodes.
>>>
>>>
>>> [0]: https://github.com/Ayush1325/linux/tree/b4/beagle-cape
>>>
>>
>> You have proven my point here. You were only able to model the GPIO
>> attached devices: buttons and LEDs. Nothing else of this cape was
>> modeled, nor could it be modeled with this solution.
> 
> 
> For i2c, I first need to implement the i2c bus extensions [0]. Something similar for SPI, UART, etc. Somewhat long list of things.
> 

That is exactly the issue, I'd think I2C extensions would be the trivial case but
even it is getting some (valid) push back, how do you intend to do the same
for SPI, UART, etc.. Would take years even at the best rate. Any solution that
requires modifying the schema for every type of peripheral node is a non-starter.

> 
>>
>> Your example fails to do even the most fundamental task: the overlay
>> is still specific to just one host board. Go connect this cape to
>> an original PocketBeagle and try to apply the overlay to its DTS..
> 
> 
> Once I make the connector node a gpio and pwm nexus node, it will not be specific to just one host board. But yes, the current one is like that.
> 
> 
>>
>> What you did with "export-symbols" in this example could have been
>> done exactly the same with normal overlays. These "examples" keep
>> showing "what" the "export-symbols" node does, not "why" it is
>> needed or better than just normal __symbols__.
>>
>> Andrew
> 
> 
> No, it cannot be. When using `__symbols__`, the changes are not contained to a single devicetree nodes. As you can see even in the current form of the overlay, any modifications happen inside the connector node. Nothing outside of the connector node is modified at runtime.
> 
> I am not here to argue whether runtime global devicetree manipulation is an okay thing to do. I would be fine with it if upstream is okay with it. But neither sysfs based, nor configfs based patches for dynamic devicetree are being considered for that exact reason.
> 
> I am working from the assumption that upstream will not accept a global devicetree manipulation solution. So for local node based solution, export-symbols are essential. If I misunderstood something in this very basic assumption, then feel free to correct me.
> 
> Do note, that any solution cannot just stay as a static, apply using fdtoverlay kind of thing. It needs to allow for dynamic discovery using both EEPROM or something similar, and a fallback using sysfs or configfs.
> 

Any static solution (works with just fdtoverlay) can be extended to the dynamic discovery
case by simply doing the application of the overlay exactly the same way, but at runtime.
The issue "global devicetree manipulation" seems to be around how unloading of the overlay
would work, which is an unsolved problem for a lot of other reasons.

Just to note here, I have no issue with export-symbols, I think it is a useful addition
to the DT toolbox. All I'm trying to do here is understand what you plan to do with this
new tool. Hence asking for a *complete* and *functional* example with a real add-on
board, so I can see how many more tools will be needed after this one.

Anyway seems like you are trying to consolidate the all the current discussions on this
to one thread[0], so we can continue this over there.

Thanks,
Andrew

[0] https://www.spinics.net/lists/kernel/msg5663574.html

> 
> Best Regards,
> 
> Ayush Singh
> 
> 
> [0]: https://lore.kernel.org/devicetree-spec/20250401081041.114333-1-herve.codina@bootlin.com/T/#m5ae5b64b0e7fcae709127b99c8aa10fc28fb1ea8
>