Zephyr API Documentation  3.2.99
A Scalable Open Source RTOS
Node identifiers and helpers

Macros

#define DT_INVALID_NODE   _
 Name for an invalid node identifier. More...
 
#define DT_ROOT   DT_N
 Node identifier for the root node in the devicetree. More...
 
#define DT_PATH(...)   DT_PATH_INTERNAL(__VA_ARGS__)
 Get a node identifier for a devicetree path. More...
 
#define DT_NODELABEL(label)   DT_CAT(DT_N_NODELABEL_, label)
 Get a node identifier for a node label. More...
 
#define DT_ALIAS(alias)   DT_CAT(DT_N_ALIAS_, alias)
 Get a node identifier from /aliases. More...
 
#define DT_INST(inst, compat)   UTIL_CAT(DT_N_INST, DT_DASH(inst, compat))
 Get a node identifier for an instance of a compatible. More...
 
#define DT_PARENT(node_id)   UTIL_CAT(node_id, _PARENT)
 Get a node identifier for a parent node. More...
 
#define DT_INST_PARENT(inst)   DT_PARENT(DT_DRV_INST(inst))
 Get a DT_DRV_COMPAT parent's node identifier. More...
 
#define DT_GPARENT(node_id)   DT_PARENT(DT_PARENT(node_id))
 Get a node identifier for a grandparent node. More...
 
#define DT_CHILD(node_id, child)   UTIL_CAT(node_id, DT_S_PREFIX(child))
 Get a node identifier for a child node. More...
 
#define DT_COMPAT_GET_ANY_STATUS_OKAY(compat)
 Get a node identifier for a status okay node with a compatible. More...
 
#define DT_NODE_PATH(node_id)   DT_CAT(node_id, _PATH)
 Get a devicetree node's full path as a string literal. More...
 
#define DT_NODE_FULL_NAME(node_id)   DT_CAT(node_id, _FULL_NAME)
 Get a devicetree node's name with unit-address as a string literal. More...
 
#define DT_NODE_CHILD_IDX(node_id)   DT_CAT(node_id, _CHILD_IDX)
 Get a devicetree node's index into its parent's list of children. More...
 
#define DT_SAME_NODE(node_id1, node_id2)    (DT_DEP_ORD(node_id1) == (DT_DEP_ORD(node_id2)))
 Do node_id1 and node_id2 refer to the same node? More...
 

Detailed Description

Macro Definition Documentation

◆ DT_ALIAS

#define DT_ALIAS (   alias)    DT_CAT(DT_N_ALIAS_, alias)

#include <zephyr/devicetree.h>

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:230
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition: devicetree.h:614
Parameters
aliaslowercase-and-underscores alias name.
Returns
node identifier for the node with that alias

◆ DT_CHILD

#define DT_CHILD (   node_id,
  child 
)    UTIL_CAT(node_id, DT_S_PREFIX(child))

#include <zephyr/devicetree.h>

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:420

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_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:2707
#define DT_INVALID_NODE
Name for an invalid node identifier.
Definition: devicetree.h:77
#define DT_INST(inst, compat)
Get a node identifier for an instance of a compatible.
Definition: devicetree.h:326
#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:156

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:463

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)    DT_PARENT(DT_PARENT(node_id))

#include <zephyr/devicetree.h>

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_PARENT(node_id)
Get a node identifier for a parent node.
Definition: devicetree.h:351
#define DT_GPARENT(node_id)
Get a node identifier for a grandparent node.
Definition: devicetree.h:383
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:190
Parameters
node_idnode identifier
Returns
a node identifier for the node's parent's parent

◆ DT_INST

#define DT_INST (   inst,
  compat 
)    UTIL_CAT(DT_N_INST, DT_DASH(inst, compat))

#include <zephyr/devicetree.h>

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

#define DT_INST_PARENT (   inst)    DT_PARENT(DT_DRV_INST(inst))

#include <zephyr/devicetree.h>

Get a DT_DRV_COMPAT parent's node identifier.

Parameters
instinstance number
Returns
a node identifier for the instance's parent

◆ 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)    DT_CAT(node_id, _CHILD_IDX)

#include <zephyr/devicetree.h>

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:549
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)    DT_CAT(node_id, _FULL_NAME)

#include <zephyr/devicetree.h>

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:521
Parameters
node_idnode identifier
Returns
the node's name with unit-address as a string in the devicetree

◆ DT_NODE_PATH

#define DT_NODE_PATH (   node_id)    DT_CAT(node_id, _PATH)

#include <zephyr/devicetree.h>

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:134
#define DT_NODE_PATH(node_id)
Get a devicetree node's full path as a string literal.
Definition: devicetree.h:495
#define DT_ROOT
Node identifier for the root node in the devicetree.
Definition: devicetree.h:82
Parameters
node_idnode identifier
Returns
the node's full path in the devicetree

◆ DT_NODELABEL

#define DT_NODELABEL (   label)    DT_CAT(DT_N_NODELABEL_, label)

#include <zephyr/devicetree.h>

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_PARENT

#define DT_PARENT (   node_id)    UTIL_CAT(node_id, _PARENT)

#include <zephyr/devicetree.h>

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 (   ...)    DT_PATH_INTERNAL(__VA_ARGS__)

#include <zephyr/devicetree.h>

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 
)     (DT_DEP_ORD(node_id1) == (DT_DEP_ORD(node_id2)))

#include <zephyr/devicetree.h>

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