"For-each" macros

Macros
#define	DT_FOREACH_NODE(fn)
	Invokes fn for every node in the tree.
#define	DT_FOREACH_NODE_VARGS(fn, ...)
	Invokes fn for every node in the tree with multiple arguments.
#define	DT_FOREACH_STATUS_OKAY_NODE(fn)
	Invokes fn for every status okay node in the tree.
#define	DT_FOREACH_STATUS_OKAY_NODE_VARGS(fn, ...)
	Invokes fn for every status okay node in the tree with multiple arguments.
#define	DT_FOREACH_ANCESTOR(node_id, fn)
	Invokes fn for each ancestor of node_id.
#define	DT_FOREACH_CHILD(node_id, fn)
	Invokes fn for each child of node_id.
#define	DT_FOREACH_CHILD_SEP(node_id, fn, sep)
	Invokes fn for each child of node_id with a separator.
#define	DT_FOREACH_CHILD_VARGS(node_id, fn, ...)
	Invokes fn for each child of node_id with multiple arguments.
#define	DT_FOREACH_CHILD_SEP_VARGS(node_id, fn, sep, ...)
	Invokes fn for each child of node_id with separator and multiple arguments.
#define	DT_FOREACH_CHILD_STATUS_OKAY(node_id, fn)
	Call fn on the child nodes with status okay
#define	DT_FOREACH_CHILD_STATUS_OKAY_SEP(node_id, fn, sep)
	Call fn on the child nodes with status okay with separator.
#define	DT_FOREACH_CHILD_STATUS_OKAY_VARGS(node_id, fn, ...)
	Call fn on the child nodes with status okay with multiple arguments.
#define	DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS(node_id, fn, sep, ...)
	Call fn on the child nodes with status okay with separator and multiple arguments.
#define	DT_FOREACH_PROP_ELEM(node_id, prop, fn)
	Invokes fn for each element in the value of property prop.
#define	DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep)
	Invokes fn for each element in the value of property prop with separator.
#define	DT_FOREACH_PROP_ELEM_VARGS(node_id, prop, fn, ...)
	Invokes fn for each element in the value of property prop with multiple arguments.
#define	DT_FOREACH_PROP_ELEM_SEP_VARGS(node_id, prop, fn, sep, ...)
	Invokes fn for each element in the value of property prop with multiple arguments and a separator.
#define	DT_FOREACH_STATUS_OKAY(compat, fn)
	Invokes fn for each status okay node of a compatible.
#define	DT_FOREACH_STATUS_OKAY_VARGS(compat, fn, ...)
	Invokes fn for each status okay node of a compatible with multiple arguments.
#define	DT_COMPAT_FOREACH_STATUS_OKAY_VARGS(compat, fn, ...)
	Call fn on all nodes with compatible compat and status okay with multiple arguments.
#define	DT_FOREACH_NODELABEL(node_id, fn)
	Invokes fn for each node label of a given node.
#define	DT_FOREACH_NODELABEL_VARGS(node_id, fn, ...)
	Invokes fn for each node label of a given node with multiple arguments.

Detailed Description

Macro Definition Documentation

DT_COMPAT_FOREACH_STATUS_OKAY_VARGS

#define DT_COMPAT_FOREACH_STATUS_OKAY_VARGS	(		compat,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                  \
                    (UTIL_CAT(DT_FOREACH_OKAY_INST_VARGS_,              \
                              compat)(fn, compat, __VA_ARGS__)),        \
                    ())

Call fn on all nodes with compatible compat and status okay with multiple arguments.

Parameters

compat	lowercase-and-underscores devicetree compatible
fn	Macro to call for each enabled node. Must accept a devicetree compatible and instance number.
...	Additional arguments to pass to fn

See also

DT_INST_FOREACH_STATUS_OKAY_VARGS

DT_FOREACH_ANCESTOR

#define DT_FOREACH_ANCESTOR	(		node_id,
			fn )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_ANCESTOR)(fn)

Invokes fn for each ancestor of node_id.

The macro fn must take one parameter, which will be the identifier of a child node of node_id to enable traversal of all ancestor nodes.

The ancestor will be iterated over in the same order as they appear in the final devicetree.

Example devicetree fragment:

n: node1 {
        foobar = "foo1";
 
        n_2: node2 {
                   foobar = "foo2";
 
                   n_3: node3 {
                              foobar = "foo3";
                   };
        };
};

Example usage:

#define GET_PROP(n) DT_PROP(n, foobar),
 
const char *ancestor_names[] = {
    DT_FOREACH_ANCESTOR(DT_NODELABEL(n_3), GET_PROP)
};

This expands to:

const char *ancestor_names[] = {
    "foo2", "foo1",
};

Parameters

node_id	node identifier
fn	macro to invoke

DT_FOREACH_CHILD

#define DT_FOREACH_CHILD	(		node_id,
			fn )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD)(fn)

Invokes fn for each child of node_id.

The macro fn must take one parameter, which will be the node identifier of a child node of node_id.

The children will be iterated over in the same order as they appear in the final devicetree.

Example devicetree fragment:

n: node {
        child-1 {
                foobar = "foo";
        };
        child-2 {
                foobar = "bar";
        };
};

Example usage:

#define FOOBAR_AND_COMMA(node_id) DT_PROP(node_id, foobar),
 
const char *child_foobars[] = {
    DT_FOREACH_CHILD(DT_NODELABEL(n), FOOBAR_AND_COMMA)
};

This expands to:

const char *child_foobars[] = {
    "foo", "bar",
};

Parameters

node_id	node identifier
fn	macro to invoke

DT_FOREACH_CHILD_SEP

#define DT_FOREACH_CHILD_SEP	(		node_id,
			fn,
			sep )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_SEP)(fn, sep)

Invokes fn for each child of node_id with a separator.

The macro fn must take one parameter, which will be the node identifier of a child node of node_id.

Example devicetree fragment:

n: node {
        child-1 {
                ...
        };
        child-2 {
                ...
        };
};

Example usage:

const char *child_names[] = {
    DT_FOREACH_CHILD_SEP(DT_NODELABEL(n), DT_NODE_FULL_NAME, (,))
};

This expands to:

const char *child_names[] = {
    "child-1", "child-2"
};

Parameters

node_id	node identifier
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

DT_FOREACH_CHILD_SEP_VARGS

#define DT_FOREACH_CHILD_SEP_VARGS	(		node_id,
			fn,
			sep,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_SEP_VARGS)(fn, sep, __VA_ARGS__)

Invokes fn for each child of node_id with separator and multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the child node. The remaining are passed-in by the caller.

Parameters

node_id	node identifier
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
...	variable number of arguments to pass to fn

See also

DT_FOREACH_CHILD_VARGS

DT_FOREACH_CHILD_STATUS_OKAY

#define DT_FOREACH_CHILD_STATUS_OKAY	(		node_id,
			fn )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY)(fn)

Call fn on the child nodes with status okay

The macro fn should take one argument, which is the node identifier for the child node.

As usual, both a missing status and an ok status are treated as okay.

The children will be iterated over in the same order as they appear in the final devicetree.

Parameters

node_id	node identifier
fn	macro to invoke

DT_FOREACH_CHILD_STATUS_OKAY_SEP

#define DT_FOREACH_CHILD_STATUS_OKAY_SEP	(		node_id,
			fn,
			sep )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_SEP)(fn, sep)

Call fn on the child nodes with status okay with separator.

The macro fn should take one argument, which is the node identifier for the child node.

As usual, both a missing status and an ok status are treated as okay.

Parameters

node_id	node identifier
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

See also

DT_FOREACH_CHILD_STATUS_OKAY

DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS

#define DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS	(		node_id,
			fn,
			sep,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_SEP_VARGS)(fn, sep, __VA_ARGS__)

Call fn on the child nodes with status okay with separator and multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the child node. The remaining are passed-in by the caller.

As usual, both a missing status and an ok status are treated as okay.

Parameters

node_id	node identifier
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
...	variable number of arguments to pass to fn

See also

DT_FOREACH_CHILD_SEP_STATUS_OKAY

DT_FOREACH_CHILD_STATUS_OKAY_VARGS

#define DT_FOREACH_CHILD_STATUS_OKAY_VARGS	(		node_id,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_VARGS)(fn, __VA_ARGS__)

Call fn on the child nodes with status okay with multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the child node. The remaining are passed-in by the caller.

As usual, both a missing status and an ok status are treated as okay.

The children will be iterated over in the same order as they appear in the final devicetree.

Parameters

node_id	node identifier
fn	macro to invoke
...	variable number of arguments to pass to fn

See also

DT_FOREACH_CHILD_STATUS_OKAY

DT_FOREACH_CHILD_VARGS

#define DT_FOREACH_CHILD_VARGS	(		node_id,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_CHILD_VARGS)(fn, __VA_ARGS__)

Invokes fn for each child of node_id with multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the child node. The remaining are passed-in by the caller.

The children will be iterated over in the same order as they appear in the final devicetree.

Parameters

node_id	node identifier
fn	macro to invoke
...	variable number of arguments to pass to fn

See also

DT_FOREACH_CHILD

DT_FOREACH_NODE

#define DT_FOREACH_NODE

(

fn

)

#include <zephyr/devicetree.h>

Value:

DT_FOREACH_HELPER(fn)

Invokes fn for every node in the tree.

The macro fn must take one parameter, which will be a node identifier. The macro is expanded once for each node in the tree. The order that nodes are visited in is not specified.

Parameters

fn	macro to invoke

DT_FOREACH_NODE_VARGS

#define DT_FOREACH_NODE_VARGS	(		fn,
			... )

#include <zephyr/devicetree.h>

Value:

DT_FOREACH_VARGS_HELPER(fn, __VA_ARGS__)

Invokes fn for every node in the tree with multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the node. The remaining are passed-in by the caller.

The macro is expanded once for each node in the tree. The order that nodes are visited in is not specified.

Parameters

fn	macro to invoke
...	variable number of arguments to pass to fn

DT_FOREACH_NODELABEL

#define DT_FOREACH_NODELABEL	(		node_id,
			fn )

#include <zephyr/devicetree.h>

Value:

DT_CAT(node_id, _FOREACH_NODELABEL)(fn)

Invokes fn for each node label of a given node.

The order of the node labels in this macro's expansion matches the order in the final devicetree, with duplicates removed.

Node labels are passed to fn as tokens. Note that devicetree node labels are always valid C tokens (see "6.2 Labels" in Devicetree Specification v0.4 for details). The node labels are passed as tokens to fn as-is, without any lowercasing or conversion of special characters to underscores.

Example devicetree fragment:

foo: bar: FOO: node@deadbeef {};

Example usage:

int foo = 1;
int bar = 2;
int FOO = 3;
 
#define FN(nodelabel) + nodelabel
int sum = 0 DT_FOREACH_NODELABEL(DT_NODELABEL(foo), FN)

This expands to:

int sum = 0 + 1 + 2 + 3;

Parameters

node_id	node identifier whose node labels to use
fn	macro which will be passed each node label in order

DT_FOREACH_NODELABEL_VARGS

#define DT_FOREACH_NODELABEL_VARGS	(		node_id,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT(node_id, _FOREACH_NODELABEL_VARGS)(fn, __VA_ARGS__)

Invokes fn for each node label of a given node with multiple arguments.

This is like DT_FOREACH_NODELABEL() except you can also pass additional arguments to fn.

Example devicetree fragment:

foo: bar: node@deadbeef {};

Example usage:

int foo = 0;
int bar = 1;
 
#define VAR_PLUS(nodelabel, to_add) int nodelabel ## _added = nodelabel + to_add;
 
DT_FOREACH_NODELABEL_VARGS(DT_NODELABEL(foo), VAR_PLUS, 1)

This expands to:

int foo = 0;
int bar = 1;
int foo_added = foo + 1;
int bar_added = bar + 1;

Parameters

node_id	node identifier whose node labels to use
fn	macro which will be passed each node label in order
...	additional arguments to pass to fn

DT_FOREACH_PROP_ELEM

#define DT_FOREACH_PROP_ELEM	(		node_id,
			prop,
			fn )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM)(fn)

Invokes fn for each element in the value of property prop.

The macro fn must take three parameters: fn(node_id, prop, idx). node_id and prop are the same as what is passed to DT_FOREACH_PROP_ELEM(), and idx is the current index into the array. The idx values are integer literals starting from 0.

The prop argument must refer to a property that can be passed to DT_PROP_LEN().

Example devicetree fragment:

n: node {
        my-ints = <1 2 3>;
};

Example usage:

#define TIMES_TWO(node_id, prop, idx) \
        (2 * DT_PROP_BY_IDX(node_id, prop, idx)),
 
int array[] = {
        DT_FOREACH_PROP_ELEM(DT_NODELABEL(n), my_ints, TIMES_TWO)
};

This expands to:

int array[] = {
        (2 * 1), (2 * 2), (2 * 3),
};

In general, this macro expands to:

fn(node_id, prop, 0) fn(node_id, prop, 1) [...] fn(node_id, prop, n-1)

where n is the number of elements in prop, as it would be returned by DT_PROP_LEN(node_id, prop).

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
fn	macro to invoke

See also

DT_PROP_LEN

DT_FOREACH_PROP_ELEM_SEP

#define DT_FOREACH_PROP_ELEM_SEP	(		node_id,
			prop,
			fn,
			sep )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_SEP)(fn, sep)

Invokes fn for each element in the value of property prop with separator.

Example devicetree fragment:

n: node {
        my-gpios = <&gpioa 0 GPIO_ACTICE_HIGH>,
                   <&gpiob 1 GPIO_ACTIVE_HIGH>;
};

Example usage:

struct gpio_dt_spec specs[] = {
        DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), my_gpios,
                                 GPIO_DT_SPEC_GET_BY_IDX, (,))
};

This expands as a first step to:

struct gpio_dt_spec specs[] = {
        GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), my_gpios, 0),
        GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), my_gpios, 1)
};

The prop parameter has the same restrictions as the same parameter given to DT_FOREACH_PROP_ELEM().

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

See also

DT_FOREACH_PROP_ELEM

DT_FOREACH_PROP_ELEM_SEP_VARGS

#define DT_FOREACH_PROP_ELEM_SEP_VARGS	(		node_id,
			prop,
			fn,
			sep,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_SEP_VARGS)(      \
                fn, sep, __VA_ARGS__)

Invokes fn for each element in the value of property prop with multiple arguments and a separator.

The prop parameter has the same restrictions as the same parameter given to DT_FOREACH_PROP_ELEM().

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
fn	macro to invoke
sep	Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.
...	variable number of arguments to pass to fn

See also

DT_FOREACH_PROP_ELEM_VARGS

DT_FOREACH_PROP_ELEM_VARGS

#define DT_FOREACH_PROP_ELEM_VARGS	(		node_id,
			prop,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_VARGS)(fn, __VA_ARGS__)

Invokes fn for each element in the value of property prop with multiple arguments.

The macro fn must take multiple parameters: fn(node_id, prop, idx, ...). node_id and prop are the same as what is passed to DT_FOREACH_PROP_ELEM(), and idx is the current index into the array. The idx values are integer literals starting from 0. The remaining arguments are passed-in by the caller.

The prop parameter has the same restrictions as the same parameter given to DT_FOREACH_PROP_ELEM().

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
fn	macro to invoke
...	variable number of arguments to pass to fn

See also

DT_FOREACH_PROP_ELEM

DT_FOREACH_STATUS_OKAY

#define DT_FOREACH_STATUS_OKAY	(		compat,
			fn )

#include <zephyr/devicetree.h>

Value:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                  \
                    (UTIL_CAT(DT_FOREACH_OKAY_, compat)(fn)),           \
                    ())

Invokes fn for each status okay node of a compatible.

This macro expands to:

fn(node_id_1) fn(node_id_2) ... fn(node_id_n)

where each node_id_<i> is a node identifier for some node with compatible compat and status okay. Whitespace is added between expansions as shown above.

Example devicetree fragment:

/ {
        a {
                compatible = "foo";
                status = "okay";
        };
        b {
                compatible = "foo";
                status = "disabled";
        };
        c {
                compatible = "foo";
        };
};

Example usage:

DT_FOREACH_STATUS_OKAY(foo, DT_NODE_PATH)

This expands to one of the following:

"/a" "/c"
"/c" "/a"

"One of the following" is because no guarantees are made about the order that node identifiers are passed to fn in the expansion.

(The /c string literal is present because a missing status property is always treated as if the status were set to okay.)

Note also that fn is responsible for adding commas, semicolons, or other terminators as needed.

Parameters

compat	lowercase-and-underscores devicetree compatible
fn	Macro to call for each enabled node. Must accept a node_id as its only parameter.

DT_FOREACH_STATUS_OKAY_NODE

#define DT_FOREACH_STATUS_OKAY_NODE

(

fn

)

#include <zephyr/devicetree.h>

Value:

DT_FOREACH_OKAY_HELPER(fn)

Invokes fn for every status okay node in the tree.

The macro fn must take one parameter, which will be a node identifier. The macro is expanded once for each node in the tree with status okay (as usual, a missing status property is treated as status okay). The order that nodes are visited in is not specified.

Parameters

fn	macro to invoke

DT_FOREACH_STATUS_OKAY_NODE_VARGS

#define DT_FOREACH_STATUS_OKAY_NODE_VARGS	(		fn,
			... )

#include <zephyr/devicetree.h>

Value:

DT_FOREACH_OKAY_VARGS_HELPER(fn, __VA_ARGS__)

Invokes fn for every status okay node in the tree with multiple arguments.

The macro fn takes multiple arguments. The first should be the node identifier for the node. The remaining are passed-in by the caller.

The macro is expanded once for each node in the tree with status okay (as usual, a missing status property is treated as status okay). The order that nodes are visited in is not specified.

Parameters

fn	macro to invoke
...	variable number of arguments to pass to fn

DT_FOREACH_STATUS_OKAY_VARGS

#define DT_FOREACH_STATUS_OKAY_VARGS	(		compat,
			fn,
			... )

#include <zephyr/devicetree.h>

Value:

        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                  \
                    (DT_CAT(DT_FOREACH_OKAY_VARGS_,                     \
                              compat)(fn, __VA_ARGS__)),                \
                    ())

Invokes fn for each status okay node of a compatible with multiple arguments.

This is like DT_FOREACH_STATUS_OKAY() except you can also pass additional arguments to fn.

Example devicetree fragment:

/ {
        a {
                compatible = "foo";
                val = <3>;
        };
        b {
                compatible = "foo";
                val = <4>;
        };
};

Example usage:

#define MY_FN(node_id, operator) DT_PROP(node_id, val) operator
x = DT_FOREACH_STATUS_OKAY_VARGS(foo, MY_FN, +) 0;

This expands to one of the following:

x = 3 + 4 + 0;
x = 4 + 3 + 0;

i.e. it sets x to 7. As with DT_FOREACH_STATUS_OKAY(), there are no guarantees about the order nodes appear in the expansion.

Parameters

compat	lowercase-and-underscores devicetree compatible
fn	Macro to call for each enabled node. Must accept a node_id as its only parameter.
...	Additional arguments to pass to fn