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


>
>
>> ---
>>   .../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 <[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_]*$":
> 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/[email protected]/T/#u

[1]: 
https://lore.kernel.org/linux-devicetree/[email protected]/


Best Regards,

Ayush Sigh