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_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_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 <include/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 <include/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 <include/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 <include/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 <include/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 <include/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_FULL_NAME

#define DT_NODE_FULL_NAME ( node_id ) DT_CAT(node_id, _FULL_NAME)

#include <include/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 <include/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 <include/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 ) UTIL_CAT(node_id, _PARENT)

#include <include/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 <include/devicetree.h>

Get a node identifier for a devicetree path.

(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 <include/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 <include/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 identifer
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

Macros

Detailed Description

Macro Definition Documentation

◆ DT_ALIAS

◆ DT_CHILD

◆ DT_COMPAT_GET_ANY_STATUS_OKAY

◆ DT_GPARENT

◆ DT_INST

◆ DT_INVALID_NODE

◆ DT_NODE_FULL_NAME

◆ DT_NODE_PATH

◆ DT_NODELABEL

◆ DT_PARENT

◆ DT_PATH

◆ DT_ROOT

◆ DT_SAME_NODE