Re: Phandles

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

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.

      };

      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>;
    
          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é