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.
Signed-off-by: Herve Codina <herve.codina@bootlin.com>
Tested-by: Ayush Singh <ayush@beagleboard.org>
---
.../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++
1 file changed, 43 insertions(+)
create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
diff --git a/Documentation/devicetree/bindings/export-symbols.yaml b/Documentation/devicetree/bindings/export-symbols.yaml
new file mode 100644
index 000000000000..0e404eff8937
--- /dev/null
+++ b/Documentation/devicetree/bindings/export-symbols.yaml
@@ -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 <herve.codina@bootlin.com>
+
+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>;
+ };
+ };
+...
--
2.49.0On 30/04/2025 14:51, Herve Codina wrote:
> 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.
>
> 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>;
> };
> };
> ...
And what would this mean? Which symbol is exported - foo or bar?
>
> - 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)
> ...
>
> - 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.
>
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> Tested-by: Ayush Singh <ayush@beagleboard.org>
I would argue you cannot test a binding, because testing here is part of
a process, but what do I know...
> ---
> .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++
> 1 file changed, 43 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
>
> diff --git a/Documentation/devicetree/bindings/export-symbols.yaml b/Documentation/devicetree/bindings/export-symbols.yaml
> new file mode 100644
> index 000000000000..0e404eff8937
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/export-symbols.yaml
> @@ -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 <herve.codina@bootlin.com>
> +
> +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_]*$":
This messes up with coding style which I would prefer keep intact.
Basically these properties will be using label style.
> + $ref: /schemas/types.yaml#/definitions/phandle
> + description:
> + A symbol exported in the form <symbol_name>=<phandle>.
> +
> +additionalProperties: false
> +
Best regards,
Krzysztof
Hi Krzysztof,
Thanks a lot for your feedback!
On Tue, 27 May 2025 20:31:14 +0200
Krzysztof Kozlowski <krzk@kernel.org> wrote:
> On 30/04/2025 14:51, Herve Codina wrote:
> > 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.
>
> >
> > 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>;
> > };
> > };
> > ...
>
> 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.
>
> >
> > - 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.
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.
>
> 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.
>
> 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.
> </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>;
> ...
> };
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).
>
> 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.
>
> ? This also answers my further question about DTS style (see at the bottom)
>
> > ...
> >
> > - 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.
> >
> > Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> > Tested-by: Ayush Singh <ayush@beagleboard.org>
>
> I would argue you cannot test a binding, because testing here is part of
> a process, but what do I know...
>
>
> > ---
> > .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++
> > 1 file changed, 43 insertions(+)
> > create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/export-symbols.yaml b/Documentation/devicetree/bindings/export-symbols.yaml
> > new file mode 100644
> > index 000000000000..0e404eff8937
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/export-symbols.yaml
> > @@ -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 <herve.codina@bootlin.com>
> > +
> > +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_]*$":
>
> 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.
>
> > + $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é
On 28/05/2025 18:57, Herve Codina wrote:
> Hi Krzysztof,
>
> Thanks a lot for your feedback!
>
> On Tue, 27 May 2025 20:31:14 +0200
> Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
>> On 30/04/2025 14:51, Herve Codina wrote:
>>> 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.
>>
>>>
>>> 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>;
>>> };
>>> };
>>> ...
>>
>> 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.
OK, this explains a lot. Unless I missed it, would be nice to include it
in binding description.
...
...
>>> +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.
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
Hi Krzysztof,
On Wed, 4 Jun 2025 20:35:51 +0200
Krzysztof Kozlowski <krzk@kernel.org> wrote:
...
> >
> > 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.
>
> 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.
...
> >>> +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.
>
> 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é
On 18/06/2025 11:32, Herve Codina wrote:
>
> 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 ?
This is fine with me.
Best regards,
Krzysztof
On 6/18/25 15:02, Herve Codina wrote:
> Hi Krzysztof,
>
> On Wed, 4 Jun 2025 20:35:51 +0200
> Krzysztof Kozlowski <krzk@kernel.org> wrote:
>
> ...
>
>>> 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.
>> 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.
>
> ...
>
>>>>> +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.
>> 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é
>
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
On Wed, Jun 18, 2025 at 03:24:07PM +0530, Ayush Singh wrote:
>
> On 6/18/25 15:02, Herve Codina wrote:
> > Hi Krzysztof,
> >
> > On Wed, 4 Jun 2025 20:35:51 +0200
> > Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >
> > ...
> >
> > > > 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.
> > > 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.
> >
> > ...
> >
> > > > > > +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.
> > > 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é
> >
>
> 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.
--
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
On 18/06/2025 11:54, Ayush Singh wrote:
>
> On 6/18/25 15:02, Herve Codina wrote:
>> Hi Krzysztof,
>>
>> On Wed, 4 Jun 2025 20:35:51 +0200
>> Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>
>> ...
>>
>>>> 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.
>>> 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.
>>
>> ...
>>
>>>>>> +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.
>>> 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é
>>
>
> 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.
>
> 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
On 8/17/25 13:11, Krzysztof Kozlowski wrote:
> On 18/06/2025 11:54, Ayush Singh wrote:
>> On 6/18/25 15:02, Herve Codina wrote:
>>> Hi Krzysztof,
>>>
>>> On Wed, 4 Jun 2025 20:35:51 +0200
>>> Krzysztof Kozlowski <krzk@kernel.org> wrote:
>>>
>>> ...
>>>
>>>>> 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.
>>>> 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.
>>>
>>> ...
>>>
>>>>>>> +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.
>>>> 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é
>>>
>> 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.
>> 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
On 17/08/2025 10:18, Ayush Singh wrote:
>>>>
>>>> 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é
>>>>
>>> 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.
OK, that's valid point. Any ideas how to solve it without introducing
underscores for properties?
Best regards,
Krzysztof
On 8/17/25 13:52, Krzysztof Kozlowski wrote:
> On 17/08/2025 10:18, Ayush Singh wrote:
>>>>> 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é
>>>>>
>>>> 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.
> 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
On Sun, Aug 17, 2025 at 02:12:28PM +0530, Ayush Singh wrote:
> On 8/17/25 13:52, Krzysztof Kozlowski wrote:
>
> > On 17/08/2025 10:18, Ayush Singh wrote:
> > > > > > 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é
> > > > > >
> > > > > 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.
> > 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.
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.
--
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
On Sun, Aug 17, 2025 at 3:42 AM Ayush Singh <ayush@beagleboard.org> wrote:
>
> On 8/17/25 13:52, Krzysztof Kozlowski wrote:
>
> > On 17/08/2025 10:18, Ayush Singh wrote:
> >>>>> 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é
> >>>>>
> >>>> 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.
> > 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.
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
On 8/18/25 22:35, Rob Herring wrote:
> On Sun, Aug 17, 2025 at 3:42 AM Ayush Singh <ayush@beagleboard.org> wrote:
>> On 8/17/25 13:52, Krzysztof Kozlowski wrote:
>>
>>> On 17/08/2025 10:18, Ayush Singh wrote:
>>>>>>> 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é
>>>>>>>
>>>>>> 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.
>>> 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.
> 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
Well, if anyone decides to do a v2 of DTB, I would love to help in any
way I can.
Best Regards,
Ayush Singh
On Mon, Aug 18, 2025 at 11:07:57PM +0530, Ayush Singh wrote:
>
> On 8/18/25 22:35, Rob Herring wrote:
> > On Sun, Aug 17, 2025 at 3:42 AM Ayush Singh <ayush@beagleboard.org> wrote:
> > > On 8/17/25 13:52, Krzysztof Kozlowski wrote:
> > >
> > > > On 17/08/2025 10:18, Ayush Singh wrote:
> > > > > > > > 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é
> > > > > > > >
> > > > > > > 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.
> > > > 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.
> > 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
>
> 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.
--
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
Hi Krzysztof, David, Rob,
Any opinion?
Best regards,
Hervé
On Wed, 18 Jun 2025 15:24:07 +0530
Ayush Singh <ayush@beagleboard.org> wrote:
> On 6/18/25 15:02, Herve Codina wrote:
...
> >
> >>>>> +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.
> >> 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é
> >
>
> 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
>
On 5/28/25 00:01, Krzysztof Kozlowski wrote:
> On 30/04/2025 14:51, Herve Codina wrote:
>> 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.
>
>> 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>;
>> };
>> };
>> ...
> And what would this mean? Which symbol is exported - foo or bar?
>
>> - 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>
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.
>
> 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>;
> ...
> };
Isn't this overlay tied to `foo_connector`, i.e. it cannot be used with
`bar_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)
>
>> ...
>>
>> - 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.
>>
>> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
>> Tested-by: Ayush Singh <ayush@beagleboard.org>
> 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.
>
>
>> ---
>> .../devicetree/bindings/export-symbols.yaml | 43 +++++++++++++++++++
>> 1 file changed, 43 insertions(+)
>> create mode 100644 Documentation/devicetree/bindings/export-symbols.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/export-symbols.yaml b/Documentation/devicetree/bindings/export-symbols.yaml
>> new file mode 100644
>> index 000000000000..0e404eff8937
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/export-symbols.yaml
>> @@ -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 <herve.codina@bootlin.com>
>> +
>> +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_]*$":
> This messes up with coding style which I would prefer keep intact.
> Basically these properties will be using label style.
>
>> + $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/20250411-export-symbols-v3-1-f59368d97063@beagleboard.org/T/#u
[1]:
https://lore.kernel.org/linux-devicetree/9c326bb7-e09a-4c21-944f-006b3fad1870@beagleboard.org/
Best Regards,
Ayush Sigh
On 28/05/2025 09:59, Ayush Singh wrote:
> On 5/28/25 00:01, Krzysztof Kozlowski wrote:
>
>> On 30/04/2025 14:51, Herve Codina wrote:
>>> 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.
>>
>>> 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>;
>>> };
>>> };
>>> ...
>> And what would this mean? Which symbol is exported - foo or bar?
>>
>>> - 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>
>
> 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.
>
>
>>
>> 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>;
>> ...
>> };
>
>
> Isn't this overlay tied to `foo_connector`, i.e. it cannot be used with
> `bar_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
On Wed, 30 Apr 2025 14:51:45 +0200
Herve Codina <herve.codina@bootlin.com> wrote:
> 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.
>
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> Tested-by: Ayush Singh <ayush@beagleboard.org>
Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
--
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
© 2016 - 2025 Red Hat, Inc.