Re: [PATCH v2 1/7] dt-bindings: Add support for export-symbols node

[Krzysztof Kozlowski <krzk@kernel.org>]

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>

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