Zephyr API Documentation  3.2.99
A Scalable Open Source RTOS
Property accessors

Macros

#define DT_PROP(node_id, prop)   DT_CAT3(node_id, _P_, prop)
 Get a devicetree property value. More...
 
#define DT_PROP_LEN(node_id, prop)   DT_CAT4(node_id, _P_, prop, _LEN)
 Get a property's logical length. More...
 
#define DT_PROP_LEN_OR(node_id, prop, default_value)
 Like DT_PROP_LEN(), but with a fallback to default_value. More...
 
#define DT_PROP_HAS_IDX(node_id, prop, idx)    IS_ENABLED(DT_CAT6(node_id, _P_, prop, _IDX_, idx, _EXISTS))
 Is index idx valid for an array type property? More...
 
#define DT_PROP_HAS_NAME(node_id, prop, name)    IS_ENABLED(DT_CAT6(node_id, _P_, prop, _NAME_, name, _EXISTS))
 Is name name available in a foo-names property? More...
 
#define DT_PROP_BY_IDX(node_id, prop, idx)    DT_CAT5(node_id, _P_, prop, _IDX_, idx)
 Get the value at index idx in an array type property. More...
 
#define DT_PROP_OR(node_id, prop, default_value)
 Like DT_PROP(), but with a fallback to default_value. More...
 
#define DT_LABEL(node_id)   DT_PROP(node_id, label) __DEPRECATED_MACRO
 Equivalent to DT_PROP(node_id, label) More...
 
#define DT_ENUM_IDX(node_id, prop)   DT_CAT4(node_id, _P_, prop, _ENUM_IDX)
 Get a property value's index into its enumeration values. More...
 
#define DT_ENUM_IDX_OR(node_id, prop, default_idx_value)
 Like DT_ENUM_IDX(), but with a fallback to a default enum index. More...
 
#define DT_STRING_TOKEN(node_id, prop)    DT_CAT4(node_id, _P_, prop, _STRING_TOKEN)
 Get a string property's value as a token. More...
 
#define DT_STRING_TOKEN_OR(node_id, prop, default_value)
 Like DT_STRING_TOKEN(), but with a fallback to default_value. More...
 
#define DT_STRING_UPPER_TOKEN(node_id, prop)    DT_CAT4(node_id, _P_, prop, _STRING_UPPER_TOKEN)
 Like DT_STRING_TOKEN(), but uppercased. More...
 
#define DT_STRING_UPPER_TOKEN_OR(node_id, prop, default_value)
 Like DT_STRING_UPPER_TOKEN(), but with a fallback to default_value. More...
 
#define DT_STRING_TOKEN_BY_IDX(node_id, prop, idx)    DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_TOKEN)
 Get an element out of a string-array property as a token. More...
 
#define DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx)    DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_UPPER_TOKEN)
 Like DT_STRING_TOKEN_BY_IDX(), but uppercased. More...
 
#define DT_PROP_BY_PHANDLE_IDX(node_id, phs, idx, prop)    DT_PROP(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop)
 Get a property value from a phandle in a property. More...
 
#define DT_PROP_BY_PHANDLE_IDX_OR(node_id, phs, idx, prop, default_value)    DT_PROP_OR(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop, default_value)
 Like DT_PROP_BY_PHANDLE_IDX(), but with a fallback to default_value. More...
 
#define DT_PROP_BY_PHANDLE(node_id, ph, prop)    DT_PROP_BY_PHANDLE_IDX(node_id, ph, 0, prop)
 Get a property value from a phandle's node. More...
 
#define DT_PHA_BY_IDX(node_id, pha, idx, cell)    DT_CAT7(node_id, _P_, pha, _IDX_, idx, _VAL_, cell)
 Get a phandle-array specifier cell value at an index. More...
 
#define DT_PHA_BY_IDX_OR(node_id, pha, idx, cell, default_value)    DT_PROP_OR(node_id, pha##_IDX_##idx##_VAL_##cell, default_value)
 Like DT_PHA_BY_IDX(), but with a fallback to default_value. More...
 
#define DT_PHA(node_id, pha, cell)   DT_PHA_BY_IDX(node_id, pha, 0, cell)
 Equivalent to DT_PHA_BY_IDX(node_id, pha, 0, cell) More...
 
#define DT_PHA_OR(node_id, pha, cell, default_value)    DT_PHA_BY_IDX_OR(node_id, pha, 0, cell, default_value)
 Like DT_PHA(), but with a fallback to default_value. More...
 
#define DT_PHA_BY_NAME(node_id, pha, name, cell)    DT_CAT7(node_id, _P_, pha, _NAME_, name, _VAL_, cell)
 Get a value within a phandle-array specifier by name. More...
 
#define DT_PHA_BY_NAME_OR(node_id, pha, name, cell, default_value)    DT_PROP_OR(node_id, pha##_NAME_##name##_VAL_##cell, default_value)
 Like DT_PHA_BY_NAME(), but with a fallback to default_value. More...
 
#define DT_PHANDLE_BY_NAME(node_id, pha, name)    DT_CAT6(node_id, _P_, pha, _NAME_, name, _PH)
 Get a phandle's node identifier from a phandle array by name. More...
 
#define DT_PHANDLE_BY_IDX(node_id, prop, idx)    DT_CAT6(node_id, _P_, prop, _IDX_, idx, _PH)
 Get a node identifier for a phandle in a property. More...
 
#define DT_PHANDLE(node_id, prop)   DT_PHANDLE_BY_IDX(node_id, prop, 0)
 Get a node identifier for a phandle property's value. More...
 

Detailed Description

Macro Definition Documentation

◆ DT_ENUM_IDX

#define DT_ENUM_IDX (   node_id,
  prop 
)    DT_CAT4(node_id, _P_, prop, _ENUM_IDX)

#include <zephyr/devicetree.h>

Get a property value's index into its enumeration values.

The return values start at zero.

Example devicetree fragment:

usb1: usb@12340000 {
maximum-speed = "full-speed";
};
usb2: usb@12341000 {
maximum-speed = "super-speed";
};

Example bindings fragment:

properties:
maximum-speed:
type: string
enum:
- "low-speed"
- "full-speed"
- "high-speed"
- "super-speed"

Example usage:

DT_ENUM_IDX(DT_NODELABEL(usb1), maximum_speed) // 1
DT_ENUM_IDX(DT_NODELABEL(usb2), maximum_speed) // 3
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:190
#define DT_ENUM_IDX(node_id, prop)
Get a property value's index into its enumeration values.
Definition: devicetree.h:815
Parameters
node_idnode identifier
proplowercase-and-underscores property name
Returns
zero-based index of the property's value in its enum: list

◆ DT_ENUM_IDX_OR

#define DT_ENUM_IDX_OR (   node_id,
  prop,
  default_idx_value 
)

#include <zephyr/devicetree.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_ENUM_IDX(node_id, prop)), (default_idx_value))
#define DT_NODE_HAS_PROP(node_id, prop)
Does a devicetree node have a property?
Definition: devicetree.h:2780
#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

Like DT_ENUM_IDX(), but with a fallback to a default enum index.

If the value exists, this expands to its zero based index value thanks to DT_ENUM_IDX(node_id, prop).

Otherwise, this expands to provided default index enum value.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
default_idx_valuea fallback index value to expand to
Returns
zero-based index of the property's value in its enum if present, default_idx_value otherwise

◆ DT_LABEL

#define DT_LABEL (   node_id)    DT_PROP(node_id, label) __DEPRECATED_MACRO

#include <zephyr/devicetree.h>

Equivalent to DT_PROP(node_id, label)

Deprecated:
Use DT_PROP(node_id, label)

This is a convenience for the Zephyr device API, which uses label properties as device_get_binding() arguments.

Parameters
node_idnode identifier
Returns
node's label property value

◆ DT_PHA

#define DT_PHA (   node_id,
  pha,
  cell 
)    DT_PHA_BY_IDX(node_id, pha, 0, cell)

#include <zephyr/devicetree.h>

Equivalent to DT_PHA_BY_IDX(node_id, pha, 0, cell)

Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
celllowercase-and-underscores cell name
Returns
the cell's value

◆ DT_PHA_BY_IDX

#define DT_PHA_BY_IDX (   node_id,
  pha,
  idx,
  cell 
)     DT_CAT7(node_id, _P_, pha, _IDX_, idx, _VAL_, cell)

#include <zephyr/devicetree.h>

Get a phandle-array specifier cell value at an index.

It might help to read the argument order as being similar to node->phandle_array[index].cell. That is, the cell value is in the pha property of node_id, inside the specifier at index idx.

Example devicetree fragment:

gpio0: gpio@abcd1234 {
#gpio-cells = <2>;
};
gpio1: gpio@1234abcd {
#gpio-cells = <2>;
};
led: led_0 {
gpios = <&gpio0 17 0x1>, <&gpio1 5 0x3>;
};

Bindings fragment for the gpio0 and gpio1 nodes:

gpio-cells:
- pin
- flags

Above, gpios has two elements:

  • index 0 has specifier <17 0x1>, so its pin cell is 17, and its flags cell is 0x1
  • index 1 has specifier <5 0x3>, so pin is 5 and flags is 0x3

Example usage:

#define LED DT_NODELABEL(led)
DT_PHA_BY_IDX(LED, gpios, 0, pin) // 17
DT_PHA_BY_IDX(LED, gpios, 1, flags) // 0x3
#define DT_PHA_BY_IDX(node_id, pha, idx, cell)
Get a phandle-array specifier cell value at an index.
Definition: devicetree.h:1238
flags
Definition: http_parser.h:131
Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
idxlogical index into pha
celllowercase-and-underscores cell name within the specifier at pha index idx
Returns
the cell's value

◆ DT_PHA_BY_IDX_OR

#define DT_PHA_BY_IDX_OR (   node_id,
  pha,
  idx,
  cell,
  default_value 
)     DT_PROP_OR(node_id, pha##_IDX_##idx##_VAL_##cell, default_value)

#include <zephyr/devicetree.h>

Like DT_PHA_BY_IDX(), but with a fallback to default_value.

If the value exists, this expands to DT_PHA_BY_IDX(node_id, pha, idx, cell). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
idxlogical index into pha
celllowercase-and-underscores cell name within the specifier at pha index idx
default_valuea fallback value to expand to
Returns
the cell's value or default_value

◆ DT_PHA_BY_NAME

#define DT_PHA_BY_NAME (   node_id,
  pha,
  name,
  cell 
)     DT_CAT7(node_id, _P_, pha, _NAME_, name, _VAL_, cell)

#include <zephyr/devicetree.h>

Get a value within a phandle-array specifier by name.

This is like DT_PHA_BY_IDX(), except it treats pha as a structure where each array element has a name.

It might help to read the argument order as being similar to node->phandle_struct.name.cell. That is, the cell value is in the pha property of node_id, treated as a data structure where each array element has a name.

Example devicetree fragment:

n: node {
io-channels = <&adc1 10>, <&adc2 20>;
io-channel-names = "SENSOR", "BANDGAP";
};

Bindings fragment for the "adc1" and "adc2" nodes:

io-channel-cells:
- input

Example usage:

DT_PHA_BY_NAME(DT_NODELABEL(n), io_channels, sensor, input) // 10
DT_PHA_BY_NAME(DT_NODELABEL(n), io_channels, bandgap, input) // 20
#define DT_PHA_BY_NAME(node_id, pha, name, cell)
Get a value within a phandle-array specifier by name.
Definition: devicetree.h:1333
Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
namelowercase-and-underscores name of a specifier in pha
celllowercase-and-underscores cell name in the named specifier
Returns
the cell's value

◆ DT_PHA_BY_NAME_OR

#define DT_PHA_BY_NAME_OR (   node_id,
  pha,
  name,
  cell,
  default_value 
)     DT_PROP_OR(node_id, pha##_NAME_##name##_VAL_##cell, default_value)

#include <zephyr/devicetree.h>

Like DT_PHA_BY_NAME(), but with a fallback to default_value.

If the value exists, this expands to DT_PHA_BY_NAME(node_id, pha, name, cell). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
namelowercase-and-underscores name of a specifier in pha
celllowercase-and-underscores cell name in the named specifier
default_valuea fallback value to expand to
Returns
the cell's value or default_value

◆ DT_PHA_OR

#define DT_PHA_OR (   node_id,
  pha,
  cell,
  default_value 
)     DT_PHA_BY_IDX_OR(node_id, pha, 0, cell, default_value)

#include <zephyr/devicetree.h>

Like DT_PHA(), but with a fallback to default_value.

If the value exists, this expands to DT_PHA(node_id, pha, cell). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
celllowercase-and-underscores cell name
default_valuea fallback value to expand to
Returns
the cell's value or default_value

◆ DT_PHANDLE

#define DT_PHANDLE (   node_id,
  prop 
)    DT_PHANDLE_BY_IDX(node_id, prop, 0)

#include <zephyr/devicetree.h>

Get a node identifier for a phandle property's value.

This is equivalent to DT_PHANDLE_BY_IDX(node_id, prop, 0). Its primary benefit is readability when prop has type phandle.

Parameters
node_idnode identifier
proplowercase-and-underscores property of node_id with type phandle
Returns
a node identifier for the node pointed to by "ph"

◆ DT_PHANDLE_BY_IDX

#define DT_PHANDLE_BY_IDX (   node_id,
  prop,
  idx 
)     DT_CAT6(node_id, _P_, prop, _IDX_, idx, _PH)

#include <zephyr/devicetree.h>

Get a node identifier for a phandle in a property.

When a node's value at a logical index contains a phandle, this macro returns a node identifier for the node with that phandle.

Therefore, if prop has type phandle, idx must be zero. (A phandle type is treated as a phandles with a fixed length of 1).

Example devicetree fragment:

n1: node-1 {
foo = <&n2 &n3>;
};
n2: node-2 { ... };
n3: node-3 { ... };

Above, foo has type phandles and has two elements:

  • index 0 has phandle &n2, which is node-2's phandle
  • index 1 has phandle &n3, which is node-3's phandle

Example usage:

#define N1 DT_NODELABEL(n1)
DT_PHANDLE_BY_IDX(N1, foo, 0) // node identifier for node-2
DT_PHANDLE_BY_IDX(N1, foo, 1) // node identifier for node-3
#define DT_PHANDLE_BY_IDX(node_id, prop, idx)
Get a node identifier for a phandle in a property.
Definition: devicetree.h:1459
Definition: main.c:25

Behavior is analogous for phandle-arrays.

Parameters
node_idnode identifier
proplowercase-and-underscores property name in node_id with type phandle, phandles or phandle-array
idxindex into prop
Returns
node identifier for the node with the phandle at that index

◆ DT_PHANDLE_BY_NAME

#define DT_PHANDLE_BY_NAME (   node_id,
  pha,
  name 
)     DT_CAT6(node_id, _P_, pha, _NAME_, name, _PH)

#include <zephyr/devicetree.h>

Get a phandle's node identifier from a phandle array by name.

It might help to read the argument order as being similar to node->phandle_struct.name.phandle. That is, the phandle array is treated as a structure with named elements. The return value is the node identifier for a phandle inside the structure.

Example devicetree fragment:

adc1: adc@abcd1234 {
foobar = "ADC_1";
};
adc2: adc@1234abcd {
foobar = "ADC_2";
};
n: node {
io-channels = <&adc1 10>, <&adc2 20>;
io-channel-names = "SENSOR", "BANDGAP";
};

Above, "io-channels" has two elements:

  • the element named "SENSOR" has phandle &adc1
  • the element named "BANDGAP" has phandle &adc2

Example usage:

#define NODE DT_NODELABEL(n)
DT_PROP(DT_PHANDLE_BY_NAME(NODE, io_channels, sensor), foobar) // "ADC_1"
DT_PROP(DT_PHANDLE_BY_NAME(NODE, io_channels, bandgap), foobar) // "ADC_2"
#define DT_PHANDLE_BY_NAME(node_id, pha, name)
Get a phandle's node identifier from a phandle array by name.
Definition: devicetree.h:1407
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition: devicetree.h:614

Notice how devicetree properties and names are lowercased, and non-alphanumeric characters are converted to underscores.

Parameters
node_idnode identifier
phalowercase-and-underscores property with type phandle-array
namelowercase-and-underscores name of an element in pha
Returns
a node identifier for the node with that phandle

◆ DT_PROP

#define DT_PROP (   node_id,
  prop 
)    DT_CAT3(node_id, _P_, prop)

#include <zephyr/devicetree.h>

Get a devicetree property value.

For properties whose bindings have the following types, this macro expands to:

  • string: a string literal
  • boolean: 0 if the property is false, or 1 if it is true
  • int: the property's value as an integer literal
  • array, uint8-array, string-array: an initializer expression in braces, whose elements are integer or string literals (like {0, 1, 2}, {"hello", "world"}, etc.)
  • phandle: a node identifier for the node with that phandle

A property's type is usually defined by its binding. In some special cases, it has an assumed type defined by the devicetree specification even when no binding is available: compatible has type string-array, status has type string, and interrupt-controller has type boolean.

For other properties or properties with unknown type due to a missing binding, behavior is undefined.

For usage examples, see DT_PATH(), DT_ALIAS(), DT_NODELABEL(), and DT_INST() above.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
Returns
a representation of the property's value

◆ DT_PROP_BY_IDX

#define DT_PROP_BY_IDX (   node_id,
  prop,
  idx 
)     DT_CAT5(node_id, _P_, prop, _IDX_, idx)

#include <zephyr/devicetree.h>

Get the value at index idx in an array type property.

It might help to read the argument order as being similar to node->property[index].

When the property's binding has type array, string-array, uint8-array, or phandles, this expands to the idx-th array element as an integer, string literal, or node identifier respectively.

These properties are handled as special cases:

For non-array properties, behavior is undefined.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
idxthe index to get
Returns
a representation of the idx-th element of the property

◆ DT_PROP_BY_PHANDLE

#define DT_PROP_BY_PHANDLE (   node_id,
  ph,
  prop 
)     DT_PROP_BY_PHANDLE_IDX(node_id, ph, 0, prop)

#include <zephyr/devicetree.h>

Get a property value from a phandle's node.

This is equivalent to DT_PROP_BY_PHANDLE_IDX(node_id, ph, 0, prop).

Parameters
node_idnode identifier
phlowercase-and-underscores property of node_id with type phandle
proplowercase-and-underscores property of the phandle's node
Returns
the property's value

◆ DT_PROP_BY_PHANDLE_IDX

#define DT_PROP_BY_PHANDLE_IDX (   node_id,
  phs,
  idx,
  prop 
)     DT_PROP(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop)

#include <zephyr/devicetree.h>

Get a property value from a phandle in a property.

This is a shorthand for:

DT_PROP(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop)

That is, prop is a property of the phandle's node, not a property of node_id.

Example devicetree fragment:

n1: node-1 {
foo = <&n2 &n3>;
};
n2: node-2 {
bar = <42>;
};
n3: node-3 {
baz = <43>;
};

Example usage:

#define N1 DT_NODELABEL(n1)
DT_PROP_BY_PHANDLE_IDX(N1, foo, 0, bar) // 42
DT_PROP_BY_PHANDLE_IDX(N1, foo, 1, baz) // 43
#define DT_PROP_BY_PHANDLE_IDX(node_id, phs, idx, prop)
Get a property value from a phandle in a property.
Definition: devicetree.h:1145
Parameters
node_idnode identifier
phslowercase-and-underscores property with type phandle, phandles, or phandle-array
idxlogical index into phs, which must be zero if phs has type phandle
proplowercase-and-underscores property of the phandle's node
Returns
the property's value

◆ DT_PROP_BY_PHANDLE_IDX_OR

#define DT_PROP_BY_PHANDLE_IDX_OR (   node_id,
  phs,
  idx,
  prop,
  default_value 
)     DT_PROP_OR(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop, default_value)

#include <zephyr/devicetree.h>

Like DT_PROP_BY_PHANDLE_IDX(), but with a fallback to default_value.

If the value exists, this expands to DT_PROP_BY_PHANDLE_IDX(node_id, phs, idx, prop). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
phslowercase-and-underscores property with type phandle, phandles, or phandle-array
idxlogical index into phs, which must be zero if phs has type phandle
proplowercase-and-underscores property of the phandle's node
default_valuea fallback value to expand to
Returns
the property's value

◆ DT_PROP_HAS_IDX

#define DT_PROP_HAS_IDX (   node_id,
  prop,
  idx 
)     IS_ENABLED(DT_CAT6(node_id, _P_, prop, _IDX_, idx, _EXISTS))

#include <zephyr/devicetree.h>

Is index idx valid for an array type property?

If this returns 1, then DT_PROP_BY_IDX(node_id, prop, idx) or DT_PHA_BY_IDX(node_id, prop, idx, ...) are valid at index idx. If it returns 0, it is an error to use those macros with that index.

These properties are handled as special cases:

It is an error to use this macro with the reg or interrupts properties.

Parameters
node_idnode identifier
propa lowercase-and-underscores property with a logical length
idxindex to check
Returns
An expression which evaluates to 1 if idx is a valid index into the given property, and 0 otherwise.

◆ DT_PROP_HAS_NAME

#define DT_PROP_HAS_NAME (   node_id,
  prop,
  name 
)     IS_ENABLED(DT_CAT6(node_id, _P_, prop, _NAME_, name, _EXISTS))

#include <zephyr/devicetree.h>

Is name name available in a foo-names property?

This property is handled as special case:

It is an error to use this macro with the interrupts property.

Example devicetree fragment:

nx: node-x {
foos = <&bar xx yy>, <&baz xx zz>;
foo-names = "event", "error";
status = "okay";
};

Example usage:

DT_PROP_HAS_NAME(nx, foos, event) // 1
DT_PROP_HAS_NAME(nx, foos, failure) // 0
#define DT_PROP_HAS_NAME(node_id, prop, name)
Is name name available in a foo-names property?
Definition: devicetree.h:719
Parameters
node_idnode identifier
propa lowercase-and-underscores prop-names type property
namea lowercase-and-underscores name to check
Returns
An expression which evaluates to 1 if "name" is an available name into the given property, and 0 otherwise.

◆ DT_PROP_LEN

#define DT_PROP_LEN (   node_id,
  prop 
)    DT_CAT4(node_id, _P_, prop, _LEN)

#include <zephyr/devicetree.h>

Get a property's logical length.

Here, "length" is a number of elements, which may differ from the property's size in bytes.

The return value depends on the property's type:

  • for types array, string-array, and uint8-array, this expands to the number of elements in the array
  • for type phandles, this expands to the number of phandles
  • for type phandle-array, this expands to the number of phandle and specifier blocks in the property

These properties are handled as special cases:

It is an error to use this macro with the ranges, dma-ranges, reg or interrupts properties.

For other properties, behavior is undefined.

Parameters
node_idnode identifier
propa lowercase-and-underscores property with a logical length
Returns
the property's length

◆ DT_PROP_LEN_OR

#define DT_PROP_LEN_OR (   node_id,
  prop,
  default_value 
)

#include <zephyr/devicetree.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_PROP_LEN(node_id, prop)), (default_value))
#define DT_PROP_LEN(node_id, prop)
Get a property's logical length.
Definition: devicetree.h:644

Like DT_PROP_LEN(), but with a fallback to default_value.

If the property is defined (as determined by DT_NODE_HAS_PROP()), this expands to DT_PROP_LEN(node_id, prop). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
propa lowercase-and-underscores property with a logical length
default_valuea fallback value to expand to
Returns
the property's length or the given default value

◆ DT_PROP_OR

#define DT_PROP_OR (   node_id,
  prop,
  default_value 
)

#include <zephyr/devicetree.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_PROP(node_id, prop)), (default_value))

Like DT_PROP(), but with a fallback to default_value.

If the value exists, this expands to DT_PROP(node_id, prop). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
default_valuea fallback value to expand to
Returns
the property's value or default_value

◆ DT_STRING_TOKEN

#define DT_STRING_TOKEN (   node_id,
  prop 
)     DT_CAT4(node_id, _P_, prop, _STRING_TOKEN)

#include <zephyr/devicetree.h>

Get a string property's value as a token.

This removes "the quotes" from a string property's value, converting any non-alphanumeric characters to underscores. This can be useful, for example, when programmatically using the value to form a C variable or code.

DT_STRING_TOKEN() can only be used for properties with string type.

It is an error to use DT_STRING_TOKEN() in other circumstances.

Example devicetree fragment:

n1: node-1 {
prop = "foo";
};
n2: node-2 {
prop = "FOO";
}
n3: node-3 {
prop = "123 foo";
};

Example bindings fragment:

properties:
prop:
type: string

Example usage:

DT_STRING_TOKEN(DT_NODELABEL(n1), prop) // foo
DT_STRING_TOKEN(DT_NODELABEL(n2), prop) // FOO
DT_STRING_TOKEN(DT_NODELABEL(n3), prop) // 123_foo
#define DT_STRING_TOKEN(node_id, prop)
Get a string property's value as a token.
Definition: devicetree.h:894

Notice how:

  • Unlike C identifiers, the property values may begin with a number. It's the user's responsibility not to use such values as the name of a C identifier.
  • The uppercased "FOO" in the DTS remains FOO as a token. It is not converted to foo.
  • The whitespace in the DTS "123 foo" string is converted to 123_foo as a token.
Parameters
node_idnode identifier
proplowercase-and-underscores property name
Returns
the value of prop as a token, i.e. without any quotes and with special characters converted to underscores

◆ DT_STRING_TOKEN_BY_IDX

#define DT_STRING_TOKEN_BY_IDX (   node_id,
  prop,
  idx 
)     DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_TOKEN)

#include <zephyr/devicetree.h>

Get an element out of a string-array property as a token.

This removes "the quotes" from an element in the array, and converts non-alphanumeric characters to underscores. That can be useful, for example, when programmatically using the value to form a C variable or code.

DT_STRING_TOKEN_BY_IDX() can only be used for properties with string-array type.

It is an error to use DT_STRING_TOKEN_BY_IDX() in other circumstances.

Example devicetree fragment:

n1: node-1 {
prop = "f1", "F2";
};
n2: node-2 {
prop = "123 foo", "456 FOO";
};

Example bindings fragment:

properties:
prop:
type: string-array

Example usage:

DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 0) // 123_foo
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 1) // 456_FOO
#define DT_STRING_TOKEN_BY_IDX(node_id, prop, idx)
Get an element out of a string-array property as a token.
Definition: devicetree.h:1039

For more information, see DT_STRING_TOKEN.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
idxthe index to get
Returns
the element in prop at index idx as a token

◆ DT_STRING_TOKEN_OR

#define DT_STRING_TOKEN_OR (   node_id,
  prop,
  default_value 
)

#include <zephyr/devicetree.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_STRING_TOKEN(node_id, prop)), (default_value))

Like DT_STRING_TOKEN(), but with a fallback to default_value.

If the value exists, this expands to DT_STRING_TOKEN(node_id, prop). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
default_valuea fallback value to expand to
Returns
the property's value as a token, or default_value

◆ DT_STRING_UPPER_TOKEN

#define DT_STRING_UPPER_TOKEN (   node_id,
  prop 
)     DT_CAT4(node_id, _P_, prop, _STRING_UPPER_TOKEN)

#include <zephyr/devicetree.h>

Like DT_STRING_TOKEN(), but uppercased.

This removes "the quotes" from a string property's value, converting any non-alphanumeric characters to underscores, and capitalizing the result. This can be useful, for example, when programmatically using the value to form a C variable or code.

DT_STRING_UPPER_TOKEN() can only be used for properties with string type.

It is an error to use DT_STRING_UPPER_TOKEN() in other circumstances.

Example devicetree fragment:

n1: node-1 {
prop = "foo";
};
n2: node-2 {
prop = "123 foo";
};

Example bindings fragment:

properties:
prop:
type: string

Example usage:

DT_STRING_UPPER_TOKEN(DT_NODELABEL(n2), prop) // 123_FOO
#define DT_STRING_UPPER_TOKEN(node_id, prop)
Like DT_STRING_TOKEN(), but uppercased.
Definition: devicetree.h:971

Notice how:

  • Unlike C identifiers, the property values may begin with a number. It's the user's responsibility not to use such values as the name of a C identifier.
  • The lowercased "foo" in the DTS becomes FOO as a token, i.e. it is uppercased.
  • The whitespace in the DTS "123 foo" string is converted to 123_FOO as a token, i.e. it is uppercased and whitespace becomes an underscore.
Parameters
node_idnode identifier
proplowercase-and-underscores property name
Returns
the value of prop as an uppercased token, i.e. without any quotes and with special characters converted to underscores

◆ DT_STRING_UPPER_TOKEN_BY_IDX

#define DT_STRING_UPPER_TOKEN_BY_IDX (   node_id,
  prop,
  idx 
)     DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_UPPER_TOKEN)

#include <zephyr/devicetree.h>

Like DT_STRING_TOKEN_BY_IDX(), but uppercased.

This removes "the quotes" and capitalizes an element in the array, and converts non-alphanumeric characters to underscores. That can be useful, for example, when programmatically using the value to form a C variable or code.

DT_STRING_UPPER_TOKEN_BY_IDX() can only be used for properties with string-array type.

It is an error to use DT_STRING_UPPER_TOKEN_BY_IDX() in other circumstances.

Example devicetree fragment:

n1: node-1 {
prop = "f1", "F2";
};
n2: node-2 {
prop = "123 foo", "456 FOO";
};

Example bindings fragment:

properties:
prop:
type: string-array

Example usage:

#define DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx)
Like DT_STRING_TOKEN_BY_IDX(), but uppercased.
Definition: devicetree.h:1089

For more information, see DT_STRING_UPPER_TOKEN.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
idxthe index to get
Returns
the element in prop at index idx as an uppercased token

◆ DT_STRING_UPPER_TOKEN_OR

#define DT_STRING_UPPER_TOKEN_OR (   node_id,
  prop,
  default_value 
)

#include <zephyr/devicetree.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
(DT_STRING_UPPER_TOKEN(node_id, prop)), (default_value))

Like DT_STRING_UPPER_TOKEN(), but with a fallback to default_value.

If the value exists, this expands to DT_STRING_UPPER_TOKEN(node_id, prop). The default_value parameter is not expanded in this case.

Otherwise, this expands to default_value.

Parameters
node_idnode identifier
proplowercase-and-underscores property name
default_valuea fallback value to expand to
Returns
the property's value as an uppercased token, or default_value