Re: Phandles

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 6263 bytes --]

On Sun, Apr 12, 2026 at 01:51:35PM +0000, Kyle Bonnici wrote:
> 
> 
> > On 12 Apr 2026, at 14:51, Herve Codina <herve.codina@bootlin.com> wrote:
> > 
> > Hi Kyle,
> > 
> > On Sat, 11 Apr 2026 18:33:33 +0000
> > Kyle Bonnici <kylebonnici@hotmail.com> wrote:
> > 
> >> Hi
> >> 
> >> I have been looking at the the code for the compiler and I am wondering which specifications marks the below properties MUST BE Nexus Properties hence the validation.
> >> 
> >> WARNING_PROPERTY_PHANDLE_CELLS(clocks, "clocks", "#clock-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(cooling_device, "cooling-device", "#cooling-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(dmas, "dmas", "#dma-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(hwlocks, "hwlocks", "#hwlock-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(interrupts_extended, "interrupts-extended", "#interrupt-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(io_channels, "io-channels", "#io-channel-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(iommus, "iommus", "#iommu-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(mboxes, "mboxes", "#mbox-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(msi_parent, "msi-parent", "#msi-cells", true);
> >> WARNING_PROPERTY_PHANDLE_CELLS(mux_controls, "mux-controls", "#mux-control-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(phys, "phys", "#phy-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(power_domains, "power-domains", "#power-domain-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(pwms, "pwms", "#pwm-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(resets, "resets", "#reset-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(sound_dai, "sound-dai", "#sound-dai-cells");
> >> WARNING_PROPERTY_PHANDLE_CELLS(thermal_sensors, "thermal-sensors", "#thermal-sensor-cells");
> > 
> > All of those properties are defined as phandles.
> > 
> > For instance, the 'pwms' property available in a node means the the node is
> > a pwm consumer. It must follow the pwm consumer binding [1] and so a phandle
> > is involved.
> > 
> > This phandle can have arguments and the number of argument is defined by the
> > #pwm-cells property set in the pwm provider node [2], [3].
> > 
> > [1] https://elixir.bootlin.com/zephyr/v4.4.0-rc3/source/dts/bindings/pwm/pwm-controller.yaml
> > [2] https://github.com/zephyrproject-rtos/zephyr/blob/main/dts/bindings/pwm/pwm-controller.yaml
> > [3] https://elixir.bootlin.com/linux/v7.0-rc7/source/Documentation/devicetree/bindings/pwm/pwm.yaml
> > 
> >> 
> >> 
> >> These can be found here: https://github.com/dgibson/dtc/blob/main/checks.c#L1498 this is relevant for https://github.com/zephyrproject-rtos/zephyr/issues/107066
> > 
> > Examples provided in the zephyrproject issue link are, in my opinion, incorrect.
> > 
> >  Case 1:
> >  / {
> >      node1 {
> >           pwms = <1 &pwm0 1 20 PWM_POLARITY_NORMAL>;
> > 
> >           Here the first cell '1' is not a phandle.
> 
> Here the compiler is making an assumption here that all `pwms`
> properties must be specifier properties and all use `pwm` specifier.
> 
> This is not the case in zephyr. Any property that is a specifier
> property must implement a binding and follow these rules
> https://docs.zephyrproject.org/latest/build/dts/bindings-syntax.html#specifier-space
> and validation is the responsibility go Zephyr's build system.

I'm not quite sure what you're saying here.  Are you saying that
Zephyr is using the same property name as an existing binding, but in
a different way from that binding?

That's a terrible idea, whether or not it's technically against any
spec,

Also, Zephyr shouldn't be making choices about how the device tree is
encoded.  The device tree describes *hardware* (real or virtual) not
how the hardware is used by a particular OS.

> The same applies for all the other examples I have here
> https://github.com/zephyrproject-rtos/zephyr/issues/107066
> 
> Given that these nodes do not implement any binding then no type should be inferred.
> 
> In addition AFAIK the devicetree specification does not say anything
> about these specific property names (unlike `interrupts` and
> `interrupts-extended)`
> 
> Hence it is my option that the compiler should be agnostic of the
> binding system used and not make any assumptions about bindings
> used.
> 
> > 
> >      };
> > 
> >      node2 {
> >          pwms = <&pwm0 1 20>;
> > 
> >          Here 2 arguments. The node referenced by &pwm0 must indicated the
> >          number of argument to provide. I.e it must have a #pwm-cells$
> >          property set.
> > 
> >          According to your example, this property must be #pwm-cells= <2>;
> > 
> > 
> >      };
> > 
> >      node3 {
> >          pwms = <1 &pwm0 1 20 PWM_POLARITY_NORMAL>;
> > 
> >          Here also, '1', the first cell, is not a phandle.
> >      };
> >  };
> > 
> >  Case 2:
> > 
> >  / {
> >      foobar {
> >          pwms = <1 2 3 4 5>;
> > 
> >          Random values. Error detected by DTC.
> > 
> >      };
> >  };
> > 
> >  Case 3:
> > 
> >  / {
> >      zephyr,user {
> >          pwms = <1  20 1>;
> 
> This is yet another example see where zephyr want to allow any inference based on the value and not the property name.
> see https://github.com/zephyrproject-rtos/zephyr/pull/107127 (https://docs.zephyrproject.org/latest/build/dts/zephyr-user-node.html) 
> 
> i.e .          
> pwms = ‘foobar”; // should be a string
> pwms = <10>; // should be a number or U32
> And so on.
> 
> 
> > 
> >          Here also the phandle is missing.
> >      };
> >  };
> > 
> > 
> > If you want to use Nexus node on top of that, you can have a look at the
> > following example:
> >  https://elixir.bootlin.com/linux/v7.0-rc7/source/Documentation/devicetree/bindings/pwm/pwm-nexus-node.yaml
> > 
> > In the example, you will find the consumer, the nexus node and the pwm
> > providers.
> > 
> > Not sure to have fully understood your issue but I hope my comments help.
> > 
> > Best regards,
> > Hervé
> 
> 

-- 
David Gibson (he or they)	| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you, not the other way
				| around.
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]