<commit_before>.. SPDX-License-Identifier: Apache-2.0

.. _chapter-devicetree:

The Devicetree
==============

Overview
--------

|spec| specifies a construct called a *devicetree* to describe
system hardware. A boot program loads a devicetree into a client
program’s memory and passes a pointer to the devicetree to the client.

This chapter describes the logical structure of the devicetree and
specifies a base set of properties for use in describing device nodes.
:numref:`Chapter %s <chapter-device-node-requirements>` specifies certain device nodes
required by a |spec|-compliant
devicetree. :numref:`Chapter %s <chapter-device-bindings>` describes the
|spec|-defined device bindings -- the requirements for representing
certain device types or classes of devices.
:numref:`Chapter %s <chapter-fdt-structure>` describes the in-memory encoding of the devicetree.

A devicetree is a tree data structure with nodes that describe the
devices in a system. Each node has property/value pairs that describe
the characteristics of the device being represented. Each node has
exactly one parent except for the root node, which has no parent.

A |spec|-compliant devicetree describes device information in a system
that cannot necessarily be dynamically detected by a client program. For
example, the architecture of PCI enables a client to probe and detect
attached devices, and thus devicetree nodes describing PCI devices
might not be required. However, a device node is required to describe a
PCI host bridge device in the system if it cannot be detected by
probing.

**Example**

:numref:`example-simple-devicetree` shows an example representation of a
simple devicetree that is nearly
complete enough to boot a simple operating system, with the platform
type, CPU, memory and a single UART described. Device nodes are shown
with properties and values inside each node.

.. _example-simple-devicetree:
.. digraph:: tree
   :caption: Devicetree Example

   rankdir = LR;
   ranksep = equally;
   size = "6,8"
   node [ shape="Mrecord"; width="3.5"; fontname = Courier; ];

   "/" [ label = "\N |
   model=\"fsl,mpc8572ds\"\l
   compatible=\"fsl,mpc8572ds\"\l
   #address-cells=\<1\>\l
   #size-cells=\<1\>\l"]

   "cpus" [ label="\N |
   #address-cells=\<1\>\l
   #size-cells=\<0\>\l"]

   "cpu@0" [ label="\N |
   device_type=\"cpu\"\l
   reg=\<0\>\l
   timebase-frequency=\<825000000\>\l
   clock-frequency=\<825000000\>\l"]

   "cpu@1" [ label="\N |
   device_type=\"cpu\"\l
   reg=\<1\>\l
   timebase-frequency=\<825000000\>\l
   clock-frequency=\<825000000\>\l"]

   "memory@0" [ label="\N |
   device_type=\"memory\"\l
   reg=\<0 0x20000000\>\l"]

   "uart@fe001000" [ label="\N |
   compatible=\"ns16550\"\l
   reg=\<0xfe001000 0x100\>\l"]

   "chosen" [ label="\N |
   bootargs=\"root=/dev/sda2\"\l"]

   "aliases" [ label="\N |
   serial0=\"/uart@fe001000\"\l"]

   "/":e    -> "cpus":w
   "cpus":e -> "cpu@0":w
   "cpus":e -> "cpu@1":w
   "/":e    -> "memory@0":w
   "/":e    -> "uart@fe001000":w
   "/":e    -> "chosen":w
   "/":e    -> "aliases":w

Devicetree Structure and Conventions
------------------------------------

.. _sect-node-names:

Node Names
~~~~~~~~~~

Node Name Requirements
^^^^^^^^^^^^^^^^^^^^^^

Each node in the devicetree is named according to the following
convention:

   ``node-name@unit-address``

The *node-name* component specifies the name of the node. It shall be 1
to 31 characters in length and consist solely of characters from the set
of characters in :numref:`node-name-characters`.

.. tabularcolumns:: | c p{8cm} |
.. _node-name-characters:
.. table:: Valid characters for node names

   ========= ================
   Character Description
   ========= ================
   ``0-9``   digit
   ``a-z``   lowercase letter
   ``A-Z``   uppercase letter
   ``,``     comma
   ``.``     period
   ``_``     underscore
   ``+``     plus sign
   ``-``     dash
   ========= ================

The *node-name* shall start with a lower or uppercase character and
should describe the general class of device.

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 :numref:`node-name-characters`. 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*.

The root node does not have a node-name or unit-address. It is
identified by a forward slash (/).

.. _example-nodenames:
.. digraph:: tree
   :caption: Examples of Node Names

   rankdir = LR;
   ranksep = equally;
   size = "6,8"
   node [ shape="Mrecord"; width="2.5"; fontname = Courier; ];

   "/":e    -> "cpus":w
   "cpus":e -> "cpu@0":w<commit_msg>Add addtional constraint on node name and property names.<commit_after>.. SPDX-License-Identifier: Apache-2.0

.. _chapter-devicetree:

The Devicetree
==============

Overview
--------

|spec| specifies a construct called a *devicetree* to describe
system hardware. A boot program loads a devicetree into a client
program’s memory and passes a pointer to the devicetree to the client.

This chapter describes the logical structure of the devicetree and
specifies a base set of properties for use in describing device nodes.
:numref:`Chapter %s <chapter-device-node-requirements>` specifies certain device nodes
required by a |spec|-compliant
devicetree. :numref:`Chapter %s <chapter-device-bindings>` describes the
|spec|-defined device bindings -- the requirements for representing
certain device types or classes of devices.
:numref:`Chapter %s <chapter-fdt-structure>` describes the in-memory encoding of the devicetree.

A devicetree is a tree data structure with nodes that describe the
devices in a system. Each node has property/value pairs that describe
the characteristics of the device being represented. Each node has
exactly one parent except for the root node, which has no parent.

A |spec|-compliant devicetree describes device information in a system
that cannot necessarily be dynamically detected by a client program. For
example, the architecture of PCI enables a client to probe and detect
attached devices, and thus devicetree nodes describing PCI devices
might not be required. However, a device node is required to describe a
PCI host bridge device in the system if it cannot be detected by
probing.

**Example**

:numref:`example-simple-devicetree` shows an example representation of a
simple devicetree that is nearly
complete enough to boot a simple operating system, with the platform
type, CPU, memory and a single UART described. Device nodes are shown
with properties and values inside each node.

.. _example-simple-devicetree:
.. digraph:: tree
   :caption: Devicetree Example

   rankdir = LR;
   ranksep = equally;
   size = "6,8"
   node [ shape="Mrecord"; width="3.5"; fontname = Courier; ];

   "/" [ label = "\N |
   model=\"fsl,mpc8572ds\"\l
   compatible=\"fsl,mpc8572ds\"\l
   #address-cells=\<1\>\l
   #size-cells=\<1\>\l"]

   "cpus" [ label="\N |
   #address-cells=\<1\>\l
   #size-cells=\<0\>\l"]

   "cpu@0" [ label="\N |
   device_type=\"cpu\"\l
   reg=\<0\>\l
   timebase-frequency=\<825000000\>\l
   clock-frequency=\<825000000\>\l"]

   "cpu@1" [ label="\N |
   device_type=\"cpu\"\l
   reg=\<1\>\l
   timebase-frequency=\<825000000\>\l
   clock-frequency=\<825000000\>\l"]

   "memory@0" [ label="\N |
   device_type=\"memory\"\l
   reg=\<0 0x20000000\>\l"]

   "uart@fe001000" [ label="\N |
   compatible=\"ns16550\"\l
   reg=\<0xfe001000 0x100\>\l"]

   "chosen" [ label="\N |
   bootargs=\"root=/dev/sda2\"\l"]

   "aliases" [ label="\N |
   serial0=\"/uart@fe001000\"\l"]

   "/":e    -> "cpus":w
   "cpus":e -> "cpu@0":w
   "cpus":e -> "cpu@1":w
   "/":e    -> "memory@0":w
   "/":e    -> "uart@fe001000":w
   "/":e    -> "chosen":w
   "/":e    -> "aliases":w

Devicetree Structure and Conventions
------------------------------------

.. _sect-node-names:

Node Names
~~~~~~~~~~

Node Name Requirements
^^^^^^^^^^^^^^^^^^^^^^

Each node in the devicetree is named according to the following
convention:

   ``node-name@unit-address``

The *node-name* component specifies the name of the node. It shall be 1
to 31 characters in length and consist solely of characters from the set
of characters in :numref:`node-name-characters`.

.. tabularcolumns:: | c p{8cm} |
.. _node-name-characters:
.. table:: Valid characters for node names

   ========= ================
   Character Description
   ========= ================
   ``0-9``   digit
   ``a-z``   lowercase letter
   ``A-Z``   uppercase letter
   ``,``     comma
   ``.``     period
   ``_``     underscore
   ``+``     plus sign
   ``-``     dash
   ========= ================

The *node-name* shall start with a lower or uppercase character and
should describe the general class of device.

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 :numref:`node-name-characters`. 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*.

In the case of *node-name* without an *@unit-address* the *node-name* shall
be unique from any property names at the same level in the tree.

The root node does not have a node-name or unit-address. It is
identified by a forward slash (/).

.. _example-nodenames:
.. digraph:: tree
   :caption: Examples of Node Names

   rankdir = LR;
   ranksep = equally;
   size = "6,8"
   node [ shape="Mrecord"; width="2.5"; fontname = Courier; ];

   "/":e    -> "cpus":w
   "cpus":e -> "cpu@0":w
{'fraction_non_alphanumeric': 0.1474056603773585, 'fraction_numerical': 0.023388364779874212, 'mean_word_length': 3.465555068012286, 'pattern_counts': {'":': 36, '<': 33, '<?xml version=': 0, '>': 51, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5661155', 'n_tokens_mistral': 3342, 'n_tokens_neox': 3079, 'n_words': 1155}