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

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@10", or hexadecimal "cpu@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

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

[David Gibson]

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

On Fri, Apr 03, 2026 at 06:06:17PM +0800, Vivian Wang wrote:
> (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@10", or hexadecimal "cpu@a"? I can't find
> any explicit specification.

It should be hex.  That's a general convention for unit addresses.
Before flattened trees, OF essentially never used decimal
representations of things.

-- 
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 --]

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

[Rob Herring]

On Sat, Apr 4, 2026 at 11:43 PM David Gibson
<david@gibson.dropbear.id.au> wrote:
>
> On Fri, Apr 03, 2026 at 06:06:17PM +0800, Vivian Wang wrote:
> > (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@10", or hexadecimal "cpu@a"? I can't find
> > any explicit specification.
>
> It should be hex.  That's a general convention for unit addresses.
> Before flattened trees, OF essentially never used decimal
> representations of things.

The only decimal usage in FDT were mistakes.

Rather than worrying about what the spec says, please worry about what
the tools check. Unfortunately, this is still only checked for
specific bus types and the default is not checked.

Rob

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

[Vivian Wang]

On 4/6/26 20:48, Rob Herring wrote:
> On Sat, Apr 4, 2026 at 11:43 PM David Gibson
> <david@gibson.dropbear.id.au> wrote:
>> On Fri, Apr 03, 2026 at 06:06:17PM +0800, Vivian Wang wrote:
>>> (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@10", or hexadecimal "cpu@a"? I can't find
>>> any explicit specification.
>> It should be hex.  That's a general convention for unit addresses.
>> Before flattened trees, OF essentially never used decimal
>> representations of things.
> The only decimal usage in FDT were mistakes.

Thanks for this. This is clear enough for me.

> Rather than worrying about what the spec says, please worry about what
> the tools check.

Since, as you two said, there is an established convention, I agree that
convention is enough here.

Thanks,
Vivian "dramforever" Wang

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

[Kyle Bonnici]

> On 6 Apr 2026, at 14:48, Rob Herring <robh@kernel.org> wrote:
> 
> On Sat, Apr 4, 2026 at 11:43 PM David Gibson
> <david@gibson.dropbear.id.au> wrote:
>> 
>> On Fri, Apr 03, 2026 at 06:06:17PM +0800, Vivian Wang wrote:
>>> (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@10", or hexadecimal "cpu@a"? I can't find
>>> any explicit specification.
>> 
>> It should be hex.  That's a general convention for unit addresses.
>> Before flattened trees, OF essentially never used decimal
>> representations of things.

I am also of the understanding that it should be in hex. 
This understanding was developed after looking at the devicetree files in 
Linux kernel and Zephyr project. 

However this is not well defined in the spec. In addition the spec V0.4 has other contradictions
related to the node address. See 
https://github.com/devicetree-org/devicetree-specification/issues/86#issuecomment-4193317641

> 
> The only decimal usage in FDT were mistakes.
> 
> Rather than worrying about what the spec says, please worry about what
> the tools check. Unfortunately, this is still only checked for
> specific bus types and the default is not checked.
> 
> Rob
>