Devicetree spec: Specifying /cpus/cpu@* unit address format?

[Vivian Wang]

(Also posted at: https://github.com/devicetree-org/devicetree-specification/issues/86 )

Hi all,

Presently, there seems to be some confusion in the community about the
format of unit addresses for "/cpus/cpu@*" nodes for a CPU with ID > 9, e.g.

    cpu@??? {
        reg = <10>;
        /* reg = <0xa>; */ /* This should be equivalent */
    }


Should this be a decimal "cpu at 10", or hexadecimal "cpu at a"? I can't find
any explicit specification.

  * Most other nodes specify a hex unit address
  * I could not find anything specifying this generically
      o AFAICT, there's no /cpus in IEEE 1275
      o ePAPR doesn't say anything about this
      o Presently, DTSpec doesn't say anything about this.
  * dt-schema says it's ^cpu@[0-9a-f]+$, seemingly intending to use
    hexadecimal, but not forbidding decimal. [1]
  * Of the `/cpus` schemas in Linux
    (Documentation/devicetree/bindings/{arm,mips,riscv,loongarch}/cpus.yaml),
    none mention the node unit address

As of current usage:

  * Of all the DTS files in (mainline) Linux, most either use hex, or
    have reg < 9 for all CPUs.
      o AFAICT from grepping, arm and arm64 consistently uses hex.
      o Most riscv SoCs have <= 9 CPUs. The two that don't use decimal:
        arch/riscv/boot/dts/sophgo/{sg2042,sg2044}-cpus.dtsi
      o No other arch has in-tree DTS with CPU reg > 9
  * Of all the dt-bindings examples in Linux, only one uses decimal, but
    it seems to be unintentional:
    Documentation/devicetree/bindings/opp/opp-v2.yaml
  * QEMU generates decimal for multiple archs in e.g.
    `hw/{arm,riscv}/virt.c` and other places (grep -R "cpu@")
  * Spike (RISC-V emulator) generates decimal [3]

It could be a good idea to have this standardized, like all other unit
addresses.

DTSpec says:

  The binding for a particular bus may specify additional, more specific
requirements for the format of reg and the unit-address.

Since /cpus and /cpus/cpu@* are generically defined in DTSpec and
specialized for various architectures, I believe this is the right place
to start standardizing this. Even if arch-specific definitions are
required, at least DTSpec can give a recommendation on whether to use
decimal or hexadecimal.

Thanks,
Vivian "dramforever" Wang

[1]: https://github.com/devicetree-org/dt-schema/blob/v2025.12/dtschema/schemas/cpus.yaml#L52-L54
[2]: https://github.com/riscv-software-src/riscv-isa-sim/blob/5eeeb91efa966936ef7b980f5e8dd00ffbe70786/riscv/dts.cc#L61