Specify /cpus/cpu@* unit address format

[dramforever]

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
  • AFAICT, there's no /cpus in IEEE 1275
  • ePAPR doesn't say anything about this
  • 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. https://github.com/devicetree-org/dt-schema/blob/v2025.12/dtschema/schemas/cpus.yaml#L52-L54
• Of the /cpus schemas in Linux (Documentation/devicetree/bindings/{arm,mips,riscv,loongarch}/cpus.yaml), none mention the node unit address. https://github.com/torvalds/linux/blob/v7.0-rc1/Documentation/devicetree/bindings/arm/cpus.yaml

As of current usage:

• Of all the DTS files in (mainline) Linux, most either use hex, or have reg < 9 for all CPUs.
  • AFAICT from grepping, arm and arm64 consistently uses hex.
  • Most riscv SoCs have <= 9 CPUs. The two that don't use decimal: arch/riscv/boot/dts/sophgo/{sg2042,sg2044}-cpus.dtsi https://github.com/torvalds/linux/blob/v7.0-rc1/arch/riscv/boot/dts/sophgo/sg2042-cpus.dts
  • 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 https://github.com/torvalds/linux/blob/v7.0-rc1/Documentation/devicetree/bindings/opp/opp-v2.yaml#L194-L215
• QEMU generates decimal for multiple archs: https://github.com/search?q=repo%3Aqemu%2Fqemu%20%2Fcpu%40%25%2F&type=code
• Spike (RISC-V emulator) generates decimal: https://github.com/riscv-software-src/riscv-isa-sim/blob/5eeeb91efa966936ef7b980f5e8dd00ffbe70786/riscv/dts.cc#L61

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.

[dramforever]

At the suggestion from a colleague, I have also posted substantially the same thing as an email to the devicetree-spec mailing list: https://lore.kernel.org/devicetree-spec/00ddad5a-02f5-474e-af9c-11ce7716ddfc@iscas.ac.cn/

[kylebonnici]

There is also another contradiction IMO in the spec

https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#node-name-requirements

The unit-address component of the name is specific to the bus type on which the node sits. It consists of one or more ASCII characters from the set of characters in Table 2.1. The unit-address must match the first address specified in the reg property of the node. If the node has no reg property, the @unit-address must be omitted and the node-name alone differentiates the node from other nodes at the same level in the tree. The binding for a particular bus may specify additional, more specific requirements for the format of reg and the unit-address.

Important to focus on

The unit-address must match the first address specified in the reg property of the node.

In the spec reg property is of type (https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#reg)

The value is a , composed of an arbitrary number of pairs of address and length,

. The number of cells required to specify the address and length are bus-specific and are specified by the #address-cells and #size-cells properties in the parent of the device node. If the parent node specifies a value of 0 for #size-cells, the length field in the value of reg shall be omitted.

By this definition:

• g-z, G-Z cannot be used to describe a U32 in hex.
• + is implicit as U32 cannot be negative
• 'period' cannot be used in U32 value
• 'dash' cannot be used in U32 value

I have seen cases where underscore has been used to make values more readable e.g. 1_000_000
I have seen cases where comma is used to split the address cells e.g.

given #address-cells = <3>; and reg = <0x10 0x20 0x30...>. Node name could be node@10,20 or node@100000002000000030

Where the above is intended to be used like this or not is also very ambiguous the spec does not help with this.

It is my opinion to Improve the spec to make sure above cases are well defined.

[robherring]

@kylebonnici Ultimately, it is each bus definition that defines the exact format of the unit-address. And it is up to schemas and/or dtc to check those (schemas can check format, but not matching 'reg'. dtc does that (for some bus types)).

If you want spec improvements, submit patches. Otherwise, no one is actively working on the spec.

[dramforever]

Where the above is intended to be used like this or not is also very ambiguous the spec does not help with this.

The generic spec is intentionally ambiguous in this.

For an example of a bus where this is specified, see the PCI bindings https://www.devicetree.org/open-firmware/bindings/pci/pci1_6d.pdf section 2.2.1.3, where PCI devices should look like e.g. iommu@1,0, meaning device 1, function 0.

[kylebonnici]

@dramforever but still there is a contradiction in the spec

The unit-address must match the first address specified in the reg property of the node.

and when one looks at pci-iommu.yaml

            iommu0: iommu@1,0 {
                compatible = "pci1af4,1057";
                reg = <0x800 0 0 0 0>;
                #iommu-cells = <1>;
            };

The above is in clear violation of this MUST from the spec!

[robherring]

@kylebonnici Probably it should say 'use' not 'match' to be clearer. It correctly uses the first address in 'reg' to construct the unit-address. The format of the unit address is not defined in the spec (but rather the PCI bus supplement referenced above).

[kylebonnici]

I am not sure I follow

It correctly uses the first address in 'reg' to construct the unit-address.

in the case of https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/marvell/armada-xp-mv78230.dtsi#L164, parent defined #address-cells = <3> hence 0x2000 0 0 are the address cells and I do not see how "the first address in 'reg' to construct the unit-address" 4,0

pcie4: pcie@4,0 {
    device_type = "pci";
    assigned-addresses = <0x82002000 0  0x4c000 0 0x2000 >;
    reg = <0x2000 0 0 0 0 >;
....
...

In the linux devicetree files I have found at least 3 variant of the , syntax all with different meaning.

• https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/arm/arm-realview-pb11mp.dts#L279 value after then , is used to have unique node name
• https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/nxp/imx/imx27-eukrea-cpuimx27.dtsi#L103 follow what I have observed "I have seen cases where comma is used to split the address cells e.g."
• https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/marvell/armada-xp-mv78230.dtsi#L164 as discussed above

[robherring]

I am not sure I follow

It correctly uses the first address in 'reg' to construct the unit-address.

in the case of https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/marvell/armada-xp-mv78230.dtsi#L164, parent defined #address-cells = <3> hence 0x2000 0 0 are the address cells and I do not see how "the first address in 'reg' to construct the unit-address" 4,0

pcie4: pcie@4,0 {
    device_type = "pci";
    assigned-addresses = <0x82002000 0  0x4c000 0 0x2000 >;
    reg = <0x2000 0 0 0 0 >;
....
...

Read the PCI bus supplement. 4 is the device number which is bits 15:11 and 0 is the function number which is bits 10:8 both from the first cell of the address in 'reg'.

In the linux devicetree files I have found at least 3 variant of the , syntax all with different meaning.

* https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/arm/arm-realview-pb11mp.dts#L279 value after then , is used to have unique node name

That's a special case used to include the bit offset.

* https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/nxp/imx/imx27-eukrea-cpuimx27.dtsi#L103 follow what I have observed  "I have seen cases where comma is used to split the address cells e.g."

That's for a parallel memory bus with chip select lines. The first number is the chip select and the 2nd number is the offset.

* https://github.com/torvalds/linux/blob/master/arch/arm/boot/dts/marvell/armada-xp-mv78230.dtsi#L164  as discussed above

As explained, standard PCI addressing. The PCI bus supplement goes thru all of that including forms we don't really use any more.