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

[Herve Codina <herve.codina@bootlin.com>]

On Mon, 9 Dec 2024 10:47:50 -0600
Andrew Davis <afd@ti.com> wrote:

> On 12/9/24 9:18 AM, Herve Codina 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.
> >   
> 
> I might be missing something, but how is the correct connector (connector1
> or connector2) selected? Let's say I connect my addon board to connector2,
> then I apply the addon board's overlay to the base DTB. What connector
> just got referenced?
> 

A driver for the connector is needed.
The driver applies the overlay using of_overlay_fdt_apply().
The node the overlay has to be applied to is passed by the driver to
of_overlay_fdt_apply().

Even if obsolete because I added one more parameter (export_symbols_name)
in of_overlay_fdt_apply() in this current series, you can have a look at the
following patch to see the connector driver:
  https://lore.kernel.org/lkml/20240917-hotplug-drm-bridge-v4-8-bc4dfee61be6@bootlin.com/

Best regards,
Hervé

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