Property accessors

Macros
#define	DT_PROP(node_id, prop)
	Get a devicetree property value.
#define	DT_PROP_LEN(node_id, prop)
	Get a property's logical length.
#define	DT_PROP_LEN_OR(node_id, prop, default_value)
	Like DT_PROP_LEN(), but with a fallback to default_value.
#define	DT_PROP_HAS_IDX(node_id, prop, idx)
	Is index idx valid for an array type property?
#define	DT_PROP_HAS_NAME(node_id, prop, name)
	Is name name available in a foo-names property?
#define	DT_PROP_BY_IDX(node_id, prop, idx)
	Get the value at index idx in an array type property.
#define	DT_PROP_OR(node_id, prop, default_value)
	Like DT_PROP(), but with a fallback to default_value.
#define	DT_ENUM_IDX_BY_IDX(node_id, prop, idx)
	Get a property array value's index into its enumeration values.
#define	DT_ENUM_IDX(node_id, prop)
	Equivalent to DT_ENUM_IDX_BY_IDX(node_id, prop, 0).
#define	DT_ENUM_IDX_BY_IDX_OR(node_id, prop, idx, default_idx_value)
	Like DT_ENUM_IDX_BY_IDX(), but with a fallback to a default enum index.
#define	DT_ENUM_IDX_OR(node_id, prop, default_idx_value)
	Equivalent to DT_ENUM_IDX_BY_IDX_OR(node_id, prop, 0, default_idx_value).
#define	DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, idx, value)
	Does a node enumeration property array have a given value?
#define	DT_ENUM_HAS_VALUE(node_id, prop, value)
	Equivalent to DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, 0, value).
#define	DT_STRING_TOKEN(node_id, prop)
	Get a string property's value as a token.
#define	DT_STRING_TOKEN_OR(node_id, prop, default_value)
	Like DT_STRING_TOKEN(), but with a fallback to default_value.
#define	DT_STRING_UPPER_TOKEN(node_id, prop)
	Like DT_STRING_TOKEN(), but uppercased.
#define	DT_STRING_UPPER_TOKEN_OR(node_id, prop, default_value)
	Like DT_STRING_UPPER_TOKEN(), but with a fallback to default_value.
#define	DT_STRING_UNQUOTED(node_id, prop)
	Get a string property's value as an unquoted sequence of tokens.
#define	DT_STRING_UNQUOTED_OR(node_id, prop, default_value)
	Like DT_STRING_UNQUOTED(), but with a fallback to default_value.
#define	DT_STRING_TOKEN_BY_IDX(node_id, prop, idx)
	Get an element out of a string-array property as a token.
#define	DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx)
	Like DT_STRING_TOKEN_BY_IDX(), but uppercased.
#define	DT_STRING_UNQUOTED_BY_IDX(node_id, prop, idx)
	Get a string array item value as an unquoted sequence of tokens.
#define	DT_PROP_BY_PHANDLE_IDX(node_id, phs, idx, prop)
	Get a property value from a phandle in a property.
#define	DT_PROP_BY_PHANDLE_IDX_OR(node_id, phs, idx, prop, default_value)
	Like DT_PROP_BY_PHANDLE_IDX(), but with a fallback to default_value.
#define	DT_PROP_BY_PHANDLE(node_id, ph, prop)
	Get a property value from a phandle's node.
#define	DT_PHA_BY_IDX(node_id, pha, idx, cell)
	Get a phandle-array specifier cell value at an index.
#define	DT_PHA_BY_IDX_OR(node_id, pha, idx, cell, default_value)
	Like DT_PHA_BY_IDX(), but with a fallback to default_value.
#define	DT_PHA(node_id, pha, cell)
	Equivalent to DT_PHA_BY_IDX(node_id, pha, 0, cell)
#define	DT_PHA_OR(node_id, pha, cell, default_value)
	Like DT_PHA(), but with a fallback to default_value.
#define	DT_PHA_BY_NAME(node_id, pha, name, cell)
	Get a value within a phandle-array specifier by name.
#define	DT_PHA_BY_NAME_OR(node_id, pha, name, cell, default_value)
	Like DT_PHA_BY_NAME(), but with a fallback to default_value.
#define	DT_PHANDLE_BY_NAME(node_id, pha, name)
	Get a phandle's node identifier from a phandle array by name.
#define	DT_PHANDLE_BY_IDX(node_id, prop, idx)
	Get a node identifier for a phandle in a property.
#define	DT_PHANDLE(node_id, prop)
	Get a node identifier for a phandle property's value.

Detailed Description

Macro Definition Documentation

DT_ENUM_HAS_VALUE

#define DT_ENUM_HAS_VALUE	(		node_id,
			prop,
			value )

#include <zephyr/devicetree.h>

Value:

        DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, 0, value)

Equivalent to DT_ENUM_HAS_VALUE_BY_IDX(node_id, prop, 0, value).

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
value	lowercase-and-underscores enumeration value

Returns

1 if the node property has the value value, 0 otherwise.

DT_ENUM_HAS_VALUE_BY_IDX

#define DT_ENUM_HAS_VALUE_BY_IDX	(		node_id,
			prop,
			idx,
			value )

#include <zephyr/devicetree.h>

Value:

        IS_ENABLED(DT_CAT8(node_id, _P_, prop, _IDX_, idx, _ENUM_VAL_, value, _EXISTS))

Does a node enumeration property array have a given value?

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the index to get
value	lowercase-and-underscores enumeration value

Returns

1 if the node property has the value value, 0 otherwise.

DT_ENUM_IDX

#define DT_ENUM_IDX	(		node_id,
			prop )

#include <zephyr/devicetree.h>

Value:

DT_ENUM_IDX_BY_IDX(node_id, prop, 0)

Equivalent to DT_ENUM_IDX_BY_IDX(node_id, prop, 0).

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name

Returns

zero-based index of the property's value in its enum: list

DT_ENUM_IDX_BY_IDX

#define DT_ENUM_IDX_BY_IDX	(		node_id,
			prop,
			idx )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, prop, _IDX_, idx, _ENUM_IDX)

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

The return values start at zero.

Example devicetree fragment:

some_node: some-node {
    compat = "vend,enum-string-array";
    foos =
        <&phandle val1>,
        <&phandle val2>,
        <&phandle val3>;
    foo-names = "default", "option3", "option1";
};

Example bindings fragment:

compatible: vend,enum-string-array
properties:
  foos:
    type: phandle-array
    description: |
      Explanation about what this phandle-array exactly is for.
 
  foo-names:
    type: string-array
    description: |
      Some explanation about the available options
      default: explain default
      option1: explain option1
      option2: explain option2
      option3: explain option3
    enum:
      - default
      - option1
      - option2
      - option3

Example usage:

DT_ENUM_IDX_BY_IDX(DT_NODELABEL(some_node), foo_names, 0) // 0
DT_ENUM_IDX_BY_IDX(DT_NODELABEL(some_node), foo_names, 2) // 1

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the index to get

Returns

zero-based index of the property's value in its enum: list

DT_ENUM_IDX_BY_IDX_OR

#define DT_ENUM_IDX_BY_IDX_OR	(		node_id,
			prop,
			idx,
			default_idx_value )

#include <zephyr/devicetree.h>

Value:

        COND_CODE_1(DT_PROP_HAS_IDX(node_id, prop, idx), \
                    (DT_ENUM_IDX_BY_IDX(node_id, prop, idx)), (default_idx_value))

Like DT_ENUM_IDX_BY_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_BY_IDX(node_id, prop, idx).

Otherwise, this expands to provided default index enum value.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the index to get
default_idx_value	a 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_ENUM_IDX_OR

#define DT_ENUM_IDX_OR	(		node_id,
			prop,
			default_idx_value )

#include <zephyr/devicetree.h>

Value:

        DT_ENUM_IDX_BY_IDX_OR(node_id, prop, 0, default_idx_value)

Equivalent to DT_ENUM_IDX_BY_IDX_OR(node_id, prop, 0, default_idx_value).

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
default_idx_value	a 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_PHA

#define DT_PHA	(		node_id,
			pha,
			cell )

#include <zephyr/devicetree.h>

Value:

DT_PHA_BY_IDX(node_id, pha, 0, cell)

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

Parameters

node_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
cell	lowercase-and-underscores cell name

Returns

the cell's value

DT_PHA_BY_IDX

#define DT_PHA_BY_IDX	(		node_id,
			pha,
			idx,
			cell )

#include <zephyr/devicetree.h>

Value:

        DT_CAT7(node_id, _P_, pha, _IDX_, idx, _VAL_, cell)

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

Parameters

node_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
idx	logical index into pha
cell	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_PROP_OR(node_id, DT_CAT5(pha, _IDX_, idx, _VAL_, cell), default_value)

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_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
idx	logical index into pha
cell	lowercase-and-underscores cell name within the specifier at pha index idx
default_value	a 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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT7(node_id, _P_, pha, _NAME_, name, _VAL_, cell)

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

Parameters

node_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
name	lowercase-and-underscores name of a specifier in pha
cell	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_PROP_OR(node_id, DT_CAT5(pha, _NAME_, name, _VAL_, cell), default_value)

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_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
name	lowercase-and-underscores name of a specifier in pha
cell	lowercase-and-underscores cell name in the named specifier
default_value	a 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 )

#include <zephyr/devicetree.h>

Value:

        DT_PHA_BY_IDX_OR(node_id, pha, 0, cell, default_value)

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_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
cell	lowercase-and-underscores cell name
default_value	a fallback value to expand to

Returns

the cell's value or default_value

DT_PHANDLE

#define DT_PHANDLE	(		node_id,
			prop )

#include <zephyr/devicetree.h>

Value:

DT_PHANDLE_BY_IDX(node_id, prop, 0)

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_id	node identifier
prop	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, prop, _IDX_, idx, _PH)

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

Behavior is analogous for phandle-arrays.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name in node_id with type phandle, phandles or phandle-array
idx	index 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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, pha, _NAME_, name, _PH)

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"

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

Parameters

node_id	node identifier
pha	lowercase-and-underscores property with type phandle-array
name	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

DT_CAT3(node_id, _P_, prop)

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_id	node identifier
prop	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT5(node_id, _P_, prop, _IDX_, idx)

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].

The return value depends on the property's type:

• for types array, string-array, uint8-array, and phandles, this expands to the idx-th array element as an integer, string literal, integer, and node identifier respectively
• for type phandle, idx must be 0 and the expansion is a node identifier (this treats phandle like a phandles of length 1)
• for type string, idx must be 0 and the expansion is the entire string (this treats string like string-array of length 1)

These properties are handled as special cases:

• reg: use DT_REG_ADDR_BY_IDX() or DT_REG_SIZE_BY_IDX() instead
• interrupts: use DT_IRQ_BY_IDX()
• ranges: use DT_NUM_RANGES()
• dma-ranges: it is an error to use this property with DT_PROP_BY_IDX()

For properties of other types, behavior is undefined.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the 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 )

#include <zephyr/devicetree.h>

Value:

        DT_PROP_BY_PHANDLE_IDX(node_id, ph, 0, prop)

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_id	node identifier
ph	lowercase-and-underscores property of node_id with type phandle
prop	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

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

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

Parameters

node_id	node identifier
phs	lowercase-and-underscores property with type phandle, phandles, or phandle-array
idx	logical index into phs, which must be zero if phs has type phandle
prop	lowercase-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 )

#include <zephyr/devicetree.h>

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.

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_id	node identifier
phs	lowercase-and-underscores property with type phandle, phandles, or phandle-array
idx	logical index into phs, which must be zero if phs has type phandle
prop	lowercase-and-underscores property of the phandle's node
default_value	a fallback value to expand to

Returns

the property's value

DT_PROP_HAS_IDX

#define DT_PROP_HAS_IDX	(		node_id,
			prop,
			idx )

#include <zephyr/devicetree.h>

Value:

        IS_ENABLED(DT_CAT6(node_id, _P_, prop, _IDX_, idx, _EXISTS))

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:

• reg property: use DT_REG_HAS_IDX(node_id, idx) instead
• interrupts property: use DT_IRQ_HAS_IDX(node_id, idx) instead

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

Parameters

node_id	node identifier
prop	a lowercase-and-underscores property with a logical length
idx	index 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 )

#include <zephyr/devicetree.h>

Value:

        IS_ENABLED(DT_CAT6(node_id, _P_, prop, _NAME_, name, _EXISTS))

Is name name available in a foo-names property?

This property is handled as special case:

• interrupts property: use DT_IRQ_HAS_NAME(node_id, idx) instead

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(DT_NODELABEL(nx), foos, event)    // 1
DT_PROP_HAS_NAME(DT_NODELABEL(nx), foos, failure)  // 0

Parameters

node_id	node identifier
prop	a lowercase-and-underscores prop-names type property
name	a 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 )

#include <zephyr/devicetree.h>

Value:

DT_CAT4(node_id, _P_, prop, _LEN)

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
• for type phandle, this expands to 1 (so that a phandle can be treated as a degenerate case of phandles with length 1)
• for type string, this expands to 1 (so that a string can be treated as a degenerate case of string-array with length 1)

These properties are handled as special cases:

• reg property: use DT_NUM_REGS(node_id) instead
• interrupts property: use DT_NUM_IRQS(node_id) instead

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_id	node identifier
prop	a 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))

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_id	node identifier
prop	a lowercase-and-underscores property with a logical length
default_value	a 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_id	node identifier
prop	lowercase-and-underscores property name
default_value	a fallback value to expand to

Returns

the property's value or default_value

DT_STRING_TOKEN

#define DT_STRING_TOKEN	(		node_id,
			prop )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _STRING_TOKEN)

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

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_id	node identifier
prop	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_TOKEN)

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(n1), prop, 0) // f1
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n1), prop, 1) // F2
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 0) // 123_foo
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 1) // 456_FOO

For more information, see DT_STRING_TOKEN.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the 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_id	node identifier
prop	lowercase-and-underscores property name
default_value	a fallback value to expand to

Returns

the property's value as a token, or default_value

DT_STRING_UNQUOTED

#define DT_STRING_UNQUOTED	(		node_id,
			prop )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _STRING_UNQUOTED)

Get a string property's value as an unquoted sequence of tokens.

This removes "the quotes" from string-valued properties. That can be useful, for example, when defining floating point values as a string in devicetree that you would like to use to initialize a float or double variable in C.

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

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

Example devicetree fragment:

n1: node-1 {
        prop = "12.7";
};
n2: node-2 {
        prop = "0.5";
}
n3: node-3 {
        prop = "A B C";
};

Example bindings fragment:

properties:
  prop:
    type: string

Example usage:

DT_STRING_UNQUOTED(DT_NODELABEL(n1), prop) // 12.7
DT_STRING_UNQUOTED(DT_NODELABEL(n2), prop) // 0.5
DT_STRING_UNQUOTED(DT_NODELABEL(n3), prop) // A B C

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name

Returns

the property's value as a sequence of tokens, with no quotes

DT_STRING_UNQUOTED_BY_IDX

#define DT_STRING_UNQUOTED_BY_IDX	(		node_id,
			prop,
			idx )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_UNQUOTED)

Get a string array item value as an unquoted sequence of tokens.

This removes "the quotes" from string-valued item. That can be useful, for example, when defining floating point values as a string in devicetree that you would like to use to initialize a float or double variable in C.

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

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

Example devicetree fragment:

n1: node-1 {
        prop = "12.7", "34.1";
};
n2: node-2 {
        prop = "A B", "C D";
}

Example bindings fragment:

properties:
  prop:
    type: string-array

Example usage:

DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n1), prop, 0) // 12.7
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n1), prop, 1) // 34.1
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n2), prop, 0) // A B
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n2), prop, 1) // C D

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the index to get

Returns

the property's value as a sequence of tokens, with no quotes

DT_STRING_UNQUOTED_OR

#define DT_STRING_UNQUOTED_OR	(		node_id,
			prop,
			default_value )

#include <zephyr/devicetree.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
                (DT_STRING_UNQUOTED(node_id, prop)), (default_value))

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

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

Otherwise, this expands to default_value.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
default_value	a fallback value to expand to

Returns

the property's value as a sequence of tokens, with no quotes, or default_value

DT_STRING_UPPER_TOKEN

#define DT_STRING_UPPER_TOKEN	(		node_id,
			prop )

#include <zephyr/devicetree.h>

Value:

        DT_CAT4(node_id, _P_, prop, _STRING_UPPER_TOKEN)

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(n1), prop) // FOO
DT_STRING_UPPER_TOKEN(DT_NODELABEL(n2), prop) // 123_FOO

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_id	node identifier
prop	lowercase-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 )

#include <zephyr/devicetree.h>

Value:

        DT_CAT6(node_id, _P_, prop, _IDX_, idx, _STRING_UPPER_TOKEN)

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:

DT_STRING_UPPER_TOKEN_BY_IDX(DT_NODELABEL(n1), prop, 0) // F1
DT_STRING_UPPER_TOKEN_BY_IDX(DT_NODELABEL(n1), prop, 1) // F2
DT_STRING_UPPER_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 0) // 123_FOO
DT_STRING_UPPER_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 1) // 456_FOO

For more information, see DT_STRING_UPPER_TOKEN.

Parameters

node_id	node identifier
prop	lowercase-and-underscores property name
idx	the 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_id	node identifier
prop	lowercase-and-underscores property name
default_value	a fallback value to expand to

Returns

the property's value as an uppercased token, or default_value