of: overlay: Add support for export-symbols node feature
Herve Codina
maintainerv2 cover of: overlay: Add support for export-symbols node feature
Hi,
At Linux Plumbers Conference 2024, we (me and Luca Ceresolli) talked about issues we have with runtime hotplug on non-discoverable busses with device tree overlays [1].
On our system, a base board has a connector and addon boards can be connected to this connector. Both boards are described using device tree. The base board is described by a base device tree and addon boards are describe by overlays device tree. More details can be found at [2].
This kind of use case can be found also on:
- Grove Sunlight Sensor [3]
- mikroBUS [4]
One of the issue we were facing on was referencing resources available on the base board device tree from the addon overlay device tree.
Using a nexus node [5] helps decoupling resources and avoid the knowledge of the full base board from the overlay. Indeed, with nexus node, the overlay need to know only about the nexus node itself.
For instance, suppose a connector where a GPIO is connected at PinA. On the base board this GPIO is connected to the GPIO 12 of the SoC GPIO controller.
The base board can describe this GPIO using a nexus node:
soc_gpio: gpio-controller {
#gpio-cells = <2>;
};
connector1: connector1 {
/*
* Nexus node for the GPIO available on the connector.
* GPIO 0 (Pin A GPIO) is connected to GPIO 12 of the SoC gpio
* controller
*/
#gpio-cells = <2>;
gpio-map = <0 0 &soc_gpio 12 0>;
gpio-map-mask = <0xf 0x0>;
gpio-map-pass-thru = <0x0 0xf>;
};The connector pin A GPIO can be referenced using:
<&connector1 0 GPIO_ACTIVE_HIGH>
This implies that the overlay needs to know about exact label that references the connector. This label can be different on a different board and so applying the overlay could failed even if it is used to describe the exact same addon board. Further more, a given base board can have several connectors where the exact same addon board can be connected. In that case, the same overlay cannot be used on both connector. Indeed, the connector labels have to be different.
The export-symbols node introduced by this current series solves this issue.
The idea of export-symbols is to have something similar to the global __symbols__ node but local to a specific node. Symbols listed in this export-symbols are local and visible only when an overlay is applied on a node having an export-symbols subnode.
Using export-symbols, our example becomes:
soc_gpio: gpio-controller {
#gpio-cells = <2>;
};
connector1: connector1 {
/*
* Nexus node for the GPIO available on the connector.
* GPIO 0 (Pin A GPIO) is connected to GPIO 12 of the SoC gpio
* controller
*/
#gpio-cells = <2>;
gpio-map = <0 0 &soc_gpio 12 0>;
gpio-map-mask = <0xf 0x0>;
gpio-map-pass-thru = <0x0 0xf>;
export-symbols {
connector = <&connector1>;
};
};With that export-symbols node, an overlay applied on connector1 node can have the symbol named 'connector' resolved to connector1. Indeed, the export-symbols node available at connector1 node is used when the overlay is applied. If the overlay has an unresolved 'connector' symbol, it will be resolved to connector1 thanks to export-symbols.
Our overlay using the nexus node can contains:
node {
foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>; };
It used the GPIO 0 from the connector it is applied on.
A board with two connectors can be described with:
connector1: connector1 {
...
export-symbols {
connector = <&connector1>;
};
};
connector2: connector2 {
...
export-symbols {
connector = <&connector2>;
};
};In that case, the same overlay with unresolved 'connector' symbol can be applied on both connectors and the correct symbol resolution (connector1 or connector2) will be done.
This current series add support for the export-symbols node feature:
- Patch 1 describes the export-symbols binding
- Patches 2 to 6 prepare and add the support for the export-symbols feature
- Patch 7 adds an unittest for the export-symbols feature
Compare to the previous iteration, the series has been rebased on top of v6.15-rc1 and an compilation issue in unittest has been fixed.
Also it is worth noting the work already done by Ayush Singh related to this topic on other repositories:
- Add export-symbols in device-tree specification
[PATCH v3] Add new export-symbols node [6]
- Support for export-symbols in the device tree compiler [PATCH 0/3] Allow specifying target node in fdtoverlay [7] [PATCH] checks: Add support for export-symbols [8]
Best regards,
Hervé
[1] https://lpc.events/event/18/contributions/1696/
[2] https://lore.kernel.org/lkml/[email protected]/
[3] https://lore.kernel.org/lkml/[email protected]/
[4] https://lore.kernel.org/lkml/[email protected]/
[5] https://github.com/devicetree-org/devicetree-specification/blob/v0.4/source/chapter2-devicetree-basics.rst#nexus-nodes-and-specifier-mapping
[6] https://lore.kernel.org/all/[email protected]/
[7] https://lore.kernel.org/all/[email protected]/
[8] https://lore.kernel.org/all/[email protected]/
Changes v1 -> v2
v1: https://lore.kernel.org/all/[email protected]/
- All patches
Add 'Tested-by: Ayush Singh <[email protected]>'
- Patch 1
Update the 'patternProperties' regexp
- Patch 2 and 4
Fix conflicts due to the rebase on top of v6.15-rc1
- Patch 5
Fix a typo in commit log
- Patch 7
Fix a compilation issue detected by a kernel test robot
Herve Codina (7):
dt-bindings: Add support for export-symbols node
of: resolver: Introduce get_phandle_from_symbols_node()
of: resolver: Add export_symbols in of_resolve_phandles() parameters
of: resolver: Add support for the export symbols node
of: overlay: Add export_symbols_name in of_overlay_fdt_apply()
parameters
of: overlay: Add support for the export symbols node
of: unittest: Add tests for export symbols
.../devicetree/bindings/export-symbols.yaml | 43 +++++++++++ drivers/misc/lan966x_pci.c | 3 +- drivers/of/of_kunit_helpers.c | 2 +- drivers/of/of_private.h | 2 +- drivers/of/overlay.c | 30 +++++++- drivers/of/resolver.c | 75 ++++++++++++++---- drivers/of/unittest-data/Makefile | 5 ++ .../unittest-data/overlay_export_symbols.dtso | 15 ++++ .../of/unittest-data/testcases_common.dtsi | 1 + .../unittest-data/tests-export-symbols.dtsi | 30 ++++++++ drivers/of/unittest.c | 77 +++++++++++++++++-- include/linux/of.h | 6 +- 12 files changed, 258 insertions(+), 31 deletions(-) create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml create mode 100644 drivers/of/unittest-data/overlay_export_symbols.dtso create mode 100644 drivers/of/unittest-data/tests-export-symbols.dtsi
Signature · 1 line
2.49.0
Herve Codina
maintainerPATCH v2 1/7 dt-bindings: Add support for export-symbols node
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.
- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:
...
foo_connector: connector1 {
export-symbols {
connector = <&foo_connector>;
};
};
bar_connector: connector2 {
export-symbols {
connector = <&bar_connector>;
};
};
...- Base device tree board B:
...
front_connector: addon-connector {
export-symbols {
connector = <&front_connector>;
};
};
...- Overlay describing an addon board the can be connected on connectors:
...
node {
...
connector = <&connector>;
...
};
...Thanks to the export-symbols node, the overlay can be applied on connector1 or connector2 available on board A but also on addon-connector available on board B.
--- .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
Documentation/devicetree/bindings/export-symbols.yaml new file +43 -0
@@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/export-symbols.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Export symbols + +maintainers: + - Herve Codina <[email protected]> + +description: | + An export-symbols node allows to export symbols for symbols resolution + performed when applying a device tree overlay. + + When a device tree overlay is applied on a node having an export-symbols + node, symbols listed in the export-symbols node are used to resolve undefined + symbols referenced from the overlay. + +properties: + $nodename: + const: export-symbols + +patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$": + $ref: /schemas/types.yaml#/definitions/phandle + description: + A symbol exported in the form <symbol_name>=<phandle>. + +additionalProperties: false + +examples: + - | + /* + * Allows 'connector' symbol used in a device-tree overlay to be resolved to + * connector0 when the device-tree overlay is applied on connector0 node. + */ + connector0: connector0 { + export-symbols { + connector = <&connector0>; + }; + }; +...
Signature · 1 line
2.49.0
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 49 lines · On Wed, 30 Apr 2025 14:51:45 +0200 Herve Codina <[email protected]>…
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:... foo_connector: connector1 { export-symbols { connector = <&foo_connector>; }; }; bar_connector: connector2 { export-symbols { connector = <&bar_connector>; }; }; ...- Base device tree board B:
... front_connector: addon-connector { export-symbols { connector = <&front_connector>; }; }; ...- Overlay describing an addon board the can be connected on connectors:
... node { ... connector = <&connector>; ... }; ...
Quoted 6 lines
Thanks to the export-symbols node, the overlay can be applied on connector1 or connector2 available on board A but also on addon-connector available on board B.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>
Signature · 3 lines
Luca Ceresoli, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Herve CodinaQuoted 6 lines · Herve Codina
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
I have impression that this is being discussed in three places simultaneously - here, DT spec and DT schema. I don't know how to solve the multiplication, but I will keep answering here, because that's my part.
Quoted 11 lines
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:
Quoted 13 lines
...
foo_connector: connector1 {
export-symbols {
connector = <&foo_connector>;
};
};
bar_connector: connector2 {
export-symbols {
connector = <&bar_connector>;
};
};
...And what would this mean? Which symbol is exported - foo or bar?
Quoted 8 lines
- Base device tree board B:
... front_connector: addon-connector { export-symbols { connector = <&front_connector>; }; };
<from my other reply in private>
Another problem is that the board DTS should not care about overlays. It feels like breaking encapsulation and I cannot imagine now adding 1000 export-symbols, because every i2c, spi, mikrobus or PCI slot could have an overlay applied.
You could argue that only few nodes will be exported like this, so only real mikrobus connectors. Then I will argue: look at aliases. People alias everything everywhere, not following the guidelines.
If we assume that such overlays are designed for specific boards, thus there will be only one or two exported symbols not 1000, then what is the benefit of export symbols comparing to referencing by full path? </end from my other reply>
And with above assumption - such overlays designed per board - plus my first point about duplicated exports:
connector = <&foo_connector>;
connector = <&bar_connector>;
why not exporting the symbol with the same name? E.g.:
foo_connector: connector1 {
export-symbols {
whatever-property-style = <&foo_connector>;
};
};and overlay:
node {
...
connector = <&foo_connector>;
...
};Or even annotation?
foo_connector: connector1 __exported_symbol__ {
....
};
node {
...
connector = <&foo_connector>;
...
};? This also answers my further question about DTS style (see at the bottom)
Quoted 11 lines
...- Overlay describing an addon board the can be connected on connectors:
... node { ... connector = <&connector>; ... }; ...
Quoted 6 lines
Thanks to the export-symbols node, the overlay can be applied on connector1 or connector2 available on board A but also on addon-connector available on board B.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>
I would argue you cannot test a binding, because testing here is part of a process, but what do I know...
Quoted 26 lines
--- .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 Documentation/devicetree/bindings/export-symbols.yamlDocumentation/devicetree/bindings/export-symbols.yaml new file +15
-0@@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/export-symbols.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Export symbols + +maintainers: + - Herve Codina <[email protected]> + +description: | + An export-symbols node allows to export symbols for symbols resolution + performed when applying a device tree overlay. +
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 10 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +10
-0+ When a device tree overlay is applied on a node having an export-symbols + node, symbols listed in the export-symbols node are used to resolve undefined + symbols referenced from the overlay. + +properties: + $nodename: + const: export-symbols + +patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":
This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Documentation/devicetree/bindings/export-symbols.yaml line 31
Quoted 6 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +6
-0+ $ref: /schemas/types.yaml#/definitions/phandle + description: + A symbol exported in the form <symbol_name>=<phandle>. + +additionalProperties: false +
Best regards,
Krzysztof
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 50 lines · Krzysztof Kozlowski
Quoted 6 lines · Herve Codina
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
I have impression that this is being discussed in three places simultaneously - here, DT spec and DT schema. I don't know how to solve the multiplication, but I will keep answering here, because that's my part.
Quoted 10 lines
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:Quoted 13 lines
... foo_connector: connector1 { export-symbols { connector = <&foo_connector>; }; }; bar_connector: connector2 { export-symbols { connector = <&bar_connector>; }; }; ...And what would this mean? Which symbol is exported - foo or bar?
Quoted 7 lines
- Base device tree board B: ... front_connector: addon-connector { export-symbols { connector = <&front_connector>; }; };<from my other reply in private>
Another problem is that the board DTS should not care about overlays. It feels like breaking encapsulation and I cannot imagine now adding 1000 export-symbols, because every i2c, spi, mikrobus or PCI slot could have an overlay applied.
Quoted 8 lines
You could argue that only few nodes will be exported like this, so only real mikrobus connectors. Then I will argue: look at aliases. People alias everything everywhere, not following the guidelines.
If we assume that such overlays are designed for specific boards, thus there will be only one or two exported symbols not 1000, then what is the benefit of export symbols comparing to referencing by full path? </end from my other reply>
Can you explain how referencing by full path will work in connector + addon board setups?
The full path will be dependent on the connector, which means the same addon board overlay cannot work for different connectors.
Quoted 14 lines
And with above assumption - such overlays designed per board - plus my first point about duplicated exports:
connector = <&foo_connector>;
connector = <&bar_connector>;why not exporting the symbol with the same name? E.g.:
foo_connector: connector1 { export-symbols { whatever-property-style = <&foo_connector>; }; };
Quoted 7 lines
and overlay:
node { ... connector = <&foo_connector>; ... };
Isn't this overlay tied to foo_connector, i.e. it cannot be used with bar_connector?
Quoted 27 lines
Or even annotation?
foo_connector: connector1 __exported_symbol__ { .... }; node { ... connector = <&foo_connector>; ... };? This also answers my further question about DTS style (see at the bottom)
Quoted 11 lines
...- Overlay describing an addon board the can be connected on connectors: ... node { ... connector = <&connector>; ... }; ...
Quoted 8 lines
Quoted 6 lines
Thanks to the export-symbols node, the overlay can be applied on connector1 or connector2 available on board A but also on addon-connector available on board B.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>I would argue you cannot test a binding, because testing here is part of a process, but what do I know...
Ahh, I added tested by for the whole patch series to check that the phandle resolution is working. But yes, I have not tested the bindings.
Quoted 41 lines
Quoted 28 lines
--- .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+)create mode 100644
Documentation/devicetree/bindings/export-symbols.yamlDocumentation/devicetree/bindings/export-symbols.yaml new file +15
-0@@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/export-symbols.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Export symbols + +maintainers: + - Herve Codina <[email protected]> + +description: | + An export-symbols node allows to export symbols for symbols resolution + performed when applying a device tree overlay. +Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 10 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +10
-0+ When a device tree overlay is applied on a node having an export-symbols + node, symbols listed in the export-symbols node are used to resolve undefined + symbols referenced from the overlay. + +properties: + $nodename: + const: export-symbols + +patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Quoted 8 lines
Documentation/devicetree/bindings/export-symbols.yaml line 31
Quoted 6 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +6
-0+ $ref: /schemas/types.yaml#/definitions/phandle + description: + A symbol exported in the form <symbol_name>=<phandle>. + +additionalProperties: false +Best regards,
Krzysztof
Maybe the dt-schema discussion will give a better description of why I need export-symbols or something similar [0].
I have also been trying to move the discussion regarding global vs local scope overlay application for connectors here [1].
[0]: https://lore.kernel.org/devicetree-spec/[email protected]/T/#u
[1]: https://lore.kernel.org/linux-devicetree/[email protected]/
Best Regards,
Ayush Sigh
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 61 lines · Ayush Singh
Quoted 50 lines · Krzysztof Kozlowski
Quoted 6 lines · Herve Codina
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
I have impression that this is being discussed in three places simultaneously - here, DT spec and DT schema. I don't know how to solve the multiplication, but I will keep answering here, because that's my part.
Quoted 10 lines
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:Quoted 13 lines
... foo_connector: connector1 { export-symbols { connector = <&foo_connector>; }; }; bar_connector: connector2 { export-symbols { connector = <&bar_connector>; }; }; ...And what would this mean? Which symbol is exported - foo or bar?
Quoted 7 lines
- Base device tree board B: ... front_connector: addon-connector { export-symbols { connector = <&front_connector>; }; };<from my other reply in private>
Another problem is that the board DTS should not care about overlays. It feels like breaking encapsulation and I cannot imagine now adding 1000 export-symbols, because every i2c, spi, mikrobus or PCI slot could have an overlay applied.Quoted 8 lines
You could argue that only few nodes will be exported like this, so only real mikrobus connectors. Then I will argue: look at aliases. People alias everything everywhere, not following the guidelines.
If we assume that such overlays are designed for specific boards, thus there will be only one or two exported symbols not 1000, then what is the benefit of export symbols comparing to referencing by full path? </end from my other reply>
Quoted 5 lines
Can you explain how referencing by full path will work in connector + addon board setups?
The full path will be dependent on the connector, which means the same addon board overlay cannot work for different connectors.
That was the assumption.
Quoted 25 lines
Quoted 16 lines
And with above assumption - such overlays designed per board - plus my first point about duplicated exports:
connector = <&foo_connector>;
connector = <&bar_connector>;why not exporting the symbol with the same name? E.g.:
foo_connector: connector1 { export-symbols { whatever-property-style = <&foo_connector>; }; };Quoted 7 lines
and overlay:
node { ... connector = <&foo_connector>; ... };
Quoted 2 lines
Isn't this overlay tied to
foo_connector, i.e. it cannot be used withbar_connector?
I don't know what the example tried to say. I asked the question, so don't ask question to my question. We both apparently do not know. What is the meaning of that example I questioned? To which connector this is an overlay? Which symbol is exported for that example?
Best regards,
Krzysztof
Herve Codina
maintainerRe: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Krzysztof KozlowskiHi Krzysztof,
Thanks a lot for your feedback!
Quoted 31 lines · On Tue, 27 May 2025 20:31:14 +0200 Krzysztof Kozlowski <[email protected]> wrote:
Quoted 6 lines · Herve Codina
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
I have impression that this is being discussed in three places simultaneously - here, DT spec and DT schema. I don't know how to solve the multiplication, but I will keep answering here, because that's my part.
Quoted 18 lines
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:... foo_connector: connector1 { export-symbols { connector = <&foo_connector>; }; };
Quoted 8 lines
Quoted 6 lines
bar_connector: connector2 { export-symbols { connector = <&bar_connector>; }; }; ...And what would this mean? Which symbol is exported - foo or bar?
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not __symbols__) but local to a node.
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to foo_connector.
If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to bar_connector.
Quoted 10 lines
Quoted 9 lines
- Base device tree board B:
... front_connector: addon-connector { export-symbols { connector = <&front_connector>; }; };
Quoted 5 lines
<from my other reply in private>
Another problem is that the board DTS should not care about overlays. It feels like breaking encapsulation and I cannot imagine now adding 1000 export-symbols, because every i2c, spi, mikrobus or PCI slot could have an overlay applied.
The board DTS don't care about overlay itself. It describes a connector where an overlay can be applied.
At this connector, several hardware resources are wired and need to be referenced. The baord DTS offer a way for something else to reference those resources.
The goal is to have a connector where it is allowed to apply an overlay instead of exporting all possible symbols and allowing overlays to add nodes anywhere.
Quoted 4 lines
You could argue that only few nodes will be exported like this, so only real mikrobus connectors. Then I will argue: look at aliases. People alias everything everywhere, not following the guidelines.
Those connector nodes have a compatible string and a binding. The export-symbols will be part of the binding.
Quoted 4 lines
If we assume that such overlays are designed for specific boards, thus there will be only one or two exported symbols not 1000, then what is the benefit of export symbols comparing to referencing by full path?
The overlay is not "designed" for a specific board but for a "specific" connector.
He described an add-on board connected to a specific connector, specific in terms of pinout. I mean an I2C bus is available at connector pin 1 and 2, a GPIO, is available at connector pin 3, an irq line is available at connector pin 4, ...
Every board that offer this connector (pinout compatible) can have the overlay applied to the connector.
Also a board can offer several connectors with same pinout and then an add-on board compatible with this connector pinout can be plugged on each connector. The overlay described the add-on board and should be the same whatever if is is applied at connector A or connector B.
The exact same dtbo should work.
Quoted 15 lines
</end from my other reply>
And with above assumption - such overlays designed per board - plus my first point about duplicated exports:
connector = <&foo_connector>;
connector = <&bar_connector>;why not exporting the symbol with the same name? E.g.:
foo_connector: connector1 { export-symbols { whatever-property-style = <&foo_connector>; }; };
Quoted 7 lines
and overlay:
node { ... connector = <&foo_connector>; ... };
With that, the overlay is designed for the board and not the connector. The exact same overlay cannot be use on different connectors (pinout compatible) available on one board. It cannot also be used on different board which provide the exact same connector (pinout compatible).
Quoted 13 lines
Or even annotation?
foo_connector: connector1 __exported_symbol__ { .... }; node { ... connector = <&foo_connector>; ... };
If you board has 2 connectors:
foo_connector1: connector1 __exported_symbol__ {...};
foo_connector2: connector2 __exported_symbol__ {...};
your overlay need to be specific. The overlay shouldn't depend on the board is going to be applied. The only knowledge from the overlay point of view is the connector.
Quoted 56 lines
? This also answers my further question about DTS style (see at the bottom)
Quoted 11 lines
...- Overlay describing an addon board the can be connected on connectors:
... node { ... connector = <&connector>; ... }; ...Quoted 6 lines
Thanks to the export-symbols node, the overlay can be applied on connector1 or connector2 available on board A but also on addon-connector available on board B.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>I would argue you cannot test a binding, because testing here is part of a process, but what do I know...
Quoted 31 lines
--- .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 Documentation/devicetree/bindings/export-symbols.yamlDocumentation/devicetree/bindings/export-symbols.yaml new file +20
-0@@ -0,0 +1,43 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/export-symbols.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Export symbols + +maintainers: + - Herve Codina <[email protected]> + +description: | + An export-symbols node allows to export symbols for symbols resolution + performed when applying a device tree overlay. + + When a device tree overlay is applied on a node having an export-symbols + node, symbols listed in the export-symbols node are used to resolve undefined + symbols referenced from the overlay. + +properties:
Quoted 8 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 5 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +5
-0+ $nodename: + const: export-symbols + +patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in __symbols__, __fixups__, __local_fixups__ nodes.
Those node are globals to the dtb or the dtbo.
export-symbols node has a finer grain. It is a child of a specific node describing a hardware connector and should be described in the binding.
Quoted 9 lines
Documentation/devicetree/bindings/export-symbols.yaml line 31
Quoted 7 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +6
-0+ $ref: /schemas/types.yaml#/definitions/phandle + description: + A symbol exported in the form <symbol_name>=<phandle>. + +additionalProperties: false +Best regards,
Krzysztof
Again, thanks for your feedback.
I hope we could move forward on this export-symbols topic.
Best regards,
Hervé
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 52 lines · Herve Codina
Hi Krzysztof,
Thanks a lot for your feedback!
Quoted 31 lines · On Tue, 27 May 2025 20:31:14 +0200 Krzysztof Kozlowski <[email protected]> wrote:
Quoted 6 lines · Herve Codina
An export-symbols node allows to export symbols for symbols resolution performed when applying a device tree overlay.
When a device tree overlay is applied on a node having an export-symbols node, symbols listed in the export-symbols node are used to resolve undefined symbols referenced from the overlay.
I have impression that this is being discussed in three places simultaneously - here, DT spec and DT schema. I don't know how to solve the multiplication, but I will keep answering here, because that's my part.
Quoted 18 lines
This allows:
- Referencing symbols from an device tree overlay without the need to know the full base board. Only the connector definition is needed.- Using the exact same overlay on several connectors available on a given board.
For instance, the following description is supported with the export-symbols node:
- Base device tree board A:... foo_connector: connector1 { export-symbols { connector = <&foo_connector>; }; };Quoted 8 lines
Quoted 6 lines
bar_connector: connector2 { export-symbols { connector = <&bar_connector>; }; }; ...And what would this mean? Which symbol is exported - foo or bar?
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.
Quoted 6 lines
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.
OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
...
...
Quoted 6 lines
Quoted 5 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 2 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Quoted 7 lines
Yes, those properties remap phandles.
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.
I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
Best regards,
Krzysztof
Herve Codina
maintainerRe: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <[email protected]> wrote:
...
Quoted 10 lines
Quoted 10 lines
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.
Quoted 5 lines
Quoted 2 lines
If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
Sure, I will add something in the next iteration.
...
Quoted 8 lines
Quoted 8 lines
Quoted 5 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 2 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 9 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals
connector1 {
export-symbols {
i2c_a = <&i2c0>;
i2c_b = <&i2c1>;
};};
In order to avoid the coding style issue, this could be replace with:
connector1 {
export-symbols {
symbol-names = "i2c_a", "i2c_b";
symbols = <&i2c0>, <&i2c1>;
};};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
Hervé
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 60 lines · Herve Codina
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <[email protected]> wrote:...
Quoted 5 lines
Quoted 5 lines
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.Quoted 8 lines
Quoted 6 lines
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
Sure, I will add something in the next iteration.
...
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 2 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 8 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; };
Quoted 9 lines
};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
Hervé
Well, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
Additionally, the further away we move from __symbols__ style, the more difficult the implementation will become since we can currently very easily piggy-back on __symbols__ resolution implementation.
Best Regards,
Ayush Singh
Herve Codina
maintainerRe: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Hi Krzysztof, David, Rob,
Any opinion?
Best regards,
Hervé
Quoted 1 line · On Wed, 18 Jun 2025 15:24:07 +0530 Ayush Singh <[email protected]> wrote:
On 6/18/25 15:02, Herve Codina wrote:
...
Quoted 61 lines
Quoted 37 lines
Quoted 7 lines
Quoted 7 lines
Quoted 5 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 3 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 8 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; };Quoted 9 lines
};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
Additionally, the further away we move from
__symbols__style, the more difficult the implementation will become since we can currently very easily piggy-back on__symbols__resolution implementation.Best Regards,
Ayush Singh
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Ayush SinghQuoted 68 lines · Ayush Singh
Quoted 66 lines · Herve Codina
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <[email protected]> wrote:...
Quoted 5 lines
Quoted 5 lines
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.Quoted 8 lines
Quoted 6 lines
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
Sure, I will add something in the next iteration.
...
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 2 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 8 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; };};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Quoted 4 lines
Additionally, the further away we move from
__symbols__style, the more difficult the implementation will become since we can currently very easily piggy-back on__symbols__resolution implementation.
I care more how I read DTS, so complexity in dtc is less important to me than consistent DTS style.
Best regards,
Krzysztof
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 71 lines · Krzysztof Kozlowski
Quoted 70 lines · Ayush Singh
Quoted 69 lines · Herve Codina
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <[email protected]> wrote:...
Quoted 5 lines
Quoted 5 lines
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.Quoted 8 lines
Quoted 6 lines
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
Sure, I will add something in the next iteration.
...
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Review
Quoted 2 lines
(quoted diff) +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 8 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
Hervé
Quoted 6 lines
Quoted 4 lines
Well, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
Quoted 9 lines
Quoted 3 lines
Additionally, the further away we move from
__symbols__style, the more difficult the implementation will become since we can currently very easily piggy-back on__symbols__resolution implementation.I care more how I read DTS, so complexity in dtc is less important to me than consistent DTS style.
Best regards,
Krzysztof
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 44 lines · Ayush Singh
Quoted 28 lines
Quoted 28 lines
Quoted 28 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
HervéQuoted 6 lines
Quoted 4 lines
Well, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
Krzysztof
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 42 lines · Krzysztof Kozlowski
Quoted 41 lines · Ayush Singh
Quoted 24 lines
Quoted 24 lines
Quoted 24 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 7 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 7 lines
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
Krzysztof
Well, we can modify get_phandle_from_symbols_node to allow matching *_* to *-*. And we can do the same in devicetree easily enough. Not sure if implicit loose matching like that are the best idea.
Zephyr does something similar for compatible strings. It pretty much replaces the all non alphanumeric characters with _ in compatible string match. Although that is more to do with the limitation they are working with, i.e. the devicetree being converted to static headers instead of being runtime thing.
Best Regards,
Ayush Singh
Rob Herring
maintainerRe: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 58 lines · Ayush Singh
Quoted 42 lines · Krzysztof Kozlowski
Quoted 41 lines · Ayush Singh
Quoted 24 lines
Quoted 24 lines
Quoted 24 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 7 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 7 lines
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
KrzysztofWell, we can modify
get_phandle_from_symbols_nodeto allow matching*_*to*-*. And we can do the same in devicetree easily enough. Not sure if implicit loose matching like that are the best idea.
Quoted 5 lines
Zephyr does something similar for compatible strings. It pretty much replaces the all non alphanumeric characters with
_in compatible string match. Although that is more to do with the limitation they are working with, i.e. the devicetree being converted to static headers instead of being runtime thing.
This is just going from bad to worse... If there's a real need to use underscores, then use underscores. But that's all beside the point. I didn't like v1 and nothing has changed in v2 to change that.
This looks like continuing down the path of working around DTB format limitations like DT overlays originally did (which both David (IIRC) and I think was a mistake). But now instead of somewhat hidden, generated data, you're adding manually written/maintained data. I don't have any suggestion currently how to avoid that other than we need to rev the DTB format which no one really wants to hear. Maybe there's some other solution, but I don't have one ATM.
Rob
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 73 lines · Rob Herring
Quoted 55 lines · Ayush Singh
Quoted 41 lines · Krzysztof Kozlowski
Quoted 40 lines · Ayush Singh
Quoted 24 lines
Quoted 24 lines
Quoted 24 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 7 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 7 lines
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
KrzysztofWell, we can modify
get_phandle_from_symbols_nodeto allow matching*_*to*-*. And we can do the same in devicetree easily enough. Not sure if implicit loose matching like that are the best idea.Quoted 5 lines
Zephyr does something similar for compatible strings. It pretty much replaces the all non alphanumeric characters with
_in compatible string match. Although that is more to do with the limitation they are working with, i.e. the devicetree being converted to static headers instead of being runtime thing.This is just going from bad to worse... If there's a real need to use underscores, then use underscores. But that's all beside the point. I didn't like v1 and nothing has changed in v2 to change that.
This looks like continuing down the path of working around DTB format limitations like DT overlays originally did (which both David (IIRC) and I think was a mistake). But now instead of somewhat hidden, generated data, you're adding manually written/maintained data. I don't have any suggestion currently how to avoid that other than we need to rev the DTB format which no one really wants to hear. Maybe there's some other solution, but I don't have one ATM.
Quoted 1 line
Rob
Well, if anyone decides to do a v2 of DTB, I would love to help in any way I can.
Best Regards,
Ayush Singh
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
Quoted 75 lines · Ayush Singh
Quoted 73 lines · Rob Herring
Quoted 55 lines · Ayush Singh
Quoted 41 lines · Krzysztof Kozlowski
Quoted 40 lines · Ayush Singh
Quoted 24 lines
Quoted 24 lines
Quoted 24 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 7 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 7 lines
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
KrzysztofWell, we can modify
get_phandle_from_symbols_nodeto allow matching*_*to*-*. And we can do the same in devicetree easily enough. Not sure if implicit loose matching like that are the best idea.Quoted 5 lines
Zephyr does something similar for compatible strings. It pretty much replaces the all non alphanumeric characters with
_in compatible string match. Although that is more to do with the limitation they are working with, i.e. the devicetree being converted to static headers instead of being runtime thing.This is just going from bad to worse... If there's a real need to use underscores, then use underscores. But that's all beside the point. I didn't like v1 and nothing has changed in v2 to change that.
This looks like continuing down the path of working around DTB format limitations like DT overlays originally did (which both David (IIRC) and I think was a mistake). But now instead of somewhat hidden, generated data, you're adding manually written/maintained data. I don't have any suggestion currently how to avoid that other than we need to rev the DTB format which no one really wants to hear. Maybe there's some other solution, but I don't have one ATM.
Quoted 4 lines
Quoted 1 line
Rob
Well, if anyone decides to do a v2 of DTB, I would love to help in any way I can.
We're already on v17 of DTB (although only 5 of those version numbers were actually used).
It shouldn't actually be that hard to extend it in a number of ways without having to completely redefine it.
Signature · 4 lines
David Gibson (he or they) | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you, not the other way | around. http://www.ozlabs.org/~dgibson
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Ayush SinghQuoted 57 lines · Ayush Singh
Quoted 42 lines · Krzysztof Kozlowski
Quoted 41 lines · Ayush Singh
Quoted 24 lines
Quoted 24 lines
Quoted 24 lines
Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; }; };Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Quoted 8 lines
Quoted 7 lines
Quoted 3 lines
Best regards,
HervéWell, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
And the first syntax solves this how? I don't see the practical difference.
Well, I was more worried about matching which phandle belongs to which symbol easily. Let us assume that 2 symbols will be in each line (after accounting for the indention and 80 char limit) and we have 70 symbols, so 35 lines. To check which phandle belongs to the 2nd symbol on line 25th line of symbol-names, well, you would at the best case need to have something like relative line numbers in your editor. Then you know that the 35th line from the current one is where you need to look.
Quoted 7 lines
Quoted 2 lines
In the current syntax, the symbol name and phandle are on the same line. So well, easy to see which symbols refers to which phandle.
OK, that's valid point. Any ideas how to solve it without introducing underscores for properties?
Best regards,
KrzysztofWell, we can modify
get_phandle_from_symbols_nodeto allow matching*_*to*-*. And we can do the same in devicetree easily enough. Not sure if implicit loose matching like that are the best idea.
Quoted 5 lines
Zephyr does something similar for compatible strings. It pretty much replaces the all non alphanumeric characters with
_in compatible string match. Although that is more to do with the limitation they are working with, i.e. the devicetree being converted to static headers instead of being runtime thing.
This is another reason to consider doing this in a new out-of-band extension to dtb, rather than as "regular" device tree properties. In that case you can redefine your naming conventions to suit your needs.
Signature · 4 lines
David Gibson (he or they) | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you, not the other way | around. http://www.ozlabs.org/~dgibson
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Ayush SinghQuoted 72 lines · Ayush Singh
Quoted 60 lines · Herve Codina
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <[email protected]> wrote:...
Quoted 5 lines
Quoted 5 lines
Symbols are exported only when an overlay is applied on the node where the export-symbols node is available. Those symbols are visible only from the overlay applied. Symbols exported thanks to export-symbols are not global to the all device-tree (it is not
__symbols__) but local to a node.Quoted 8 lines
Quoted 6 lines
If an overlay is applied at connector1 node, it can use the 'connector' symbols and thanks to export-symbols, the 'connector' symbol will be resolved to
foo_connector.If the overlay is applied at connector2 node, the 'connector' symbol is then resolved to
bar_connector.OK, this explains a lot. Unless I missed it, would be nice to include it in binding description.
Sure, I will add something in the next iteration.
...
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Documentation/devicetree/bindings/export-symbols.yaml line 25
Quoted 2 lines
Documentation/devicetree/bindings/export-symbols.yaml new file +2
-0+patternProperties: + "^[a-zA-Z_]?[a-zA-Z0-9_]*$":This messes up with coding style which I would prefer keep intact. Basically these properties will be using label style.
Yes, those properties remap phandles.
Quoted 8 lines
Quoted 5 lines
Their names are the name of the label used from the overlay and their values are the phandle mapped.
You already have this kind properties using label style in
__symbols__,__fixups__,__local_fixups__nodes.I have them in DTB, but I don't have these in DTS. The exported-symbols would be in the DTS and that is what coding style is about.
I think export-symbols has to be in DTS.
Maybe it could be described in an other way in order to avoid the coding style issue you reported.Hardware:
i2c0 from SoC --------- connector 1, I2C A signals i2c1 from SoC --------- connector 1, I2C B signals connector1 { export-symbols { i2c_a = <&i2c0>; i2c_b = <&i2c1>; }; };In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; };Quoted 9 lines
};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
Best regards,
Hervé
Quoted 8 lines
Well, it is possible.
However, on connectors like pb2 header, there will be 50-100 export symbols. So it will start becoming difficult to maintain.
Additionally, the further away we move from
__symbols__style, the more difficult the implementation will become since we can currently very easily piggy-back on__symbols__resolution implementation.
I think that should be a non-goal. Current __symbols__ resolution was a quick hack. Design what makes sense rather than being tied to the ugly past.
Signature · 4 lines
David Gibson (he or they) | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you, not the other way | around. http://www.ozlabs.org/~dgibson
Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node
In reply to Herve CodinaQuoted 8 lines · Herve Codina
In order to avoid the coding style issue, this could be replace with:
connector1 { export-symbols { symbol-names = "i2c_a", "i2c_b"; symbols = <&i2c0>, <&i2c1>; };
Quoted 5 lines
};
Krzysztof, Rob, do you think this could be accepted ?
Ayush, David, do you thing this could be easily implemented in fdtoverlay ?
This is fine with me.
Best regards,
Krzysztof
Herve Codina
maintainerPATCH v2 2/7 of: resolver: Introduce get_phandle_from_symbols_node()
In reply to Herve CodinaIn order to simplify the introduction of the export symbols node handling, group necessary operations done to get a phandle from the __symbols__ node in this dedicated get_phandle_from_symbols_node() function.
--- drivers/of/resolver.c | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-)
drivers/of/resolver.c +26 -13
@@ -212,6 +212,28 @@ static int adjust_local_phandle_references(const struct device_node *local_fixupreturn 0 ; } +static int get_phandle_from_symbols_node (const struct device_node *tree_symbols, +const char *symbol_name, +phandle *phandle) +{ +struct device_node *refnode; +const char *refpath; +int err; + + err =of_property_read_string (tree_symbols, symbol_name, &refpath); +if (err) +return err; + + refnode =of_find_node_by_path (refpath); +if (!refnode) +return -ENOENT ; + + *phandle = refnode->phandle; +of_node_put (refnode); + +return 0 ; +} +/** * of_resolve_phandles - Relocate and resolve overlay against live tree *
@@ -247,11 +269,9 @@ static int adjust_local_phandle_references(const struct device_node *local_fixup*/ int of_resolve_phandles (struct device_node *overlay) { -struct device_node *child, *refnode; -struct device_node *overlay_fixups; +struct device_node *child, *overlay_fixups; struct device_node __free(device_node) *local_fixups = NULL;struct property *prop; -const char *refpath;phandle phandle, phandle_delta;int err;
@@ -298,21 +318,14 @@ int of_resolve_phandles(struct device_node *overlay)if (!of_prop_cmp (prop->name,"name" ))continue ; - err =of_property_read_string (tree_symbols, - prop->name, &refpath); + err =get_phandle_from_symbols_node (tree_symbols, prop->name, + &phandle);if (err) { -pr_err ("node label '%s' not found in live devicetree symbols table\n" , +pr_err ("node label '%s' not found or invalid in live devicetree symbols table\n" , prop->name);return err; } - refnode =of_find_node_by_path (refpath); -if (!refnode) -return -ENOENT ; - - phandle = refnode->phandle; -of_node_put (refnode); - err =update_usages_of_a_phandle_reference (overlay, prop, phandle);if (err)break ;
Signature · 1 line
2.49.0
Herve Codina
maintainerPATCH v2 3/7 of: resolver: Add export_symbols in of_resolve_phandles() parameters
In reply to Herve CodinaIn order to prepare the introduction of the export symbols node handling, add a export_symbols parameter in of_resolve_phandles().
The export_symbols is the export symbols device tree node the resolver will use for the overlay symbols resolution.
--- drivers/of/of_private.h | 2 +- drivers/of/overlay.c | 2 +- drivers/of/resolver.c | 9 +++++++-- drivers/of/unittest.c | 4 ++-- 4 files changed, 11 insertions(+), 6 deletions(-)
drivers/of/of_private.h +1 -1
@@ -94,7 +94,7 @@ static inline void __of_detach_node_sysfs(struct device_node *np) {}#endif #if defined(CONFIG_OF_RESOLVE ) -int of_resolve_phandles (struct device_node *tree); +int of_resolve_phandles (struct device_node *tree,const struct device_node *export_symbols);#endif void __of_phandle_cache_inv_entry (phandle handle);
drivers/of/overlay.c +1 -1
@@ -919,7 +919,7 @@ static int of_overlay_apply(struct overlay_changeset *ovcs, {int ret =0 , ret_revert, ret_tmp; - ret =of_resolve_phandles (ovcs->overlay_root); + ret =of_resolve_phandles (ovcs->overlay_root,NULL );if (ret) goto out;
drivers/of/resolver.c +7 -2
@@ -237,7 +237,8 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,/** * of_resolve_phandles - Relocate and resolve overlay against live tree * -* @overlay: Pointer to devicetree overlay to relocate and resolve +* @overlay: Pointer to devicetree overlay to relocate and resolve +* @export_symbols: Pointer to devicetree export symbols node. * * Modify (relocate) values of local phandles in @overlay to a range that * does not conflict with the live expanded devicetree. Update references
@@ -257,6 +258,10 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,* corresponding to that symbol in the live tree. Update the references in * the overlay with the phandle values in the live tree. * +* @export_symbols can be use in this references update. The resolver tries +* first to find a match in the @export_symbols. If not found, it uses the +* "__symbol__" node in the live tree. +* * @overlay must be detached. * * Resolving and applying @overlay to the live expanded devicetree must be
@@ -267,7 +272,7 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,* * Return: %0 on success or a negative error value on error. */ -int of_resolve_phandles (struct device_node *overlay) +int of_resolve_phandles (struct device_node *overlay,const struct device_node *export_symbols) {struct device_node *child, *overlay_fixups; struct device_node __free(device_node) *local_fixups = NULL;
drivers/of/unittest.c +2 -2
@@ -2026,7 +2026,7 @@ static int __init unittest_data_add(void)*/ of_overlay_mutex_lock (); - rc =of_resolve_phandles (unittest_data_node); + rc =of_resolve_phandles (unittest_data_node,NULL );if (rc) {pr_err ("%s: Failed to resolve phandles (rc=%i)\n" , __func__, rc);of_overlay_mutex_unlock ();
@@ -3915,7 +3915,7 @@ static __init void of_unittest_overlay_high_level(void)* because kmalloc() was not yet available. */ of_overlay_mutex_lock (); -of_resolve_phandles (overlay_base_root); +of_resolve_phandles (overlay_base_root,NULL );of_overlay_mutex_unlock ();
Signature · 1 line
2.49.0
Re: [PATCH v2 3/7] of: resolver: Add export_symbols in of_resolve_phandles() parameters
Hello Hervé,
Quoted 8 lines · On Wed, 30 Apr 2025 14:51:47 +0200 Herve Codina <[email protected]>…
In order to prepare the introduction of the export symbols node handling, add a
export_symbolsparameter inof_resolve_phandles().The
export_symbolsis the export symbols device tree node the resolver will use for the overlay symbols resolution.Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>
[...]
Quoted 13 lines
drivers/of/resolver.c +2
-1@@ -237,7 +237,8 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,/** * of_resolve_phandles - Relocate and resolve overlay against live tree * -* @overlay: Pointer to devicetree overlay to relocate and resolve +* @overlay: Pointer to devicetree overlay to relocate and resolve +* @export_symbols: Pointer to devicetree export symbols node. * * Modify (relocate) values of local phandles in @overlay to a range that * does not conflict with the live expanded devicetree. Update references
drivers/of/resolver.c static int get_phandle_from_symbols_node(const struct device_node *tree_symbols, · line 263
Quoted 6 lines
drivers/of/resolver.c +3
-0@@ -257,6 +258,10 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,* corresponding to that symbol in the live tree. Update the references in * the overlay with the phandle values in the live tree. * +* @export_symbols can be use in this references update. The resolver tries +* first to find a match in the @export_symbols. If not found, it uses the +* "__symbol__" node in the live tree.
The rationale behind this logic is not clear to me. I'd have expected instead this logic:
if (export-symbols != NULL):
match only in export-symbols
else
match only in __symbols__
following the idea that it's better to be strict when introducing something, and possibly relax it later on.
As I see it, with the current logic if you use export-symbols but you build dtbs with -@, you can still match a global label. export-symbols should avoid that instead.
Let me know whether I'm missing something here (which is surely possible).
Other than this, the series looks good to me. I'm not adding my R-by on the implementation patches though, waiting for the above question to be clarified.
Luca
Signature · 3 lines
Luca Ceresoli, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Herve Codina
maintainerRe: [PATCH v2 3/7] of: resolver: Add export_symbols in of_resolve_phandles() parameters
Hi Luca,
Quoted 47 lines · On Fri, 2 May 2025 16:35:59 +0200 Luca Ceresoli <[email protected]>…
Hello Hervé,
Quoted 8 lines · On Wed, 30 Apr 2025 14:51:47 +0200 Herve Codina <[email protected]>…
In order to prepare the introduction of the export symbols node handling, add a
export_symbolsparameter inof_resolve_phandles().The
export_symbolsis the export symbols device tree node the resolver will use for the overlay symbols resolution.Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>[...]
Quoted 13 lines
drivers/of/resolver.c +2
-1@@ -237,7 +237,8 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,/** * of_resolve_phandles - Relocate and resolve overlay against live tree * -* @overlay: Pointer to devicetree overlay to relocate and resolve +* @overlay: Pointer to devicetree overlay to relocate and resolve +* @export_symbols: Pointer to devicetree export symbols node. * * Modify (relocate) values of local phandles in @overlay to a range that * does not conflict with the live expanded devicetree. Update references drivers/of/resolver.c static int get_phandle_from_symbols_node(const struct device_node *tree_symbols, · line 263
Quoted 6 lines
drivers/of/resolver.c +3
-0@@ -257,6 +258,10 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,* corresponding to that symbol in the live tree. Update the references in * the overlay with the phandle values in the live tree. * +* @export_symbols can be use in this references update. The resolver tries +* first to find a match in the @export_symbols. If not found, it uses the +* "__symbol__" node in the live tree. The rationale behind this logic is not clear to me. I'd have expected instead this logic:
if (export-symbols != NULL):
match only in export-symbols
else
match only in__symbols__following the idea that it's better to be strict when introducing something, and possibly relax it later on.
Quoted 6 lines
As I see it, with the current logic if you use export-symbols but you build dtbs with -@, you can still match a global label. export-symbols should avoid that instead.
Let me know whether I'm missing something here (which is surely possible).
No, you don't miss anything, it was just a choice and I have chosen to be not exclusive between export-symbols and __symbols__.
export-symbols is taken in priority and if the symbol is not found in export-symbols, we try with __symbols__.
Maybe I should be stricter. I don't have any strong opinion about that.
Ayush, on fdtoverlay what is the choice done ?
If an export-symbols is present and a symbol needs to be resolved but this symbol is not found in export-symbols, do you try to fing it in __symbols__ or do you simply abort the resolution with an error ?
Best regards,
Hervé
Herve Codina
maintainerPATCH v2 4/7 of: resolver: Add support for the export symbols node
In reply to Herve CodinaSymbols resolution done when an overlay is applied looks only at the global __symbol__ node to resolve unknown symbols from the overlay (i.e symbols listed in the overlay __fixups__ node).
In order to provide flexibilities and allow to define some additional symbols visible only when an overlay is applied to a specific node, introduce the export symbols node.
The export symbols node adds some additional symbols that can be used in the symbols resolution. The resolver tries to match unresolved symbols first using the export symbols node and, if a match is not found, it tries to match using the global __symbol__ node.
Contrary to symbols available in the global __symbols__ node, symbols listed in the export symbols node can be considered as local symbols. Indeed, they can be changed depending on the node the overlay is going to be applied to and are only visibible from the current recolver call.
Handle those additional symbols given by the export symbols node in the symbols resolution.
--- drivers/of/resolver.c | 33 +++++++++++++++++++++++++++++---- drivers/of/unittest.c | 4 ++-- 2 files changed, 31 insertions(+), 6 deletions(-)
drivers/of/resolver.c +29 -4
@@ -220,6 +220,9 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,const char *refpath;int err; +if (!tree_symbols) +return -ENOENT ; + err =of_property_read_string (tree_symbols, symbol_name, &refpath);if (err)return err;
@@ -234,6 +237,25 @@ static int get_phandle_from_symbols_node(const struct device_node *tree_symbols,return 0 ; } +static int get_phandle_from_export_node (const struct device_node *export_symbols, +const char *symbol_name, +phandle *phandle) +{ +struct device_node *refnode; + +if (!export_symbols) +return -ENOENT ; + + refnode =of_parse_phandle (export_symbols, symbol_name,0 ); +if (!refnode) +return -ENOENT ; + + *phandle = refnode->phandle; +of_node_put (refnode); + +return 0 ; +} +/** * of_resolve_phandles - Relocate and resolve overlay against live tree *
@@ -312,7 +334,7 @@ int of_resolve_phandles(struct device_node *overlay, const struct device_node *ereturn 0 ; struct device_node __free(device_node) *tree_symbols = of_find_node_by_path("/__symbols__"); -if (!tree_symbols) { +if (!tree_symbols && !export_symbols) {pr_err ("no symbols in root of device tree.\n" );return -EINVAL ; }
@@ -323,10 +345,13 @@ int of_resolve_phandles(struct device_node *overlay, const struct device_node *eif (!of_prop_cmp (prop->name,"name" ))continue ; - err =get_phandle_from_symbols_node (tree_symbols, prop->name, - &phandle); + err =get_phandle_from_export_node (export_symbols, prop->name, + &phandle); +if (err) + err =get_phandle_from_symbols_node (tree_symbols, prop->name, + &phandle);if (err) { -pr_err ("node label '%s' not found or invalid in live devicetree symbols table\n" , +pr_err ("node label '%s' not found or invalid in live devicetree symbols or export tables\n" , prop->name);return err; }
drivers/of/unittest.c +2 -2
@@ -4146,7 +4146,7 @@ static __init void of_unittest_overlay_high_level(void)/* --- overlay_bad_unresolved --- */ EXPECT_BEGIN (KERN_ERR , -"OF: resolver: node label 'this_label_does_not_exist' not found in live devicetree symbols table" ); +"OF: resolver: node label 'this_label_does_not_exist' not found or invalid in live devicetree symbols or export tables" );EXPECT_BEGIN (KERN_ERR ,"OF: resolver: overlay phandle fixup failed: -22" );
@@ -4156,7 +4156,7 @@ static __init void of_unittest_overlay_high_level(void)EXPECT_END (KERN_ERR ,"OF: resolver: overlay phandle fixup failed: -22" );EXPECT_END (KERN_ERR , -"OF: resolver: node label 'this_label_does_not_exist' not found in live devicetree symbols table" ); +"OF: resolver: node label 'this_label_does_not_exist' not found or invalid in live devicetree symbols or export tables" );return ;
Signature · 1 line
2.49.0
Herve Codina
maintainerPATCH v2 5/7 of: overlay: Add export_symbols_name in of_overlay_fdt_apply() parameters
In reply to Herve CodinaIn order to prepare the introduction of the export symbols node handling, add a export_symbols_name parameter in of_overlay_fdt_apply().
The export_symbols_name is the name of the export symbols subnode available in the base node that will be used by the resolver to handle export symbols resolution.
Having the name of the subnode in parameters instead of the subnode itself avoids the use of an export symbol node that is not directly related to the base node.
--- drivers/misc/lan966x_pci.c | 3 ++- drivers/of/of_kunit_helpers.c | 2 +- drivers/of/overlay.c | 7 ++++++- drivers/of/unittest.c | 4 ++-- include/linux/of.h | 6 ++++-- 5 files changed, 15 insertions(+), 7 deletions(-)
drivers/misc/lan966x_pci.c +2 -1
@@ -128,7 +128,8 @@ static int lan966x_pci_load_overlay(struct lan966x_pci *data)u32 dtbo_size = __dtbo_lan966x_pci_end - __dtbo_lan966x_pci_begin;void *dtbo_start = __dtbo_lan966x_pci_begin; -return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id,dev_of_node (data->dev)); +return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id, +dev_of_node (data->dev),NULL ); }static void lan966x_pci_unload_overlay (struct lan966x_pci *data)
drivers/of/of_kunit_helpers.c +1 -1
@@ -56,7 +56,7 @@ int of_overlay_fdt_apply_kunit(struct kunit *test, void *overlay_fdt,return -ENOMEM ; ret =of_overlay_fdt_apply (overlay_fdt, overlay_fdt_size, - ovcs_id,NULL ); + ovcs_id,NULL ,NULL );if (ret)return ret;
drivers/of/overlay.c +6 -1
@@ -968,6 +968,10 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,* @overlay_fdt_size: number of bytes in @overlay_fdt * @ret_ovcs_id: pointer for returning created changeset id * @base: pointer for the target node to apply overlay +* @export_symbols_name: +* Name of the export symbol subnode of the @base node to +* provide extra symbols. Those extra symbols are used in +* the overlay symbols resolution. * * Creates and applies an overlay changeset. *
@@ -983,7 +987,8 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,*/ int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ret_ovcs_id,const struct device_node *base) +int *ret_ovcs_id,const struct device_node *base, +const char *export_symbols_name) {void *new_fdt;void *new_fdt_align;
drivers/of/unittest.c +2 -2
@@ -3858,7 +3858,7 @@ static int __init overlay_data_apply(const char *overlay_name, int *ovcs_id)pr_err ("no overlay data for %s\n" , overlay_name); ret =of_overlay_fdt_apply (info->dtbo_begin, size, &info->ovcs_id, -NULL ); +NULL ,NULL );if (ovcs_id) *ovcs_id = info->ovcs_id;if (ret <0 )
@@ -4198,7 +4198,7 @@ static int testdrv_probe(struct pci_dev *pdev, const struct pci_device_id *id) } size = info->dtbo_end - info->dtbo_begin; - ret =of_overlay_fdt_apply (info->dtbo_begin, size, &ovcs_id, dn); + ret =of_overlay_fdt_apply (info->dtbo_begin, size, &ovcs_id, dn,NULL );of_node_put (dn);if (ret)return ret;
include/linux/of.h +4 -2
@@ -1749,7 +1749,8 @@ struct of_overlay_notify_data {#ifdef CONFIG_OF_OVERLAY int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ovcs_id,const struct device_node *target_base); +int *ovcs_id,const struct device_node *target_base, +const char *export_symbols_name);int of_overlay_remove (int *ovcs_id);int of_overlay_remove_all (void );
@@ -1759,7 +1760,8 @@ int of_overlay_notifier_unregister(struct notifier_block *nb);#else static inline int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ovcs_id,const struct device_node *target_base) +int *ovcs_id,const struct device_node *target_base, +const char *export_symbols_name) {return -ENOTSUPP ; }
Signature · 1 line
2.49.0
Re: [PATCH v2 5/7] of: overlay: Add export_symbols_name in of_overlay_fdt_apply() parameters
Quoted 64 lines · Herve Codina
In order to prepare the introduction of the export symbols node handling, add a
export_symbols_nameparameter inof_overlay_fdt_apply().The
export_symbols_nameis the name of the export symbols subnode available in the base node that will be used by the resolver to handle export symbols resolution.Having the name of the subnode in parameters instead of the subnode itself avoids the use of an export symbol node that is not directly related to the base node.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>--- drivers/misc/lan966x_pci.c | 3 ++- drivers/of/of_kunit_helpers.c | 2 +- drivers/of/overlay.c | 7 ++++++- drivers/of/unittest.c | 4 ++-- include/linux/of.h | 6 ++++-- 5 files changed, 15 insertions(+), 7 deletions(-)drivers/misc/lan966x_pci.c +2
-1@@ -128,7 +128,8 @@ static int lan966x_pci_load_overlay(struct lan966x_pci *data)u32 dtbo_size = __dtbo_lan966x_pci_end - __dtbo_lan966x_pci_begin;void *dtbo_start = __dtbo_lan966x_pci_begin; -return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id,dev_of_node (data->dev)); +return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id, +dev_of_node (data->dev),NULL ); }static void lan966x_pci_unload_overlay (struct lan966x_pci *data)drivers/of/of_kunit_helpers.c +1
-1@@ -56,7 +56,7 @@ int of_overlay_fdt_apply_kunit(struct kunit *test, void *overlay_fdt,return -ENOMEM ; ret =of_overlay_fdt_apply (overlay_fdt, overlay_fdt_size, - ovcs_id,NULL ); + ovcs_id,NULL ,NULL );if (ret)return ret;drivers/of/overlay.c +4
-0@@ -968,6 +968,10 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,* @overlay_fdt_size: number of bytes in @overlay_fdt * @ret_ovcs_id: pointer for returning created changeset id * @base: pointer for the target node to apply overlay +* @export_symbols_name: +* Name of the export symbol subnode of the @base node to +* provide extra symbols. Those extra symbols are used in +* the overlay symbols resolution. * * Creates and applies an overlay changeset. *
drivers/of/overlay.c static int of_overlay_apply(struct overlay_changeset *ovcs, · line 991
Quoted 6 lines
drivers/of/overlay.c +2
-1@@ -983,7 +987,8 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,*/ int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ret_ovcs_id,const struct device_node *base) +int *ret_ovcs_id,const struct device_node *base, +const char *export_symbols_name)
Do we really need the export-symbols node name to be configurable?
Quoted 40 lines
drivers/of/overlay.c +0
-0{void *new_fdt;void *new_fdt_align;drivers/of/unittest.c +2
-2@@ -3858,7 +3858,7 @@ static int __init overlay_data_apply(const char *overlay_name, int *ovcs_id)pr_err ("no overlay data for %s\n" , overlay_name); ret =of_overlay_fdt_apply (info->dtbo_begin, size, &info->ovcs_id, -NULL ); +NULL ,NULL );if (ovcs_id) *ovcs_id = info->ovcs_id;if (ret <0 )@@ -4198,7 +4198,7 @@ static int testdrv_probe(struct pci_dev *pdev, const struct pci_device_id *id) } size = info->dtbo_end - info->dtbo_begin; - ret =of_overlay_fdt_apply (info->dtbo_begin, size, &ovcs_id, dn); + ret =of_overlay_fdt_apply (info->dtbo_begin, size, &ovcs_id, dn,NULL );of_node_put (dn);if (ret)return ret;include/linux/of.h +2
-1@@ -1749,7 +1749,8 @@ struct of_overlay_notify_data {#ifdef CONFIG_OF_OVERLAY int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ovcs_id,const struct device_node *target_base); +int *ovcs_id,const struct device_node *target_base, +const char *export_symbols_name);int of_overlay_remove (int *ovcs_id);int of_overlay_remove_all (void );
include/linux/of.h int of_overlay_notifier_unregister(struct notifier_block *nb); · line 1767
Quoted 9 lines
include/linux/of.h +2
-1@@ -1759,7 +1760,8 @@ int of_overlay_notifier_unregister(struct notifier_block *nb);#else static inline int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ovcs_id,const struct device_node *target_base) +int *ovcs_id,const struct device_node *target_base, +const char *export_symbols_name) {return -ENOTSUPP ; }
Ayush Singh
Herve Codina
maintainerRe: [PATCH v2 5/7] of: overlay: Add export_symbols_name in of_overlay_fdt_apply() parameters
Hi Ayush,
Quoted 68 lines · On Fri, 2 May 2025 20:10:41 +0530 Ayush Singh <[email protected]> wrote:
Quoted 66 lines · Herve Codina
In order to prepare the introduction of the export symbols node handling, add a
export_symbols_nameparameter inof_overlay_fdt_apply().The
export_symbols_nameis the name of the export symbols subnode available in the base node that will be used by the resolver to handle export symbols resolution.Having the name of the subnode in parameters instead of the subnode itself avoids the use of an export symbol node that is not directly related to the base node.
Signed-off-by Herve Codina <[email protected]>Tested-by Ayush Singh <[email protected]>--- drivers/misc/lan966x_pci.c | 3 ++- drivers/of/of_kunit_helpers.c | 2 +- drivers/of/overlay.c | 7 ++++++- drivers/of/unittest.c | 4 ++-- include/linux/of.h | 6 ++++-- 5 files changed, 15 insertions(+), 7 deletions(-)drivers/misc/lan966x_pci.c +2
-1@@ -128,7 +128,8 @@ static int lan966x_pci_load_overlay(struct lan966x_pci *data)u32 dtbo_size = __dtbo_lan966x_pci_end - __dtbo_lan966x_pci_begin;void *dtbo_start = __dtbo_lan966x_pci_begin; -return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id,dev_of_node (data->dev)); +return of_overlay_fdt_apply (dtbo_start, dtbo_size, &data->ovcs_id, +dev_of_node (data->dev),NULL ); }static void lan966x_pci_unload_overlay (struct lan966x_pci *data)drivers/of/of_kunit_helpers.c +1
-1@@ -56,7 +56,7 @@ int of_overlay_fdt_apply_kunit(struct kunit *test, void *overlay_fdt,return -ENOMEM ; ret =of_overlay_fdt_apply (overlay_fdt, overlay_fdt_size, - ovcs_id,NULL ); + ovcs_id,NULL ,NULL );if (ret)return ret;drivers/of/overlay.c +4
-0@@ -968,6 +968,10 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,* @overlay_fdt_size: number of bytes in @overlay_fdt * @ret_ovcs_id: pointer for returning created changeset id * @base: pointer for the target node to apply overlay +* @export_symbols_name: +* Name of the export symbol subnode of the @base node to +* provide extra symbols. Those extra symbols are used in +* the overlay symbols resolution. * * Creates and applies an overlay changeset. * @@ -983,7 +987,8 @@ static int of_overlay_apply(struct overlay_changeset *ovcs,*/
Quoted 6 lines
drivers/of/overlay.c static int of_overlay_apply(struct overlay_changeset *ovcs, · line 991
Quoted 4 lines
drivers/of/overlay.c +2
-1int of_overlay_fdt_apply (const void *overlay_fdt,u32 overlay_fdt_size, -int *ret_ovcs_id,const struct device_node *base) +int *ret_ovcs_id,const struct device_node *base, +const char *export_symbols_name)Do we really need the export-symbols node name to be configurable?
Well, it depends on the export-symbols acceptance in device-tree spec or some other global device-tree bindings.
If this export-symbols node is accepted globally, the name is not needed and shouldn't be configurable.
If this node name can be changed from one node binding to an other, having it configurable is interesting.
That said, according to your work done at higher level (device-tree spec), this name tends to be global. If confirmed, I will remove the export_symbols_name parameter in the next iteration and use 'export-symbols' for all cases.
Best regards,
Hervé
Herve Codina
maintainerPATCH v2 6/7 of: overlay: Add support for the export symbols node
In reply to Herve CodinaThe resolver already supports the use of the export symbol node.
Add support of the export symbol node feature in of_overlay_fdt_apply() simply getting the export node from its name and passing it to the resolver.
--- drivers/of/overlay.c | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-)
drivers/of/overlay.c +20 -3
@@ -891,6 +891,10 @@ static void free_overlay_changeset(struct overlay_changeset *ovcs)* of_overlay_apply() - Create and apply an overlay changeset * @ovcs: overlay changeset * @base: point to the target node to apply overlay +* @export_symbols_name: +* Name of the export symbol subnode of the @base node to +* provide extra symbols. Those extra symbols are used in +* the overlay symbols resolution. * * Creates and applies an overlay changeset. *
@@ -915,11 +919,24 @@ static void free_overlay_changeset(struct overlay_changeset *ovcs)*/ static int of_overlay_apply (struct overlay_changeset *ovcs, -const struct device_node *base) +const struct device_node *base, +const char *export_symbols_name) { +struct device_node *export_symbols =NULL ;int ret =0 , ret_revert, ret_tmp; - ret =of_resolve_phandles (ovcs->overlay_root,NULL ); +if (base && export_symbols_name) { + export_symbols =of_get_child_by_name (base, export_symbols_name); +if (!export_symbols) { +pr_err ("overlay get export symbols '%s' from %pOF failed\n" , + export_symbols_name, base); + ret = -EINVAL ; + goto out; + } + } + + ret =of_resolve_phandles (ovcs->overlay_root, export_symbols); +of_node_put (export_symbols);if (ret) goto out;
@@ -1059,7 +1076,7 @@ int of_overlay_fdt_apply(const void *overlay_fdt, u32 overlay_fdt_size, } ovcs->overlay_mem = overlay_mem; - ret =of_overlay_apply (ovcs, base); + ret =of_overlay_apply (ovcs, base, export_symbols_name);/* * If of_overlay_apply() error, calling free_overlay_changeset() may * result in a memory leak if the apply partly succeeded, so do NOT
Signature · 1 line
2.49.0
Herve Codina
maintainerPATCH v2 7/7 of: unittest: Add tests for export symbols
In reply to Herve CodinaThe export symbols feature allows to use some additional symbols provided in an export symbols node to resolve overlay symbols.
Add tests to exercise the export symbols feature.
--- drivers/of/unittest-data/Makefile | 5 ++ .../unittest-data/overlay_export_symbols.dtso | 15 +++++ .../of/unittest-data/testcases_common.dtsi | 1 + .../unittest-data/tests-export-symbols.dtsi | 30 +++++++++ drivers/of/unittest.c | 65 +++++++++++++++++++ 5 files changed, 116 insertions(+) create mode 100644 drivers/of/unittest-data/overlay_export_symbols.dtso create mode 100644 drivers/of/unittest-data/tests-export-symbols.dtsi
drivers/of/unittest-data/Makefile +5 -0
@@ -34,6 +34,7 @@ obj-$(CONFIG_OF_OVERLAY) += overlay.dtbo.o \ overlay_gpio_04a.dtbo.o \ overlay_gpio_04b.dtbo.o \ overlay_pci_node.dtbo.o \ + overlay_export_symbols.dtbo.o \ overlay_bad_unresolved.dtbo.o # enable creation of __symbols__ node
@@ -66,6 +67,10 @@ DTC_FLAGS_testcases += -Wno-interrupts_property \ # overlay_bad_add_dup_prop.dtbo \ # overlay_bad_phandle.dtbo \ # overlay_bad_symbol.dtbo \ +# +# Also overlay_export_symbols_ovl.dtbo is designed to be applied to a specific +# node and cannot be applied statically with fdtoverlay + apply_static_overlay_1 := overlay_0.dtbo \ overlay_1.dtbo \
drivers/of/unittest-data/overlay_export_symbols.dtso new file +15 -0
@@ -0,0 +1,15 @@ +// SPDX-License-Identifier: GPL-2.0 +/dts-v1/; +/plugin/; + +/ { + fragment@0 { + target-path=""; + __overlay__ { + ovl_node { + ref-base = <&test_export_base>; + ref-node = <&test_export_node>; + }; + }; + }; +};
drivers/of/unittest-data/testcases_common.dtsi +1 -0
@@ -18,4 +18,5 @@ node-remove { #include "tests-address.dtsi" #include "tests-platform.dtsi" #include "tests-overlay.dtsi" +#include "tests-export-symbols.dtsi" #include "tests-lifecycle.dtsi"
drivers/of/unittest-data/tests-export-symbols.dtsi new file +30 -0
@@ -0,0 +1,30 @@ +// SPDX-License-Identifier: GPL-2.0 + +/ { + testcase-data { + test-export-symbols { + test_export_symbols_b0: base0 { + test_export_symbols_n0: node { + dummy; + }; + + export-symbols { + test_export_base = <&test_export_symbols_b0>; + test_export_node = <&test_export_symbols_n0>; + }; + }; + + test_export_symbols_b1: base1 { + + test_export_symbols_n1: node { + dummy; + }; + + export-symbols { + test_export_base = <&test_export_symbols_b1>; + test_export_node = <&test_export_symbols_n1>; + }; + }; + }; + }; +};
drivers/of/unittest.c +65 -0
83 lines not on this page · raw message
Signature · 1 line
2.49.0