Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Node identifiers and helpers

Macros

#define DT_INVALID_NODE   _
 Name for an invalid node identifier.
 
#define DT_ROOT   DT_N
 Node identifier for the root node in the devicetree.
 
#define DT_PATH(...)
 Get a node identifier for a devicetree path.
 
#define DT_NODELABEL(label)
 Get a node identifier for a node label.
 
#define DT_ALIAS(alias)
 Get a node identifier from /aliases.
 
#define DT_INST(inst, compat)
 Get a node identifier for an instance of a compatible.
 
#define DT_PARENT(node_id)
 Get a node identifier for a parent node.
 
#define DT_GPARENT(node_id)
 Get a node identifier for a grandparent node.
 
#define DT_CHILD(node_id, child)
 Get a node identifier for a child node.
 
#define DT_COMPAT_GET_ANY_STATUS_OKAY(compat)
 Get a node identifier for a status okay node with a compatible.
 
#define DT_NODE_PATH(node_id)
 Get a devicetree node's full path as a string literal.
 
#define DT_NODE_FULL_NAME(node_id)
 Get a devicetree node's name with unit-address as a string literal.
 
#define DT_NODE_FULL_NAME_UNQUOTED(node_id)
 Get the node's full name, including the unit-address, as an unquoted sequence of tokens.
 
#define DT_NODE_FULL_NAME_TOKEN(node_id)
 Get the node's full name, including the unit-address, as a token.
 
#define DT_NODE_FULL_NAME_UPPER_TOKEN(node_id)
 Like DT_NODE_FULL_NAME_TOKEN(), but uppercased.
 
#define DT_NODE_CHILD_IDX(node_id)
 Get a devicetree node's index into its parent's list of children.
 
#define DT_CHILD_NUM(node_id)
 Get the number of child nodes of a given node.
 
#define DT_CHILD_NUM_STATUS_OKAY(node_id)
 Get the number of child nodes of a given node which child nodes' status are okay.
 
#define DT_SAME_NODE(node_id1, node_id2)
 Do node_id1 and node_id2 refer to the same node?
 
#define DT_NODELABEL_STRING_ARRAY(node_id)
 Get a devicetree node's node labels as an array of strings.
 

Detailed Description

Macro Definition Documentation

◆ DT_ALIAS

#define DT_ALIAS ( alias)

#include <zephyr/devicetree.h>

Value:
DT_CAT(DT_N_ALIAS_, alias)

Get a node identifier from /aliases.

This macro's argument is a property of the /aliases node. It returns a node identifier for the node which is aliased. Convert non-alphanumeric characters in the alias property to underscores to form valid C tokens, and lowercase all letters.

Example devicetree fragment:

/ {
aliases {
my-serial = &serial1;
};
soc {
serial1: serial@40001000 {
status = "okay";
current-speed = <115200>;
...
};
};
};

You can use DT_ALIAS(my_serial) to get a node identifier for the serial@40001000 node. Notice how my-serial in the devicetree becomes my_serial in the DT_ALIAS() argument. Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_ALIAS(my_serial), current_speed) // 115200
#define DT_ALIAS(alias)
Get a node identifier from /aliases.
Definition devicetree.h:240
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition devicetree.h:749
Parameters
aliaslowercase-and-underscores alias name.
Returns
node identifier for the node with that alias

◆ DT_CHILD

#define DT_CHILD ( node_id,
child )

#include <zephyr/devicetree.h>

Value:
UTIL_CAT(node_id, DT_S_PREFIX(child))
#define UTIL_CAT(a,...)
Definition util_internal.h:104

Get a node identifier for a child node.

Example devicetree fragment:

/ {
soc-label: soc {
serial1: serial@40001000 {
status = "okay";
current-speed = <115200>;
...
};
};
};

Example usage with DT_PROP() to get the status of the serial@40001000 node:

#define SOC_NODE DT_NODELABEL(soc_label)
DT_PROP(DT_CHILD(SOC_NODE, serial_40001000), status) // "okay"
#define DT_CHILD(node_id, child)
Get a node identifier for a child node.
Definition devicetree.h:423

Node labels like serial1 cannot be used as the child argument to this macro. Use DT_NODELABEL() for that instead.

You can also use DT_FOREACH_CHILD() to iterate over node identifiers for all of a node's children.

Parameters
node_idnode identifier
childlowercase-and-underscores child node name
Returns
node identifier for the node with the name referred to by 'child'

◆ DT_CHILD_NUM

#define DT_CHILD_NUM ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _CHILD_NUM)

Get the number of child nodes of a given node.

Parameters
node_ida node identifier
Returns
Number of child nodes

◆ DT_CHILD_NUM_STATUS_OKAY

#define DT_CHILD_NUM_STATUS_OKAY ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _CHILD_NUM_STATUS_OKAY)

Get the number of child nodes of a given node which child nodes' status are okay.

Parameters
node_ida node identifier
Returns
Number of child nodes which status are okay

◆ DT_COMPAT_GET_ANY_STATUS_OKAY

#define DT_COMPAT_GET_ANY_STATUS_OKAY ( compat)

#include <zephyr/devicetree.h>

Value:
(DT_INST(0, compat)), \
#define DT_HAS_COMPAT_STATUS_OKAY(compat)
Does the devicetree have a status okay node with a compatible?
Definition devicetree.h:3561
#define DT_INVALID_NODE
Name for an invalid node identifier.
Definition devicetree.h:87
#define DT_INST(inst, compat)
Get a node identifier for an instance of a compatible.
Definition devicetree.h:336
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition util_macro.h:195

Get a node identifier for a status okay node with a compatible.

Use this if you want to get an arbitrary enabled node with a given compatible, and you do not care which one you get. If any enabled nodes with the given compatible exist, a node identifier for one of them is returned. Otherwise, DT_INVALID_NODE is returned.

Example devicetree fragment:

node-a {
compatible = "vnd,device";
status = "okay";
};
node-b {
compatible = "vnd,device";
status = "okay";
};
node-c {
compatible = "vnd,device";
status = "disabled";
};

Example usage:

#define DT_COMPAT_GET_ANY_STATUS_OKAY(compat)
Get a node identifier for a status okay node with a compatible.
Definition devicetree.h:466

This expands to a node identifier for either node-a or node-b. It will not expand to a node identifier for node-c, because that node does not have status okay.

Parameters
compatlowercase-and-underscores compatible, without quotes
Returns
node identifier for a node with that compatible, or DT_INVALID_NODE

◆ DT_GPARENT

#define DT_GPARENT ( node_id)

#include <zephyr/devicetree.h>

Value:
#define DT_PARENT(node_id)
Get a node identifier for a parent node.
Definition devicetree.h:361

Get a node identifier for a grandparent node.

Example devicetree fragment:

gparent: grandparent-node {
parent: parent-node {
child: child-node { ... }
};
};

The following are equivalent ways to get the same node identifier:

#define DT_GPARENT(node_id)
Get a node identifier for a grandparent node.
Definition devicetree.h:386
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition devicetree.h:200
Parameters
node_idnode identifier
Returns
a node identifier for the node's parent's parent

◆ DT_INST

#define DT_INST ( inst,
compat )

#include <zephyr/devicetree.h>

Value:
UTIL_CAT(DT_N_INST, DT_DASH(inst, compat))

Get a node identifier for an instance of a compatible.

All nodes with a particular compatible property value are assigned instance numbers, which are zero-based indexes specific to that compatible. You can get a node identifier for these nodes by passing DT_INST() an instance number, inst, along with the lowercase-and-underscores version of the compatible, compat.

Instance numbers have the following properties:

  • for each compatible, instance numbers start at 0 and are contiguous
  • exactly one instance number is assigned for each node with a compatible, including disabled nodes
  • enabled nodes (status property is okay or missing) are assigned the instance numbers starting from 0, and disabled nodes have instance numbers which are greater than those of any enabled node

No other guarantees are made. In particular:

  • instance numbers in no way reflect any numbering scheme that might exist in SoC documentation, node labels or unit addresses, or properties of the /aliases node (use DT_NODELABEL() or DT_ALIAS() for those)
  • there is no general guarantee that the same node will have the same instance number between builds, even if you are building the same application again in the same build directory

Example devicetree fragment:

serial1: serial@40001000 {
compatible = "vnd,soc-serial";
status = "disabled";
current-speed = <9600>;
...
};
serial2: serial@40002000 {
compatible = "vnd,soc-serial";
status = "okay";
current-speed = <57600>;
...
};
serial3: serial@40003000 {
compatible = "vnd,soc-serial";
current-speed = <115200>;
...
};

Assuming no other nodes in the devicetree have compatible "vnd,soc-serial", that compatible has nodes with instance numbers 0, 1, and 2.

The nodes serial@40002000 and serial@40003000 are both enabled, so their instance numbers are 0 and 1, but no guarantees are made regarding which node has which instance number.

Since serial@40001000 is the only disabled node, it has instance number 2, since disabled nodes are assigned the largest instance numbers. Therefore:

// Could be 57600 or 115200. There is no way to be sure:
// either serial@40002000 or serial@40003000 could
// have instance number 0, so this could be the current-speed
// property of either of those nodes.
DT_PROP(DT_INST(0, vnd_soc_serial), current_speed)
// Could be 57600 or 115200, for the same reason.
// If the above expression expands to 57600, then
// this expands to 115200, and vice-versa.
DT_PROP(DT_INST(1, vnd_soc_serial), current_speed)
// 9600, because there is only one disabled node, and
// disabled nodes are "at the end" of the instance
// number "list".
DT_PROP(DT_INST(2, vnd_soc_serial), current_speed)

Notice how "vnd,soc-serial" in the devicetree becomes vnd_soc_serial (without quotes) in the DT_INST() arguments. (As usual, current-speed in the devicetree becomes current_speed as well.)

Nodes whose compatible property has multiple values are assigned independent instance numbers for each compatible.

Parameters
instinstance number for compatible compat
compatlowercase-and-underscores compatible, without quotes
Returns
node identifier for the node with that instance number and compatible

◆ DT_INVALID_NODE

#define DT_INVALID_NODE   _

#include <zephyr/devicetree.h>

Name for an invalid node identifier.

This supports cases where factored macros can be invoked from paths where devicetree data may or may not be available. It is a preprocessor identifier that does not match any valid devicetree node identifier.

◆ DT_NODE_CHILD_IDX

#define DT_NODE_CHILD_IDX ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _CHILD_IDX)

Get a devicetree node's index into its parent's list of children.

Indexes are zero-based.

It is an error to use this macro with the root node.

Example devicetree fragment:

parent {
c1: child-1 {};
c2: child-2 {};
};

Example usage:

#define DT_NODE_CHILD_IDX(node_id)
Get a devicetree node's index into its parent's list of children.
Definition devicetree.h:638
Parameters
node_idnode identifier
Returns
the node's index in its parent node's list of children

◆ DT_NODE_FULL_NAME

#define DT_NODE_FULL_NAME ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _FULL_NAME)

Get a devicetree node's name with unit-address as a string literal.

This returns the node name and unit-address from a node identifier.

Example devicetree fragment:

/ {
soc {
node: my-node@12345678 { ... };
};
};

Example usage:

DT_NODE_FULL_NAME(DT_NODELABEL(node)) // "my-node@12345678"
#define DT_NODE_FULL_NAME(node_id)
Get a devicetree node's name with unit-address as a string literal.
Definition devicetree.h:524
Parameters
node_idnode identifier
Returns
the node's name with unit-address as a string in the devicetree

◆ DT_NODE_FULL_NAME_TOKEN

#define DT_NODE_FULL_NAME_TOKEN ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _FULL_NAME_TOKEN)

Get the node's full name, including the unit-address, as a token.

This macro returns removed "the quotes" from the node's full name and converting any non-alphanumeric characters to underscores.

Example devicetree fragment:

/ {
soc {
node: my-node@12345678 { ... };
};
};

Example usage:

DT_NODE_FULL_NAME_TOKEN(DT_NODELABEL(node)) // my_node_12345678
#define DT_NODE_FULL_NAME_TOKEN(node_id)
Get the node's full name, including the unit-address, as a token.
Definition devicetree.h:580
Parameters
node_idnode identifier
Returns
the node's full name with unit-address as a token, i.e. without any quotes and with special characters converted to underscores

◆ DT_NODE_FULL_NAME_UNQUOTED

#define DT_NODE_FULL_NAME_UNQUOTED ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _FULL_NAME_UNQUOTED)

Get the node's full name, including the unit-address, as an unquoted sequence of tokens.

This macro returns removed "the quotes" from the node's full name.

Example devicetree fragment:

/ {
soc {
node: my-node@12345678 { ... };
};
};

Example usage:

DT_NODE_FULL_NAME_UNQUOTED(DT_NODELABEL(node)) // my-node@12345678
#define DT_NODE_FULL_NAME_UNQUOTED(node_id)
Get the node's full name, including the unit-address, as an unquoted sequence of tokens.
Definition devicetree.h:552
Parameters
node_idnode identifier
Returns
the node's full name with unit-address as a sequence of tokens, with no quotes

◆ DT_NODE_FULL_NAME_UPPER_TOKEN

#define DT_NODE_FULL_NAME_UPPER_TOKEN ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _FULL_NAME_UPPER_TOKEN)

Like DT_NODE_FULL_NAME_TOKEN(), but uppercased.

This macro returns removed "the quotes" from the node's full name, converting any non-alphanumeric characters to underscores, and capitalizing the result.

Example devicetree fragment:

/ {
soc {
node: my-node@12345678 { ... };
};
};

Example usage:

DT_NODE_FULL_NAME_UPPER_TOKEN(DT_NODELABEL(node)) // MY_NODE_12345678
#define DT_NODE_FULL_NAME_UPPER_TOKEN(node_id)
Like DT_NODE_FULL_NAME_TOKEN(), but uppercased.
Definition devicetree.h:610
Parameters
node_idnode identifier
Returns
the node's full name with unit-address as an uppercased token, i.e. without any quotes and with special characters converted to underscores

◆ DT_NODE_PATH

#define DT_NODE_PATH ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _PATH)

Get a devicetree node's full path as a string literal.

This returns the path to a node from a node identifier. To get a node identifier from path components instead, use DT_PATH().

Example devicetree fragment:

/ {
soc {
node: my-node@12345678 { ... };
};
};

Example usage:

DT_NODE_PATH(DT_NODELABEL(node)) // "/soc/my-node@12345678"
DT_NODE_PATH(DT_PATH(soc)) // "/soc"
#define DT_PATH(...)
Get a node identifier for a devicetree path.
Definition devicetree.h:144
#define DT_NODE_PATH(node_id)
Get a devicetree node's full path as a string literal.
Definition devicetree.h:498
#define DT_ROOT
Node identifier for the root node in the devicetree.
Definition devicetree.h:92
Parameters
node_idnode identifier
Returns
the node's full path in the devicetree

◆ DT_NODELABEL

#define DT_NODELABEL ( label)

#include <zephyr/devicetree.h>

Value:
DT_CAT(DT_N_NODELABEL_, label)

Get a node identifier for a node label.

Convert non-alphanumeric characters in the node label to underscores to form valid C tokens, and lowercase all letters. Note that node labels are not the same thing as label properties.

Example devicetree fragment:

serial1: serial@40001000 {
label = "UART_0";
status = "okay";
current-speed = <115200>;
...
};

The only node label in this example is serial1.

The string UART_0 is not a node label; it's the value of a property named label.

You can use DT_NODELABEL(serial1) to get a node identifier for the serial@40001000 node. Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_NODELABEL(serial1), current_speed) // 115200

Another example devicetree fragment:

cpu@0 {
L2_0: l2-cache {
cache-level = <2>;
...
};
};

Example usage to get the cache-level property:

DT_PROP(DT_NODELABEL(l2_0), cache_level) // 2

Notice how L2_0 in the devicetree is lowercased to l2_0 in the DT_NODELABEL() argument.

Parameters
labellowercase-and-underscores node label name
Returns
node identifier for the node with that label

◆ DT_NODELABEL_STRING_ARRAY

#define DT_NODELABEL_STRING_ARRAY ( node_id)

#include <zephyr/devicetree.h>

Value:
{ DT_FOREACH_NODELABEL(node_id, DT_NODELABEL_STRING_ARRAY_ENTRY_INTERNAL) }
#define DT_FOREACH_NODELABEL(node_id, fn)
Invokes fn for each node label of a given node.
Definition devicetree.h:3428

Get a devicetree node's node labels as an array of strings.

Example devicetree fragment:

foo: bar: node@deadbeef {};

Example usage:

#define DT_NODELABEL_STRING_ARRAY(node_id)
Get a devicetree node's node labels as an array of strings.
Definition devicetree.h:706

This expands to:

{ "foo", "bar", }
Parameters
node_idnode identifier
Returns
an array initializer for an array of the node's node labels as strings

◆ DT_PARENT

#define DT_PARENT ( node_id)

#include <zephyr/devicetree.h>

Value:
DT_CAT(node_id, _PARENT)

Get a node identifier for a parent node.

Example devicetree fragment:

parent: parent-node {
child: child-node {
...
};
};

The following are equivalent ways to get the same node identifier:

Parameters
node_idnode identifier
Returns
a node identifier for the node's parent

◆ DT_PATH

#define DT_PATH ( ...)

#include <zephyr/devicetree.h>

Value:
DT_PATH_INTERNAL(__VA_ARGS__)

Get a node identifier for a devicetree path.

Note
This macro returns a node identifier from path components. To get a path string from a node identifier, use DT_NODE_PATH() instead.

The arguments to this macro are the names of non-root nodes in the tree required to reach the desired node, starting from the root. Non-alphanumeric characters in each name must be converted to underscores to form valid C tokens, and letters must be lowercased.

Example devicetree fragment:

/ {
soc {
serial1: serial@40001000 {
status = "okay";
current-speed = <115200>;
...
};
};
};

You can use DT_PATH(soc, serial_40001000) to get a node identifier for the serial@40001000 node. Node labels like serial1 cannot be used as DT_PATH() arguments; use DT_NODELABEL() for those instead.

Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_PATH(soc, serial_40001000), current_speed) // 115200

(The current-speed property is also in lowercase-and-underscores form when used with this API.)

When determining arguments to DT_PATH():

  • the first argument corresponds to a child node of the root (soc above)
  • a second argument corresponds to a child of the first argument (serial_40001000 above, from the node name serial@40001000 after lowercasing and changing @ to _)
  • and so on for deeper nodes in the desired node's path
Parameters
...lowercase-and-underscores node names along the node's path, with each name given as a separate argument
Returns
node identifier for the node with that path

◆ DT_ROOT

#define DT_ROOT   DT_N

#include <zephyr/devicetree.h>

Node identifier for the root node in the devicetree.

◆ DT_SAME_NODE

#define DT_SAME_NODE ( node_id1,
node_id2 )

#include <zephyr/devicetree.h>

Value:
(DT_DEP_ORD(node_id1) == (DT_DEP_ORD(node_id2)))
#define DT_DEP_ORD(node_id)
Get a node's dependency ordinal.
Definition ordinals.h:25

Do node_id1 and node_id2 refer to the same node?

Both node_id1 and node_id2 must be node identifiers for nodes that exist in the devicetree (if unsure, you can check with DT_NODE_EXISTS()).

The expansion evaluates to 0 or 1, but may not be a literal integer 0 or 1.

Parameters
node_id1first node identifier
node_id2second node identifier
Returns
an expression that evaluates to 1 if the node identifiers refer to the same node, and evaluates to 0 otherwise