Re: [PATCH 0/7] of: overlay: Add support for export-symbols node feature

Re: [PATCH 0/7] of: overlay: Add support for export-symbols node feature

[Rob Herring]

+dtc list and David G.

On Tue, Dec 10, 2024 at 2:16 AM Herve Codina <herve.codina@bootlin.com> wrote:
>
> Hi Rob,
>
> On Mon, 9 Dec 2024 14:11:09 -0600
> Rob Herring <robh@kernel.org> wrote:
>
> ...
> > >
> > > Our overlay using the nexus node can contains:
> > >    node {
> > >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> > >    };
> >
> > Couldn't we make something like this work:
> >
> > connector: __overlay__ {
> >
> >    node {
> >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> >    };
> > };
> >
> > We already have to process all the phandles in the overlay. So this
> > just changes handling of 'connector' from being a local phandle which
> > we just renumber to an unresolved phandle which we have to lookup and
> > replace the phandle uses with.
> >
>
> I have tried what you suggested but I've got some issues with dtc.
>
> If a label is not used as a phandle in a dts, dtc doesn't create the phandle
> property in the pointed node (except if we use '-@' option but I don't want
> to add all symbols in my dtb just for one or two connector symbols).

Sorry, but that's the cost of using overlays, and that's pretty
orthogonal to the issue of how the overlay references the connector
node.

However, I agree '-@' is a pretty big switch and an issue that's been
discussed before. I also don't like that all labels become part of the
ABI nor the fact that overlays can make any random modification
anywhere in the DT. I would rather see some sort of explicit opt-in
mechanism of nodes we can apply overlays to. Perhaps we could do
something like this:

/export/ label: node {
};

And then __symbols__ can be only those exported labels (unless -@ is used).

> The way to make sure that the phandle property will be created in the base
> DT node by dtc is to reference the label as a phandle in the base DT.
> The export-symbols node references this label as a phandle in the base DT
> and so, with that, dtc creates the phandle property.
>
> Also, using 'connector: __overlay__' allows to have only one label from
> the base DT to be referenced by the overlay.
>
> I don't know if use cases exist where more than one label need to be
> referenced but this 'one label' constraint is not present with the
> export-symbols node.
>
> The use case where more than one label would be needed is the need for a
> phandle from the overlay that couldn't be translated by the connector nexus
> node. Maybe pinctrl because it uses of_find_node_by_phandle().

Labels are an ABI. I can't see that we need to remap them when we can
just say the name must be X. We can have multiple labels on a node as
well. So I think the problem space is purely mapping 1 name to
multiple possible names.

The connector handling has to be addressed binding by binding at least
for each pattern of binding. Pinctrl binding is pretty unique, so we
should make sure we can handle it in this case.

> Last point, having export-symbols node makes some nodes explicitly
> candidates for an overlay and defines the label to be used on the base DT
> node side. This specific label can be described in the node binding as well
> as the nexus node properties.

Both David (IIRC) and I feel that putting the overlay info
(__symbols__, __fixups__, etc.) within the DT data rather than in the
DTB format was a mistake. The export-symbols node expands on that, so
I'm not sure that's the right direction.

(We should have rev'ed the DTB format to store type information for
(at a minimum) phandles.)

> With 'connector: __overlay__', the overlay can be applied on any nodes, at
> least from the needed label point of view without any restrictions.

Certainly that is something I'd like to have some control over. An
/export/ tag would accomplish that.

One idea I have there is that the overlay could have the compatible of
the connector and we use that for matching. That would give us a way
to know what base DTs overlays apply to. Then you could load an
overlay and dispatch it to the correct driver to handle. It would have
to be handled as a special case as the compatible may match, but
wouldn't necessarily be equal values.


I'll throw out another idea. What if we make resolving phandle errors
something that can be handled by the connector driver? The driver
knows 'connector' resolves to the connector node it is applying the
overlay to.

Rob

Re: [PATCH 0/7] of: overlay: Add support for export-symbols node feature

[Herve Codina]

Hi Rob,

On Tue, 10 Dec 2024 07:46:02 -0600
Rob Herring <robh@kernel.org> wrote:

> +dtc list and David G.
> 
> On Tue, Dec 10, 2024 at 2:16 AM Herve Codina <herve.codina@bootlin.com> wrote:
> >
> > Hi Rob,
> >
> > On Mon, 9 Dec 2024 14:11:09 -0600
> > Rob Herring <robh@kernel.org> wrote:
> >
> > ...  
> > > >
> > > > Our overlay using the nexus node can contains:
> > > >    node {
> > > >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> > > >    };  
> > >
> > > Couldn't we make something like this work:
> > >
> > > connector: __overlay__ {
> > >
> > >    node {
> > >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> > >    };
> > > };
> > >
> > > We already have to process all the phandles in the overlay. So this
> > > just changes handling of 'connector' from being a local phandle which
> > > we just renumber to an unresolved phandle which we have to lookup and
> > > replace the phandle uses with.
> > >  
> >
> > I have tried what you suggested but I've got some issues with dtc.
> >
> > If a label is not used as a phandle in a dts, dtc doesn't create the phandle
> > property in the pointed node (except if we use '-@' option but I don't want
> > to add all symbols in my dtb just for one or two connector symbols).  
> 
> Sorry, but that's the cost of using overlays, and that's pretty
> orthogonal to the issue of how the overlay references the connector
> node.
> 
> However, I agree '-@' is a pretty big switch and an issue that's been
> discussed before. I also don't like that all labels become part of the
> ABI nor the fact that overlays can make any random modification
> anywhere in the DT. I would rather see some sort of explicit opt-in
> mechanism of nodes we can apply overlays to. Perhaps we could do
> something like this:
> 
> /export/ label: node {
> };
> 
> And then __symbols__ can be only those exported labels (unless -@ is used).
> 
> > The way to make sure that the phandle property will be created in the base
> > DT node by dtc is to reference the label as a phandle in the base DT.
> > The export-symbols node references this label as a phandle in the base DT
> > and so, with that, dtc creates the phandle property.
> >
> > Also, using 'connector: __overlay__' allows to have only one label from
> > the base DT to be referenced by the overlay.
> >
> > I don't know if use cases exist where more than one label need to be
> > referenced but this 'one label' constraint is not present with the
> > export-symbols node.
> >
> > The use case where more than one label would be needed is the need for a
> > phandle from the overlay that couldn't be translated by the connector nexus
> > node. Maybe pinctrl because it uses of_find_node_by_phandle().  
> 
> Labels are an ABI. I can't see that we need to remap them when we can
> just say the name must be X. We can have multiple labels on a node as
> well. So I think the problem space is purely mapping 1 name to
> multiple possible names.

So, with a base DT having:
  /export/ label0: node@0 {
  }

  /export/ label1: node@1 {
  }

the __symbols__ node will contains:
  __symbols__ {
	label0 = ...;
	label1 = ...;
  }

without export-symbols, the overlay will look like this:
  connector: __overlay__ {
	...
	ref = <&connector>;
  }

The "connector" label is the only one we can use from the overlay to
reference the base DT (special label defined on the __overlay__ node).
As it is defined to point to __overlay__, it has to be resolved to the
exported symbol that point to the node where the overlay is applied.

If the overlay is applied on node@0, 'connector' is resolved to node@0.

This case cannot be handled:
   connector: __overlay__ {
	...
	ref1 = <&connector>;
        ref2 = <&other-label-from-base-dt>;
   }

Indeed, only one 'connector' label can be resolved to node@0 or node@1.
other-label-from-base-dt cannot be resolved based on the node the overlay
is applied to.

Again, I am not sure on my side that we have to handle this case of multiple
labels in the overlay that point to the base DT dependent on node@0 or node@1.

On my use case, I considered the node@0 or node@1 as nexus nodes and so, all
GPIOs (soon PWM, I hope, and probably other ressources in the future) can be
referenced using nexus nodes.

> 
> The connector handling has to be addressed binding by binding at least
> for each pattern of binding. Pinctrl binding is pretty unique, so we
> should make sure we can handle it in this case.

If pinctrl can be handled using nexus node, it should be ok. Otherwise
things are going to be complicated. Again, with your proposal, we can
reference only one label from the overlay, the node where the overlay
is applied to.

> 
> > Last point, having export-symbols node makes some nodes explicitly
> > candidates for an overlay and defines the label to be used on the base DT
> > node side. This specific label can be described in the node binding as well
> > as the nexus node properties.  
> 
> Both David (IIRC) and I feel that putting the overlay info
> (__symbols__, __fixups__, etc.) within the DT data rather than in the
> DTB format was a mistake. The export-symbols node expands on that, so
> I'm not sure that's the right direction.
> 
> (We should have rev'ed the DTB format to store type information for
> (at a minimum) phandles.)
> 
> > With 'connector: __overlay__', the overlay can be applied on any nodes, at
> > least from the needed label point of view without any restrictions.  
> 
> Certainly that is something I'd like to have some control over. An
> /export/ tag would accomplish that.
> 
> One idea I have there is that the overlay could have the compatible of
> the connector and we use that for matching. That would give us a way
> to know what base DTs overlays apply to. Then you could load an
> overlay and dispatch it to the correct driver to handle. It would have
> to be handled as a special case as the compatible may match, but
> wouldn't necessarily be equal values.

compatible property will not be enough. We can have two exact same
connectors on the same base board:
  /export/ label0: node@0 {
     compatible = 'foo,addon-connector';
  }

  /export/ label1: node@1 {
     compatible = 'foo,addon-connector';
  }

To load the overlay, we can match compatible for sure but we need to node
the overlay is supposed to be applied to.

Also, it you want to check bindings for node@0 available in the base DT
and bindings in the overlay, having one compatible string with different
meaning will introduce some complexity.
A compatible string can now define the "provider" part (the base DT) and
the "consumer" part (the overlay).

> 
> 
> I'll throw out another idea. What if we make resolving phandle errors
> something that can be handled by the connector driver? The driver
> knows 'connector' resolves to the connector node it is applying the
> overlay to.

Well, my proposal was to give enough information to the resolver instead of
handling errors.

I probably miss something but I don't see what could be the benefit to do
that in the other way. Can you give me more details about your idea?

Best regards,
Hervé

Re: [PATCH 0/7] of: overlay: Add support for export-symbols node feature

[Herve Codina]

Hi Rob, David,

On Tue, 10 Dec 2024 15:58:33 +0100
Herve Codina <herve.codina@bootlin.com> wrote:

> Hi Rob,
> 
> On Tue, 10 Dec 2024 07:46:02 -0600
> Rob Herring <robh@kernel.org> wrote:
> 
> > +dtc list and David G.
> > 
> > On Tue, Dec 10, 2024 at 2:16 AM Herve Codina <herve.codina@bootlin.com> wrote:  
> > >
> > > Hi Rob,
> > >
> > > On Mon, 9 Dec 2024 14:11:09 -0600
> > > Rob Herring <robh@kernel.org> wrote:
> > >
> > > ...    
> > > > >
> > > > > Our overlay using the nexus node can contains:
> > > > >    node {
> > > > >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> > > > >    };    
> > > >
> > > > Couldn't we make something like this work:
> > > >
> > > > connector: __overlay__ {
> > > >
> > > >    node {
> > > >       foo-gpio = <&connector 0 GPIO_ACTIVE_HIGH>;
> > > >    };
> > > > };
> > > >
> > > > We already have to process all the phandles in the overlay. So this
> > > > just changes handling of 'connector' from being a local phandle which
> > > > we just renumber to an unresolved phandle which we have to lookup and
> > > > replace the phandle uses with.
> > > >    
> > >
> > > I have tried what you suggested but I've got some issues with dtc.
> > >
> > > If a label is not used as a phandle in a dts, dtc doesn't create the phandle
> > > property in the pointed node (except if we use '-@' option but I don't want
> > > to add all symbols in my dtb just for one or two connector symbols).    
> > 
> > Sorry, but that's the cost of using overlays, and that's pretty
> > orthogonal to the issue of how the overlay references the connector
> > node.
> > 
> > However, I agree '-@' is a pretty big switch and an issue that's been
> > discussed before. I also don't like that all labels become part of the
> > ABI nor the fact that overlays can make any random modification
> > anywhere in the DT. I would rather see some sort of explicit opt-in
> > mechanism of nodes we can apply overlays to. Perhaps we could do
> > something like this:
> > 
> > /export/ label: node {
> > };
> > 
> > And then __symbols__ can be only those exported labels (unless -@ is used).
> >   
> > > The way to make sure that the phandle property will be created in the base
> > > DT node by dtc is to reference the label as a phandle in the base DT.
> > > The export-symbols node references this label as a phandle in the base DT
> > > and so, with that, dtc creates the phandle property.
> > >
> > > Also, using 'connector: __overlay__' allows to have only one label from
> > > the base DT to be referenced by the overlay.
> > >
> > > I don't know if use cases exist where more than one label need to be
> > > referenced but this 'one label' constraint is not present with the
> > > export-symbols node.
> > >
> > > The use case where more than one label would be needed is the need for a
> > > phandle from the overlay that couldn't be translated by the connector nexus
> > > node. Maybe pinctrl because it uses of_find_node_by_phandle().    
> > 
> > Labels are an ABI. I can't see that we need to remap them when we can
> > just say the name must be X. We can have multiple labels on a node as
> > well. So I think the problem space is purely mapping 1 name to
> > multiple possible names.  
> 
> So, with a base DT having:
>   /export/ label0: node@0 {
>   }
> 
>   /export/ label1: node@1 {
>   }
> 
> the __symbols__ node will contains:
>   __symbols__ {
> 	label0 = ...;
> 	label1 = ...;
>   }
> 
> without export-symbols, the overlay will look like this:
>   connector: __overlay__ {
> 	...
> 	ref = <&connector>;
>   }
> 
> The "connector" label is the only one we can use from the overlay to
> reference the base DT (special label defined on the __overlay__ node).
> As it is defined to point to __overlay__, it has to be resolved to the
> exported symbol that point to the node where the overlay is applied.
> 
> If the overlay is applied on node@0, 'connector' is resolved to node@0.
> 
> This case cannot be handled:
>    connector: __overlay__ {
> 	...
> 	ref1 = <&connector>;
>         ref2 = <&other-label-from-base-dt>;
>    }
> 
> Indeed, only one 'connector' label can be resolved to node@0 or node@1.
> other-label-from-base-dt cannot be resolved based on the node the overlay
> is applied to.
> 
> Again, I am not sure on my side that we have to handle this case of multiple
> labels in the overlay that point to the base DT dependent on node@0 or node@1.
> 
> On my use case, I considered the node@0 or node@1 as nexus nodes and so, all
> GPIOs (soon PWM, I hope, and probably other ressources in the future) can be
> referenced using nexus nodes.
> 
> > 
> > The connector handling has to be addressed binding by binding at least
> > for each pattern of binding. Pinctrl binding is pretty unique, so we
> > should make sure we can handle it in this case.  
> 
> If pinctrl can be handled using nexus node, it should be ok. Otherwise
> things are going to be complicated. Again, with your proposal, we can
> reference only one label from the overlay, the node where the overlay
> is applied to.
> 
> >   
> > > Last point, having export-symbols node makes some nodes explicitly
> > > candidates for an overlay and defines the label to be used on the base DT
> > > node side. This specific label can be described in the node binding as well
> > > as the nexus node properties.    
> > 
> > Both David (IIRC) and I feel that putting the overlay info
> > (__symbols__, __fixups__, etc.) within the DT data rather than in the
> > DTB format was a mistake. The export-symbols node expands on that, so
> > I'm not sure that's the right direction.
> > 
> > (We should have rev'ed the DTB format to store type information for
> > (at a minimum) phandles.)
> >   
> > > With 'connector: __overlay__', the overlay can be applied on any nodes, at
> > > least from the needed label point of view without any restrictions.    
> > 
> > Certainly that is something I'd like to have some control over. An
> > /export/ tag would accomplish that.
> > 
> > One idea I have there is that the overlay could have the compatible of
> > the connector and we use that for matching. That would give us a way
> > to know what base DTs overlays apply to. Then you could load an
> > overlay and dispatch it to the correct driver to handle. It would have
> > to be handled as a special case as the compatible may match, but
> > wouldn't necessarily be equal values.  
> 
> compatible property will not be enough. We can have two exact same
> connectors on the same base board:
>   /export/ label0: node@0 {
>      compatible = 'foo,addon-connector';
>   }
> 
>   /export/ label1: node@1 {
>      compatible = 'foo,addon-connector';
>   }
> 
> To load the overlay, we can match compatible for sure but we need to node
> the overlay is supposed to be applied to.
> 
> Also, it you want to check bindings for node@0 available in the base DT
> and bindings in the overlay, having one compatible string with different
> meaning will introduce some complexity.
> A compatible string can now define the "provider" part (the base DT) and
> the "consumer" part (the overlay).
> 
> > 
> > 
> > I'll throw out another idea. What if we make resolving phandle errors
> > something that can be handled by the connector driver? The driver
> > knows 'connector' resolves to the connector node it is applying the
> > overlay to.  
> 
> Well, my proposal was to give enough information to the resolver instead of
> handling errors.
> 
> I probably miss something but I don't see what could be the benefit to do
> that in the other way. Can you give me more details about your idea?
> 

If I understand correctly, to move forward on the topic, we are waiting from
feedback from David.

Is that correct or do you have in mind an other plan I could explore?

Best regards,
Hervé

[PATCH 0/7] of: overlay: Add support for export-symbols node feature

[Herve Codina]

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/20240917-hotplug-drm-bridge-v4-0-bc4dfee61be6@bootlin.com/
[3] https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/
[4] https://lore.kernel.org/lkml/20240627-mikrobus-scratch-spi-v5-0-9e6c148bf5f0@beagleboard.org/
[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/20250411-export-symbols-v3-1-f59368d97063@beagleboard.org/
[7] https://lore.kernel.org/all/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/
[8] https://lore.kernel.org/all/20250110-export-symbols-v1-1-b6213fcd6c82@beagleboard.org/

Changes v1 -> v2
  v1: https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/

  - All patches
    Add 'Tested-by: Ayush Singh <ayush@beagleboard.org>'

  - 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

-- 
2.49.0

Re: [PATCH 0/7] of: overlay: Add support for export-symbols node feature

[Herve Codina]

Hi all,

Sorry, this should be a v2 series.

I resend as v2.

Please ighnore this one.

Best regards,
Hervé


On Wed, 30 Apr 2025 14:48:59 +0200
Herve Codina <herve.codina@bootlin.com> wrote:

> 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/20240917-hotplug-drm-bridge-v4-0-bc4dfee61be6@bootlin.com/
> [3] https://lore.kernel.org/lkml/20240702164403.29067-1-afd@ti.com/
> [4] https://lore.kernel.org/lkml/20240627-mikrobus-scratch-spi-v5-0-9e6c148bf5f0@beagleboard.org/
> [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/20250411-export-symbols-v3-1-f59368d97063@beagleboard.org/
> [7] https://lore.kernel.org/all/20250313-fdtoverlay-target-v1-0-dd5924e12bd3@beagleboard.org/
> [8] https://lore.kernel.org/all/20250110-export-symbols-v1-1-b6213fcd6c82@beagleboard.org/
> 
> Changes v1 -> v2
>   v1: https://lore.kernel.org/all/20241209151830.95723-1-herve.codina@bootlin.com/
> 
>   - All patches
>     Add 'Tested-by: Ayush Singh <ayush@beagleboard.org>'
> 
>   - 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
> 



-- 
Hervé Codina, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com