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(...)   DT_PATH_INTERNAL(__VA_ARGS__)
	Get a node identifier for a devicetree path.
#define	DT_NODELABEL(label)   DT_CAT(DT_N_NODELABEL_, label)
	Get a node identifier for a node label.
#define	DT_ALIAS(alias)   DT_CAT(DT_N_ALIAS_, alias)
	Get a node identifier from /aliases.
#define	DT_INST(inst, compat)   UTIL_CAT(DT_N_INST, DT_DASH(inst, compat))
	Get a node identifier for an instance of a compatible.
#define	DT_PARENT(node_id)   DT_CAT(node_id, _PARENT)
	Get a node identifier for a parent node.
#define	DT_GPARENT(node_id)   DT_PARENT(DT_PARENT(node_id))
	Get a node identifier for a grandparent node.
#define	DT_CHILD(node_id, child)   UTIL_CAT(node_id, DT_S_PREFIX(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)   DT_CAT(node_id, _PATH)
	Get a devicetree node's full path as a string literal.
#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.
#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.
#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?

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

Parameters

alias

lowercase-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"

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_id	node identifier
child	lowercase-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:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),  \
                    (DT_INST(0, compat)),               \
                    (DT_INVALID_NODE))

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:

DT_COMPAT_GET_ANY_STATUS_OKAY(vnd_device)

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

compat

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

DT_GPARENT(DT_NODELABEL(child))
DT_PARENT(DT_PARENT(DT_NODELABEL(child))

Parameters

node_id

node 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

inst	instance number for compatible compat
compat	lowercase-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

)

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:

DT_NODE_CHILD_IDX(DT_NODELABEL(c1)) // 0
DT_NODE_CHILD_IDX(DT_NODELABEL(c2)) // 1

Parameters

node_id

node 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"

Parameters

node_id

node 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"
DT_NODE_PATH(DT_ROOT)            // "/"

Parameters

node_id

node 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

label

lowercase-and-underscores node label name

Returns

node identifier for the node with that label

DT_PARENT

#define DT_PARENT

(

node_id

)

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

DT_NODELABEL(parent)
DT_PARENT(DT_NODELABEL(child))

Parameters

node_id

node 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_id1	first node identifier
node_id2	second node identifier

Returns

an expression that evaluates to 1 if the node identifiers refer to the same node, and evaluates to 0 otherwise