Message-ID: <6c61a101-6ec7-4350-bfa7-5b7d32177818@beagleboard.org>
Date: Wed, 28 May 2025 13:29:14 +0530
From: Ayush Singh <ayush@...gleboard.org>
To: Krzysztof Kozlowski <krzk@...nel.org>,
 Herve Codina <herve.codina@...tlin.com>,
 David Gibson <david@...son.dropbear.id.au>, Andrew Davis <afd@...com>,
 Geert Uytterhoeven <geert@...ux-m68k.org>, Rob Herring <robh@...nel.org>,
 Krzysztof Kozlowski <krzk+dt@...nel.org>, Conor Dooley
 <conor+dt@...nel.org>, Arnd Bergmann <arnd@...db.de>,
 Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
 Saravana Kannan <saravanak@...gle.com>
Cc: devicetree@...r.kernel.org, devicetree-compiler@...r.kernel.org,
 linux-kernel@...r.kernel.org, Luca Ceresoli <luca.ceresoli@...tlin.com>,
 Thomas Petazzoni <thomas.petazzoni@...tlin.com>
Subject: Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node

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@...tlin.com>
>> Tested-by: Ayush Singh <ayush@...gleboard.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@...tlin.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

Powered by blists - more mailing lists