Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
"For-each" macros

Macros

#define DT_FOREACH_NODE(fn)   DT_FOREACH_HELPER(fn)
 Invokes fn for every node in the tree.
 
#define DT_FOREACH_NODE_VARGS(fn, ...)   DT_FOREACH_VARGS_HELPER(fn, __VA_ARGS__)
 Invokes fn for every node in the tree with multiple arguments.
 
#define DT_FOREACH_STATUS_OKAY_NODE(fn)   DT_FOREACH_OKAY_HELPER(fn)
 Invokes fn for every status okay node in the tree.
 
#define DT_FOREACH_STATUS_OKAY_NODE_VARGS(fn, ...)   DT_FOREACH_OKAY_VARGS_HELPER(fn, __VA_ARGS__)
 Invokes fn for every status okay node in the tree with multiple arguments.
 
#define DT_FOREACH_CHILD(node_id, fn)    DT_CAT(node_id, _FOREACH_CHILD)(fn)
 Invokes fn for each child of node_id.
 
#define DT_FOREACH_CHILD_SEP(node_id, fn, sep)    DT_CAT(node_id, _FOREACH_CHILD_SEP)(fn, sep)
 Invokes fn for each child of node_id with a separator.
 
#define DT_FOREACH_CHILD_VARGS(node_id, fn, ...)    DT_CAT(node_id, _FOREACH_CHILD_VARGS)(fn, __VA_ARGS__)
 Invokes fn for each child of node_id with multiple arguments.
 
#define DT_FOREACH_CHILD_SEP_VARGS(node_id, fn, sep, ...)    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.
 
#define DT_FOREACH_CHILD_STATUS_OKAY(node_id, fn)    DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY)(fn)
 Call fn on the child nodes with status okay
 
#define DT_FOREACH_CHILD_STATUS_OKAY_SEP(node_id, fn, sep)    DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_SEP)(fn, sep)
 Call fn on the child nodes with status okay with separator.
 
#define DT_FOREACH_CHILD_STATUS_OKAY_VARGS(node_id, fn, ...)    DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_VARGS)(fn, __VA_ARGS__)
 Call fn on the child nodes with status okay with multiple arguments.
 
#define DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS(node_id, fn, sep, ...)    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.
 
#define DT_FOREACH_PROP_ELEM(node_id, prop, fn)    DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM)(fn)
 Invokes fn for each element in the value of property prop.
 
#define DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep)    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.
 
#define DT_FOREACH_PROP_ELEM_VARGS(node_id, prop, fn, ...)    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.
 
#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_FOREACH_NODELABEL(node_id, fn)   DT_CAT(node_id, _FOREACH_NODELABEL)(fn)
 Invokes fn for each node label of a given node.
 
#define DT_FOREACH_NODELABEL_VARGS(node_id, fn, ...)    DT_CAT(node_id, _FOREACH_NODELABEL_VARGS)(fn, __VA_ARGS__)
 Invokes fn for each node label of a given node with multiple arguments.
 

Detailed Description

Macro Definition Documentation

◆ DT_FOREACH_CHILD

#define DT_FOREACH_CHILD (   node_id,
  fn 
)     DT_CAT(node_id, _FOREACH_CHILD)(fn)

#include <zephyr/devicetree.h>

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)
};
#define DT_FOREACH_CHILD(node_id, fn)
Invokes fn for each child of node_id.
Definition: devicetree.h:2846
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:200

This expands to:

const char *child_foobars[] = {
"foo", "bar",
};
Parameters
node_idnode identifier
fnmacro to invoke

◆ DT_FOREACH_CHILD_SEP

#define DT_FOREACH_CHILD_SEP (   node_id,
  fn,
  sep 
)     DT_CAT(node_id, _FOREACH_CHILD_SEP)(fn, sep)

#include <zephyr/devicetree.h>

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[] = {
};
#define DT_FOREACH_CHILD_SEP(node_id, fn, sep)
Invokes fn for each child of node_id with a separator.
Definition: devicetree.h:2889
#define DT_NODE_FULL_NAME(node_id)
Get a devicetree node's name with unit-address as a string literal.
Definition: devicetree.h:524

This expands to:

const char *child_names[] = {
"child-1", "child-2"
};
Parameters
node_idnode identifier
fnmacro to invoke
sepSeparator (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,
  ... 
)     DT_CAT(node_id, _FOREACH_CHILD_SEP_VARGS)(fn, sep, __VA_ARGS__)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro to invoke
sepSeparator (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 
)     DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY)(fn)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro to invoke

◆ DT_FOREACH_CHILD_STATUS_OKAY_SEP

#define DT_FOREACH_CHILD_STATUS_OKAY_SEP (   node_id,
  fn,
  sep 
)     DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_SEP)(fn, sep)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro to invoke
sepSeparator (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,
  ... 
)     DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_SEP_VARGS)(fn, sep, __VA_ARGS__)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro to invoke
sepSeparator (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,
  ... 
)     DT_CAT(node_id, _FOREACH_CHILD_STATUS_OKAY_VARGS)(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro 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,
  ... 
)     DT_CAT(node_id, _FOREACH_CHILD_VARGS)(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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_idnode identifier
fnmacro to invoke
...variable number of arguments to pass to fn
See also
DT_FOREACH_CHILD

◆ DT_FOREACH_NODE

#define DT_FOREACH_NODE (   fn)    DT_FOREACH_HELPER(fn)

#include <zephyr/devicetree.h>

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
fnmacro to invoke

◆ DT_FOREACH_NODE_VARGS

#define DT_FOREACH_NODE_VARGS (   fn,
  ... 
)    DT_FOREACH_VARGS_HELPER(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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
fnmacro to invoke
...variable number of arguments to pass to fn

◆ DT_FOREACH_NODELABEL

#define DT_FOREACH_NODELABEL (   node_id,
  fn 
)    DT_CAT(node_id, _FOREACH_NODELABEL)(fn)

#include <zephyr/devicetree.h>

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)
#define DT_FOREACH_NODELABEL(node_id, fn)
Invokes fn for each node label of a given node.
Definition: devicetree.h:3295

This expands to:

int sum = 0 + 1 + 2 + 3;
Parameters
node_idnode identifier whose node labels to use
fnmacro which will be passed each node label in order

◆ DT_FOREACH_NODELABEL_VARGS

#define DT_FOREACH_NODELABEL_VARGS (   node_id,
  fn,
  ... 
)     DT_CAT(node_id, _FOREACH_NODELABEL_VARGS)(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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;
#define DT_FOREACH_NODELABEL_VARGS(node_id, fn,...)
Invokes fn for each node label of a given node with multiple arguments.
Definition: devicetree.h:3334

This expands to:

int foo = 0;
int bar = 1;
int foo_added = foo + 1;
int bar_added = bar + 1;
Parameters
node_idnode identifier whose node labels to use
fnmacro 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 
)     DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM)(fn)

#include <zephyr/devicetree.h>

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)
};
#define DT_FOREACH_PROP_ELEM(node_id, prop, fn)
Invokes fn for each element in the value of property prop.
Definition: devicetree.h:3058

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_idnode identifier
proplowercase-and-underscores property name
fnmacro to invoke
See also
DT_PROP_LEN

◆ DT_FOREACH_PROP_ELEM_SEP

#define DT_FOREACH_PROP_ELEM_SEP (   node_id,
  prop,
  fn,
  sep 
)     DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_SEP)(fn, sep)

#include <zephyr/devicetree.h>

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[] = {
};
#define DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep)
Invokes fn for each element in the value of property prop with separator.
Definition: devicetree.h:3103
#define GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, idx)
Static initializer for a gpio_dt_spec.
Definition: gpio.h:331
Container for GPIO pin information specified in devicetree.
Definition: gpio.h:288

This expands as a first step to:

struct gpio_dt_spec specs[] = {
};

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

Parameters
node_idnode identifier
proplowercase-and-underscores property name
fnmacro to invoke
sepSeparator (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_idnode identifier
proplowercase-and-underscores property name
fnmacro to invoke
sepSeparator (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,
  ... 
)     DT_CAT4(node_id, _P_, prop, _FOREACH_PROP_ELEM_VARGS)(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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_idnode identifier
proplowercase-and-underscores property name
fnmacro 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:
(DT_CAT(DT_FOREACH_OKAY_, compat)(fn)), \
())
#define DT_HAS_COMPAT_STATUS_OKAY(compat)
Does the devicetree have a status okay node with a compatible?
Definition: devicetree.h:3406
#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:179

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:

#define DT_FOREACH_STATUS_OKAY(compat, fn)
Invokes fn for each status okay node of a compatible.
Definition: devicetree.h:3202
#define DT_NODE_PATH(node_id)
Get a devicetree node's full path as a string literal.
Definition: devicetree.h:498

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
compatlowercase-and-underscores devicetree compatible
fnMacro 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)    DT_FOREACH_OKAY_HELPER(fn)

#include <zephyr/devicetree.h>

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
fnmacro to invoke

◆ DT_FOREACH_STATUS_OKAY_NODE_VARGS

#define DT_FOREACH_STATUS_OKAY_NODE_VARGS (   fn,
  ... 
)    DT_FOREACH_OKAY_VARGS_HELPER(fn, __VA_ARGS__)

#include <zephyr/devicetree.h>

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
fnmacro 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:
(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;
#define DT_FOREACH_STATUS_OKAY_VARGS(compat, fn,...)
Invokes fn for each status okay node of a compatible with multiple arguments.
Definition: devicetree.h:3251

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
compatlowercase-and-underscores devicetree compatible
fnMacro to call for each enabled node. Must accept a node_id as its only parameter.
...Additional arguments to pass to fn