3. Device Node Requirements¶
3.1. Base Device Node Types¶
The sections that follow specify the requirements for the base set of device nodes required in a DTSpec-compliant devicetree.
All devicetrees shall have a root node and the following nodes shall be present at the root of all devicetrees:
One
/cpus
nodeAt least one
/memory
node
3.2. Root node¶
The devicetree has a single root node of which all other device nodes
are descendants. The full path to the root node is /
.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
Specifies the number of |
|
R |
|
Specifies the number of |
|
R |
|
Specifies a string that uniquely identifies the model of the system board. The recommended format is “manufacturer,model-number”. |
|
R |
|
Specifies a list of platform architectures with which this platform is compatible. This property can be used by operating systems in selecting platform specific code. The recommended form of the property value is:
For example:
|
|
O |
|
Specifies a string representing the device’s serial number. |
|
OR |
|
Specifies a string that identifies the form-factor of the system. The property value can be one of:
|
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
3.3. /aliases
node¶
A devicetree may have an aliases node (/aliases
) that defines one or
more alias properties. The alias node shall be at the root of the devicetree
and have the node name /aliases
.
Each property of the /aliases
node defines an alias. The property name
specifies the alias name. The property value specifies the full path to
a node in the devicetree. For example, the property serial0 =
"/simple-bus@fe000000/serial@llc500"
defines the alias serial0
.
Alias names shall be a lowercase text strings of 1 to 31 characters from the following set of characters.
Character |
Description |
---|---|
0-9 |
digit |
a-z |
lowercase letter |
- |
dash |
An alias value is a device path and is encoded as a string. The value represents the full path to a node, but the path does not need to refer to a leaf node.
A client program may use an alias property name to refer to a full device path as all or part of its string value. A client program, when considering a string as a device path, shall detect and use the alias.
Example
aliases {
serial0 = "/simple-bus@fe000000/serial@llc500";
ethernet0 = "/simple-bus@fe000000/ethernet@31c000";
};
Given the alias serial0
, a client program can look at the /aliases
node
and determine the alias refers to the device path
/simple-bus@fe000000/serial@llc500
.
3.4. /memory
node¶
A memory device node is required for all devicetrees and describes the physical memory layout for the system. If a system has multiple ranges of memory, multiple memory nodes can be created, or the ranges can be specified in the reg property of a single memory node.
The unit-name component of the node name
(see Section 2.2.1)
shall be memory
.
The client program may access memory not covered by any memory reservations (see Section 5.3) using any storage attributes it chooses. However, before changing the storage attributes used to access a real page, the client program is responsible for performing actions required by the architecture and implementation, possibly including flushing the real page from the caches. The boot program is responsible for ensuring that, without taking any action associated with a change in storage attributes, the client program can safely access all memory (including memory covered by memory reservations) as WIMG = 0b001x. That is:
not Write Through Required
not Caching Inhibited
Memory Coherence
Required either not Guarded or Guarded
If the VLE storage attribute is supported, with VLE=0.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
Value shall be “memory” |
|
R |
|
Consists of an arbitrary number of address and size pairs that specify the physical address and size of the memory ranges. |
|
O |
|
Specifies the address and size of the Initial Mapped Area Is a prop-encoded-array consisting of a
triplet of (effective address, physical
address, size). The effective and physical
address shall each be 64-bit ( |
|
O |
|
Specifies an explicit hint to the operating system that this memory may potentially be removed later. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
3.4.1. /memory
node and UEFI¶
When booting via [UEFI], the system memory map is obtained via the
GetMemoryMap() UEFI boot time service as defined in [UEFI] § 7.2,
and if present, the OS must ignore any /memory
nodes.
3.4.2. /memory
Examples¶
Given a 64-bit Power system with the following physical memory layout:
RAM: starting address 0x0, length 0x80000000 (2 GB)
RAM: starting address 0x100000000, length 0x100000000 (4 GB)
Memory nodes could be defined as follows, assuming #address-cells = <2>
and #size-cells = <2>
.
Example #1
memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000
0x000000001 0x00000000 0x00000001 0x00000000>;
};
Example #2
memory@0 {
device_type = "memory";
reg = <0x000000000 0x00000000 0x00000000 0x80000000>;
};
memory@100000000 {
device_type = "memory";
reg = <0x000000001 0x00000000 0x00000001 0x00000000>;
};
The reg
property is used to define the address and size of the two
memory ranges. The 2 GB I/O region is skipped. Note that the
#address-cells
and #size-cells
properties of the root node specify a
value of 2, which means that two 32-bit cells are required to define the
address and length for the reg
property of the memory node.
3.5. /reserved-memory
Node¶
Reserved memory is specified as a node under the /reserved-memory
node.
The operating system shall exclude reserved memory from normal usage.
One can create child nodes describing particular reserved (excluded from
normal use) memory regions.
Such memory regions are usually designed for the special usage by various
device drivers.
Parameters for each memory region can be encoded into the device tree with the following nodes:
3.5.1. /reserved-memory parent node¶
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
Specifies the number of |
|
R |
|
Specifies the number of |
|
R |
|
This property represents the mapping between parent address to child address spaces (see Section 2.3.8, ranges). |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
#address-cells
and #size-cells
should use the same values as for the root node,
and ranges
should be empty so that address translation logic works correctly.
3.5.2. /reserved-memory/ child nodes¶
Each child of the reserved-memory node specifies one or more regions of
reserved memory. Each child node may either use a reg
property to
specify a specific range of reserved memory, or a size
property with
optional constraints to request a dynamically allocated block of memory.
Following the generic-names recommended practice, node names should
reflect the purpose of the node (ie. “framebuffer” or “dma-pool”).
Unit address (@<address>
) should be appended to the name if the node
is a static allocation.
A reserved memory node requires either a reg
property for static
allocations, or a size
property for dynamics allocations.
Dynamic allocations may use alignment
and alloc-ranges
properties
to constrain where the memory is allocated from.
If both reg
and size
are present, then the region is treated as a
static allocation with the reg
property taking precedence and size
is ignored.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
Consists of an arbitrary number of address and size pairs that specify the physical address and size of the memory ranges. |
|
O |
|
Size in bytes of memory to reserve for
dynamically allocated regions.
Size of this property is based on parent node’s
|
|
O |
|
Address boundary for alignment of allocation.
Size of this property is based on parent node’s
|
|
O |
|
Specifies regions of memory that are acceptable
to allocate from.
Format is (address, length pairs) tuples in
same format as for |
|
O |
|
May contain the following strings:
|
|
O |
|
If present, indicates the operating system must not create a virtual mapping of the region as part of its standard mapping of system memory, nor permit speculative access to it under any circumstances other than under the control of the device driver using the region. |
|
O |
|
The operating system can use the memory in this region with the limitation that the device driver(s) owning the region need to be able to reclaim it back. Typically that means that the operating system can use that region to store volatile or cached data that can be otherwise regenerated or migrated elsewhere. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
The no-map
and reusable
properties are mutually exclusive and both must
not be used together in the same node.
Linux implementation notes:
If a
linux,cma-default
property is present, then Linux will use the region for the default pool of the contiguous memory allocator.If a
linux,dma-default
property is present, then Linux will use the region for the default pool of the consistent DMA allocator.
3.5.3. Device node references to reserved memory¶
Regions in the /reserved-memory
node may be referenced by other device
nodes by adding a memory-region
property to the device node.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
phandle, specifier pairs to children of
|
|
O |
|
A list of names, one for each corresponding
entry in the |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
3.5.4. /reserved-memory
and UEFI¶
When booting via [UEFI], static /reserved-memory
regions must
also be listed in the system memory map obtained via the GetMemoryMap()
UEFI boot time service as defined in [UEFI] § 7.2.
The reserved memory regions need to be included in the UEFI memory map to
protect against allocations by UEFI applications.
Reserved regions with the no-map
property must be listed in the memory
map with type EfiReservedMemoryType
.
All other reserved regions must be listed with type EfiBootServicesData
.
Dynamic reserved memory regions must not be listed in the [UEFI] memory map because they are allocated by the OS after exiting firmware boot services.
3.5.5. /reserved-memory
Example¶
This example defines 3 contiguous regions are defined for Linux kernel:
one default of all device drivers (named linux,cma
and 64MiB in size),
one dedicated to the framebuffer device (named framebuffer@78000000
, 8MiB), and
one for multimedia processing (named multimedia@77000000
, 64MiB).
/ {
#address-cells = <1>;
#size-cells = <1>;
memory {
reg = <0x40000000 0x40000000>;
};
reserved-memory {
#address-cells = <1>;
#size-cells = <1>;
ranges;
/* global autoconfigured region for contiguous allocations */
linux,cma {
compatible = "shared-dma-pool";
reusable;
size = <0x4000000>;
alignment = <0x2000>;
linux,cma-default;
};
display_reserved: framebuffer@78000000 {
reg = <0x78000000 0x800000>;
};
multimedia_reserved: multimedia@77000000 {
compatible = "acme,multimedia-memory";
reg = <0x77000000 0x4000000>;
};
};
/* ... */
fb0: video@12300000 {
memory-region = <&display_reserved>;
/* ... */
};
scaler: scaler@12500000 {
memory-region = <&multimedia_reserved>;
/* ... */
};
codec: codec@12600000 {
memory-region = <&multimedia_reserved>;
/* ... */
};
};
3.6. /chosen
Node¶
The /chosen
node does not represent a real device in the system but
describes parameters chosen or specified by the system firmware at run
time. It shall be a child of the root node.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O |
|
A string that specifies the boot arguments for the client program. The value could potentially be a null string if no boot arguments are required. |
|
O |
|
A string that specifies the full path to the node representing the device to be used for boot console output. If the character “:” is present in the value it terminates the path. The value may be an alias. If the stdin-path property is not specified, stdout-path should be assumed to define the input device. |
|
O |
|
A string that specifies the full path to the node representing the device to be used for boot console input. If the character “:” is present in the value it terminates the path. The value may be an alias. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
Example
chosen {
bootargs = "root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200";
};
Older versions of devicetrees may be encountered that contain a deprecated form of the stdout-path property called linux,stdout-path. For compatibility, a client program might want to support linux,stdout-path if a stdout-path property is not present. The meaning and use of the two properties is identical.
3.7. /cpus
Node Properties¶
A /cpus
node is required for all devicetrees. It does not represent a
real device in the system, but acts as a container for child cpu
nodes
which represent the systems CPUs.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R |
|
The value specifies how many cells each
element of the |
|
R |
|
Value shall be 0. Specifies that no size is
required in the |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
The /cpus
node may contain properties that are common across cpu
nodes.
See Section 3.8 for details.
For an example, see Section 3.8.4.
3.8. /cpus/cpu*
Node Properties¶
A cpu
node represents a hardware execution block that is sufficiently
independent that it is capable of running an operating system without
interfering with other CPUs possibly running other operating systems.
Hardware threads that share an MMU would generally be represented under
one cpu
node. If other more complex CPU topographies are designed, the
binding for the CPU must describe the topography (e.g. threads that
don’t share an MMU).
CPUs and threads are numbered through a unified number-space that should match as closely as possible the interrupt controller’s numbering of CPUs/threads.
Properties that have identical values across cpu
nodes may be placed in
the /cpus
node instead. A client program must first examine a specific
cpu
node, but if an expected property is not found then it should look
at the parent /cpus
node. This results in a less verbose representation
of properties which are identical across all CPUs.
The node name for every CPU node should be cpu
.
3.8.1. General Properties of /cpus/cpu*
nodes¶
The following table describes the general properties of cpu
nodes. Some
of the properties described in Table 3.9 are select
standard properties with specific applicable detail.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
R
|
<string> |
Value shall be |
|
R |
array |
The value of reg is a If a CPU supports more than one thread (i.e.
multiple streams of execution) the reg
property is an array with 1 element per
thread. The #address-cells on the If a CPU/thread can be the target of an external interrupt the reg property value must be a unique CPU/thread id that is addressable by the interrupt controller. If a CPU/thread cannot be the target of an external interrupt, then reg must be unique and out of bounds of the range addressed by the interrupt controller If a CPU/thread’s PIR (pending interrupt register) is modifiable, a client program should modify PIR to match the reg property value. If PIR cannot be modified and the PIR value is distinct from the interrupt controller number space, the CPUs binding may define a binding-specific representation of PIR values if desired. |
|
O
|
array
|
Specifies the clock speed of the CPU in Hertz,
if that is constant. The value is a
|
|
O
|
array
|
Specifies the current frequency at which the timebase and decrementer registers are updated (in Hertz). The value is a <prop-encoded-array> in one of two forms:
|
|
SD |
|
A standard property describing the state of a
CPU. This property shall be present for nodes
representing CPUs in a symmetric
multiprocessing (SMP) configuration. For a CPU
node the meaning of the
A quiescent CPU is in a state where it cannot interfere with the normal operation of other CPUs, nor can its state be affected by the normal operation of other running CPUs, except by an explicit method for enabling or re-enabling the quiescent CPU (see the enable-method property). In particular, a running CPU shall be able to issue broadcast TLB invalidates without affecting a quiescent CPU. Examples: A quiescent CPU could be in a spin loop, held in reset, and electrically isolated from the system bus or in another implementation dependent state. A CPU with |
|
SD
|
<stringlist> |
Describes the method by which a CPU in a
disabled state is enabled. This property is
required for CPUs with a status property with
a value of
Example: Note Other methods may be added to later revisions of the DTSpec specification. |
|
SD
|
<u64> |
The cpu-release-addr property is required for
cpu nodes that have an enable-method property
value of |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
O
|
<string> |
A string that specifies the numerical portion
of the Power ISA version string. For example,
for an implementation complying with Power ISA
Version 2.06, the value of this property would
be |
|
O
|
<empty> |
If the For example, if the power-isa-version property
exists and its value is |
|
SD
|
<u32> |
Specifies the block size in bytes upon which cache block instructions operate (e.g., dcbz). Required if different than the L1 cache block size. |
|
SD
|
<u32> |
Specifies the reservation granule size supported by this processor in bytes. |
|
O |
|
Specifies the CPU’s MMU type. Valid values are shown below:
|
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
Older versions of devicetree may be encountered that contain a bus-frequency property on CPU nodes. For compatibility, a client-program might want to support bus-frequency. The format of the value is identical to that of clock-frequency. The recommended practice is to represent the frequency of a bus on the bus node using a clock-frequency property.
3.8.2. TLB Properties¶
The following properties of a cpu node describe the translate look-aside buffer in the processor’s MMU.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
SD |
|
If present specifies that the TLB has a split configuration, with separate TLBs for instructions and data. If absent, specifies that the TLB has a unified configuration. Required for a CPU with a TLB in a split configuration. |
|
SD |
|
Specifies the number of entries in the TLB. Required for a CPU with a unified TLB for instruction and data addresses. |
|
SD |
|
Specifies the number of associativity sets in the TLB. Required for a CPU with a unified TLB for instruction and data addresses. |
|
SD |
|
Specifies the number of entries in the data TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of associativity sets in the data TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of entries in the instruction TLB. Required for a CPU with a split TLB configuration. |
|
SD |
|
Specifies the number of associativity sets in the instruction TLB. Required for a CPU with a split TLB configuration. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
3.8.3. Internal (L1) Cache Properties¶
The following properties of a cpu node describe the processor’s internal (L1) cache.
Property Name |
Usage |
Value Type |
Definition |
---|---|---|---|
|
SD |
|
If present, specifies the cache has a unified organization. If not present, specifies that the cache has a Harvard architecture with separate caches for instructions and data. |
|
SD |
|
Specifies the size in bytes of a unified cache. Required if the cache is unified (combined instructions and data). |
|
SD |
|
Specifies the number of associativity sets in a unified cache. Required if the cache is unified (combined instructions and data) |
|
SD |
|
Specifies the block size in bytes of a unified cache. Required if the processor has a unified cache (combined instructions and data) |
|
SD |
|
Specifies the line size in bytes of a unified cache, if different than the cache block size Required if the processor has a unified cache (combined instructions and data). |
|
SD |
|
Specifies the size in bytes of the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the number of associativity sets in the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the block size in bytes of the instruction cache. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the line size in bytes of the instruction cache, if different than the cache block size. Required if the cpu has a separate cache for instructions. |
|
SD |
|
Specifies the size in bytes of the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the number of associativity sets in the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the block size in bytes of the data cache. Required if the cpu has a separate cache for data. |
|
SD |
|
Specifies the line size in bytes of the data cache, if different than the cache block size. Required if the cpu has a separate cache for data. |
|
SD |
|
If present, indicates that another level of cache exists. The value is the phandle of the next level of cache. The phandle value type is fully described in Section 2.3.3. |
Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition |
Note
All other standard properties (Section 2.3) are allowed but are optional.
Older versions of devicetrees may be encountered that contain a
deprecated form of the next-level-cache property called l2-cache
.
For compatibility, a client-program may wish to support l2-cache
if a next-level-cache property is not present.
The meaning and use of the two properties is identical.
3.8.4. Example¶
Here is an example of a /cpus
node with one child cpu node:
cpus {
#address-cells = <1>;
#size-cells = <0>;
cpu@0 {
device_type = "cpu";
reg = <0>;
d-cache-block-size = <32>; // L1 - 32 bytes
i-cache-block-size = <32>; // L1 - 32 bytes
d-cache-size = <0x8000>; // L1, 32K
i-cache-size = <0x8000>; // L1, 32K
timebase-frequency = <82500000>; // 82.5 MHz
clock-frequency = <825000000>; // 825 MHz
};
};