Devicetree API

This is a reference page for the <devicetree.h> API. The API is macro based. Use of these macros has no impact on scheduling. They can be used from any calling context and at file scope.

Some of these require a special macro named DT_DRV_COMPAT to be defined before they can be used; these are discussed individually below. These macros are generally meant for use within device drivers, though they can be used outside of drivers with appropriate care.

Generic APIs

The APIs in this section can be used anywhere and do not require DT_DRV_COMPAT to be defined.

Node identifiers and helpers

A node identifier is a way to refer to a devicetree node at C preprocessor time. While node identifiers are not C values, you can use them to access devicetree data in C rvalue form using, for example, the Property access API.

The root node / has node identifier DT_ROOT. You can create node identifiers for other devicetree nodes using DT_PATH(), DT_NODELABEL(), DT_ALIAS(), and DT_INST().

There are also DT_PARENT() and DT_CHILD() macros which can be used to create node identifiers for a given node’s parent node or a particular child node, respectively.

The following macros create or operate on node identifiers.

group devicetree-generic-id

Defines

DT_ROOT

Node identifier for the root node in the devicetree.

DT_PATH(...)

Get a node identifier for a devicetree path.

(This macro returns a node identifier from path components. To get a path string from a node identifier, use DT_NODE_PATH() instead.)

The arguments to this macro are the names of non-root nodes in the tree required to reach the desired node, starting from the root. Non-alphanumeric characters in each name must be converted to underscores to form valid C tokens, and letters must be lowercased.

Example devicetree fragment:

/ {
        soc {
                serial1: serial@40001000 {
                        status = "okay";
                        current-speed = <115200>;
                        ...
                };
        };
};

You can use DT_PATH(soc, serial_40001000) to get a node identifier for the serial@40001000 node. Node labels like “serial1” cannot be used as DT_PATH() arguments; use DT_NODELABEL() for those instead.

Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_PATH(soc, serial_40001000), current_speed) // 115200

(The current-speed property is also in “lowercase-and-underscores” form when used with this API.)

When determining arguments to DT_PATH():

• the first argument corresponds to a child node of the root (“soc” above)

• a second argument corresponds to a child of the first argument (“serial_40001000” above, from the node name “serial@40001000” after lowercasing and changing “@” to “_”)

• and so on for deeper nodes in the desired node’s path

Return

node identifier for the node with that path

Parameters

• ...: lowercase-and-underscores node names along the node’s path, with each name given as a separate argument

DT_NODELABEL(label)

Get a node identifier for a node label.

Convert non-alphanumeric characters in the node label to underscores to form valid C tokens, and lowercase all letters. Note that node labels are not the same thing as label properties.

Example devicetree fragment:

serial1: serial@40001000 {
        label = "UART_0";
        status = "okay";
        current-speed = <115200>;
        ...
};

The only node label in this example is “serial1”.

The string “UART_0” is not a node label; it’s the value of a property named label.

You can use DT_NODELABEL(serial1) to get a node identifier for the serial@40001000 node. Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_NODELABEL(serial1), current_speed) // 115200

Another example devicetree fragment:

cpu@0 {
       L2_0: l2-cache {
               cache-level = <2>;
               ...
       };
};

Example usage to get the cache-level property:

DT_PROP(DT_NODELABEL(l2_0), cache_level) // 2

Notice how “L2_0” in the devicetree is lowercased to “l2_0” in the DT_NODELABEL() argument.

Return

node identifier for the node with that label

Parameters

• label: lowercase-and-underscores node label name

DT_ALIAS(alias)

Get a node identifier from /aliases.

This macro’s argument is a property of the /aliases node. It returns a node identifier for the node which is aliased. Convert non-alphanumeric characters in the alias property to underscores to form valid C tokens, and lowercase all letters.

Example devicetree fragment:

/ {
        aliases {
                my-serial = &serial1;
        };

        soc {
                serial1: serial@40001000 {
                        status = "okay";
                        current-speed = <115200>;
                        ...
                };
        };
};

You can use DT_ALIAS(my_serial) to get a node identifier for the serial@40001000 node. Notice how my-serial in the devicetree becomes my_serial in the DT_ALIAS() argument. Example usage with DT_PROP() to get the current-speed property:

DT_PROP(DT_ALIAS(my_serial), current_speed) // 115200

Return

node identifier for the node with that alias

Parameters

• alias: lowercase-and-underscores alias name.

DT_INST(inst, compat)

Get a node identifier for an instance of a compatible.

All nodes with a particular compatible property value are assigned instance numbers, which are zero-based indexes specific to that compatible. You can get a node identifier for these nodes by passing DT_INST() an instance number, “inst”, along with the lowercase-and-underscores version of the compatible, “compat”.

Instance numbers have the following properties:

• for each compatible, instance numbers start at 0 and are contiguous

• exactly one instance number is assigned for each node with a compatible, including disabled nodes

• enabled nodes (status property is “okay” or missing) are assigned the instance numbers starting from 0, and disabled nodes have instance numbers which are greater than those of any enabled node

No other guarantees are made. In particular:

• instance numbers in no way reflect any numbering scheme that might exist in SoC documentation, node labels or unit addresses, or properties of the /aliases node (use DT_NODELABEL() or DT_ALIAS() for those)

• there is no general guarantee that the same node will have the same instance number between builds, even if you are building the same application again in the same build directory

Example devicetree fragment:

serial1: serial@40001000 {
        compatible = "vnd,soc-serial";
        status = "disabled";
        current-speed = <9600>;
        ...
};

serial2: serial@40002000 {
        compatible = "vnd,soc-serial";
        status = "okay";
        current-speed = <57600>;
        ...
};

serial3: serial@40003000 {
        compatible = "vnd,soc-serial";
        current-speed = <115200>;
        ...
};

Assuming no other nodes in the devicetree have compatible “vnd,soc-serial”, that compatible has nodes with instance numbers 0, 1, and 2.

The nodes serial@40002000 and serial@40003000 are both enabled, so their instance numbers are 0 and 1, but no guarantees are made regarding which node has which instance number.

Since serial@40001000 is the only disabled node, it has instance number 2, since disabled nodes are assigned the largest instance numbers. Therefore:

// Could be 57600 or 115200. There is no way to be sure:
// either serial@40002000 or serial@40003000 could
// have instance number 0, so this could be the current-speed
// property of either of those nodes.
DT_PROP(DT_INST(0, vnd_soc_serial), current_speed)

// Could be 57600 or 115200, for the same reason.
// If the above expression expands to 57600, then
// this expands to 115200, and vice-versa.
DT_PROP(DT_INST(1, vnd_soc_serial), current_speed)

// 9600, because there is only one disabled node, and
// disabled nodes are "at the the end" of the instance
// number "list".
DT_PROP(DT_INST(2, vnd_soc_serial), current_speed)

Notice how “vnd,soc-serial” in the devicetree becomes vnd_soc_serial (without quotes) in the DT_INST() arguments. (As usual, current-speed in the devicetree becomes current_speed as well.)

Nodes whose “compatible” property has multiple values are assigned independent instance numbers for each compatible.

Return

node identifier for the node with that instance number and compatible

Parameters

• inst: instance number for compatible “compat”

• compat: lowercase-and-underscores compatible, without quotes

DT_PARENT(node_id)

Get a node identifier for a parent node.

Example devicetree fragment:

parent: parent-node {
        child: child-node {
                ...
        };
};

The following are equivalent ways to get the same node identifier:

DT_NODELABEL(parent)
DT_PARENT(DT_NODELABEL(child))

Return

a node identifier for the node’s parent

Parameters

• node_id: node identifier

DT_GPARENT(node_id)

Get a node identifier for a grandparent node.

Example devicetree fragment:

gparent: grandparent-node {
        parent: parent-node {
                child: child-node { ... }
        };
};

The following are equivalent ways to get the same node identifier:

DT_GPARENT(DT_NODELABEL(child))
DT_PARENT(DT_PARENT(DT_NODELABEL(child))

Return

a node identifier for the node’s parent’s parent

Parameters

• node_id: node identifier

DT_CHILD(node_id, child)

Get a node identifier for a child node.

Example devicetree fragment:

/ {
        soc-label: soc {
                serial1: serial@40001000 {
                        status = "okay";
                        current-speed = <115200>;
                        ...
                };
        };
};

Example usage with DT_PROP() to get the status of the serial@40001000 node:

#define SOC_NODE DT_NODELABEL(soc_label)
DT_PROP(DT_CHILD(SOC_NODE, serial_40001000), status) // "okay"

Node labels like “serial1” cannot be used as the “child” argument to this macro. Use DT_NODELABEL() for that instead.

You can also use DT_FOREACH_CHILD() to iterate over node identifiers for all of a node’s children.

Return

node identifier for the node with the name referred to by ‘child’

Parameters

• node_id: node identifier

• child: lowercase-and-underscores child node name

DT_NODE_PATH(node_id)

Get a devicetree node’s full path as a string literal.

This returns the path to a node from a node identifier. To get a node identifier from path components instead, use DT_PATH().

Example devicetree fragment:

/ {
        soc {
                node: my-node@12345678 { ... };
        };
};

Example usage:

DT_NODE_PATH(DT_NODELABEL(node)) // “/soc/my-node@12345678” DT_NODE_PATH(DT_PATH(soc)) // “/soc” DT_NODE_PATH(DT_ROOT) // “/”

Return

the node’s full path in the devicetree

Parameters

• node_id: node identifier

DT_SAME_NODE(node_id1, node_id2)

Do node_id1 and node_id2 refer to the same node?

Both “node_id1” and “node_id2” must be node identifiers for nodes that exist in the devicetree (if unsure, you can check with DT_NODE_EXISTS()).

The expansion evaluates to 0 or 1, but may not be a literal integer 0 or 1.

Return

an expression that evaluates to 1 if the node identifiers refer to the same node, and evaluates to 0 otherwise

Parameters

• node_id1: first node identifer

• node_id2: second node identifier

Property access

The following general-purpose macros can be used to access node properties. There are special-purpose APIs for accessing the reg property and interrupts property.

Property values can be read using these macros even if the node is disabled, as long as it has a matching binding.

group devicetree-generic-prop

Defines

DT_PROP(node_id, 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” and “label” have 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.

Return

a representation of the property’s value

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

DT_PROP_LEN(node_id, prop)

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:

• 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 reg or interrupts properties.

For other properties, behavior is undefined.

Return

the property’s length

Parameters

• node_id: node identifier

• prop: a lowercase-and-underscores property with a logical length

DT_PROP_LEN_OR(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.

Return

the property’s length or the given 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

DT_PROP_HAS_IDX(node_id, prop, idx)

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.

Return

An expression which evaluates to 1 if “idx” is a valid index into the given property, and 0 otherwise.

Parameters

• node_id: node identifier

• prop: a lowercase-and-underscores property with a logical length

• idx: index to check

DT_PROP_BY_IDX(node_id, prop, 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]”.

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:

• reg property: use DT_REG_ADDR_BY_IDX() or DT_REG_SIZE_BY_IDX() instead

• interrupts property: use DT_IRQ_BY_IDX() instead

For non-array properties, behavior is undefined.

Return

a representation of the idx-th element of the property

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

• idx: the index to get

DT_PROP_OR(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.

Return

the property’s value or default_value

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

• default_value: a fallback value to expand to

DT_LABEL(node_id)

Equivalent to DT_PROP(node_id, label)

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

Return

node’s label property value

Parameters

• node_id: node identifier

DT_ENUM_IDX(node_id, prop)

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

Return

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

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

DT_ENUM_IDX_OR(node_id, prop, default_idx_value)

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.

Return

zero-based index of the property’s value in its enum if present, default_idx_value ohterwise

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

• default_idx_value: a fallback index value to expand to

DT_ENUM_TOKEN(node_id, prop)

Get an enumeration property’s value as a token.

This allows you to “remove the quotes” from some string-valued properties. That can be useful, for example, when pasting the values onto some other token to form an enum in C using the ## preprocessor operator.

DT_ENUM_TOKEN() can only be used for properties with string type whose binding has an “enum:”. The values in the binding’s “enum:” list must be unique after converting non-alphanumeric characters to underscores.

It is an error to use DT_ENUM_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
    enum:
       - "foo"
       - "FOO"
       - "123 foo"

Example usage:

DT_ENUM_TOKEN((DT_NODELABEL(n1), prop) // foo
DT_ENUM_TOKEN((DT_NODELABEL(n2), prop) // FOO
DT_ENUM_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.

Return

the value of prop as a token, i.e. without any quotes and with special characters converted to underscores

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name with suitable enumeration of values in its binding

DT_ENUM_UPPER_TOKEN(node_id, prop)

Like DT_ENUM_TOKEN(), but uppercased.

This allows you to “remove the quotes and capitalize” some string-valued properties.

DT_ENUM_UPPER_TOKEN() can only be used for properties with string type whose binding has an “enum:”. The values in the binding’s “enum:” list must be unique after converting non-alphanumeric characters to underscores and capitalizating any letters.

It is an error to use DT_ENUM_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
    enum:
       - "foo"
       - "123 foo"

Example usage:

DT_ENUM_TOKEN((DT_NODELABEL(n1), prop) // FOO
DT_ENUM_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.

Return

the value of prop as a capitalized token, i.e. upper case, without any quotes, and with special characters converted to underscores

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name with suitable enumeration of values in its binding

DT_PROP_BY_PHANDLE_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

Return

the property’s 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

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.

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.

Return

the property’s 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

DT_PROP_BY_PHANDLE(node_id, ph, prop)

Get a property value from a phandle’s node.

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

Return

the property’s value

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

DT_PHA_BY_IDX(node_id, pha, idx, 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@... {
        #gpio-cells = <2>;
};

gpio1: gpio@... {
        #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

Return

the cell’s 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”

DT_PHA_BY_IDX_OR(node_id, pha, idx, 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.

Return

the cell’s value or “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

DT_PHA(node_id, pha, cell)

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

Return

the cell’s value

Parameters

• node_id: node identifier

• pha: lowercase-and-underscores property with type “phandle-array”

• cell: lowercase-and-underscores cell name

DT_PHA_OR(node_id, pha, 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.

Return

the cell’s value or 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

DT_PHA_BY_NAME(node_id, pha, name, 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

Return

the cell’s 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

DT_PHA_BY_NAME_OR(node_id, pha, name, 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.

Return

the cell’s value or 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

DT_PHANDLE_BY_NAME(node_id, pha, name)

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@... {
        label = "ADC_1";
};

adc2: adc@... {
        label = "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_LABEL(DT_PHANDLE_BY_NAME(NODE, io_channels, sensor))  // "ADC_1"
DT_LABEL(DT_PHANDLE_BY_NAME(NODE, io_channels, bandgap)) // "ADC_2"

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

Return

a node identifier for the node with that phandle

Parameters

• node_id: node identifier

• pha: lowercase-and-underscores property with type “phandle-array”

• name: lowercase-and-underscores name of an element in “pha”

DT_PHANDLE_BY_IDX(node_id, prop, idx)

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.

Return

node identifier for the node with the phandle at that index

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”

DT_PHANDLE(node_id, prop)

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

Return

a node identifier for the node pointed to by “ph”

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property of “node_id” with type “phandle”

reg property

Use these APIs instead of Property access to access the reg property. Because this property’s semantics are defined by the devicetree specification, these macros can be used even for nodes without matching bindings.

group devicetree-reg-prop

Defines

DT_NUM_REGS(node_id)

Get the number of register blocks in the reg property.

Use this instead of DT_PROP_LEN(node_id, reg).

Return

Number of register blocks in the node’s “reg” property.

Parameters

• node_id: node identifier

DT_REG_HAS_IDX(node_id, idx)

Is “idx” a valid register block index?

If this returns 1, then DT_REG_ADDR_BY_IDX(node_id, idx) or DT_REG_SIZE_BY_IDX(node_id, idx) are valid. If it returns 0, it is an error to use those macros with index “idx”.

Return

1 if “idx” is a valid register block index, 0 otherwise.

Parameters

• node_id: node identifier

• idx: index to check

DT_REG_ADDR_BY_IDX(node_id, idx)

Get the base address of the register block at index “idx”.

Return

address of the idx-th register block

Parameters

• node_id: node identifier

• idx: index of the register whose address to return

DT_REG_SIZE_BY_IDX(node_id, idx)

Get the size of the register block at index “idx”.

This is the size of an individual register block, not the total number of register blocks in the property; use DT_NUM_REGS() for that.

Return

size of the idx-th register block

Parameters

• node_id: node identifier

• idx: index of the register whose size to return

DT_REG_ADDR(node_id)

Get a node’s (only) register block address.

Equivalent to DT_REG_ADDR_BY_IDX(node_id, 0).

Return

node’s register block address

Parameters

• node_id: node identifier

DT_REG_SIZE(node_id)

Get a node’s (only) register block size.

Equivalent to DT_REG_SIZE_BY_IDX(node_id, 0).

Return

node’s only register block’s size

Parameters

• node_id: node identifier

DT_REG_ADDR_BY_NAME(node_id, name)

Get a register block’s base address by name.

Return

address of the register block specified by name

Parameters

• node_id: node identifier

• name: lowercase-and-underscores register specifier name

DT_REG_SIZE_BY_NAME(node_id, name)

Get a register block’s size by name.

Return

size of the register block specified by name

Parameters

• node_id: node identifier

• name: lowercase-and-underscores register specifier name

interrupts property

Use these APIs instead of Property access to access the interrupts property.

Because this property’s semantics are defined by the devicetree specification, some of these macros can be used even for nodes without matching bindings. This does not apply to macros which take cell names as arguments.

group devicetree-interrupts-prop

Defines

DT_NUM_IRQS(node_id)

Get the number of interrupt sources for the node.

Use this instead of DT_PROP_LEN(node_id, interrupts).

Return

Number of interrupt specifiers in the node’s “interrupts” property.

Parameters

• node_id: node identifier

DT_IRQ_HAS_IDX(node_id, idx)

Is “idx” a valid interrupt index?

If this returns 1, then DT_IRQ_BY_IDX(node_id, idx) is valid. If it returns 0, it is an error to use that macro with this index.

Return

1 if the idx is valid for the interrupt property 0 otherwise.

Parameters

• node_id: node identifier

• idx: index to check

DT_IRQ_HAS_CELL_AT_IDX(node_id, idx, cell)

Does an interrupts property have a named cell specifier at an index? If this returns 1, then DT_IRQ_BY_IDX(node_id, idx, cell) is valid. If it returns 0, it is an error to use that macro.

Return

1 if the named cell exists in the interrupt specifier at index idx 0 otherwise.

Parameters

• node_id: node identifier

• idx: index to check

• cell: named cell value whose existence to check

DT_IRQ_HAS_CELL(node_id, cell)

Equivalent to DT_IRQ_HAS_CELL_AT_IDX(node_id, 0, cell)

Return

1 if the named cell exists in the interrupt specifier at index 0 0 otherwise.

Parameters

• node_id: node identifier

• cell: named cell value whose existence to check

DT_IRQ_HAS_NAME(node_id, name)

Does an interrupts property have a named specifier value at an index? If this returns 1, then DT_IRQ_BY_NAME(node_id, name, cell) is valid. If it returns 0, it is an error to use that macro.

Return

1 if “name” is a valid named specifier 0 otherwise.

Parameters

• node_id: node identifier

• name: lowercase-and-underscores interrupt specifier name

DT_IRQ_BY_IDX(node_id, idx, cell)

Get a value within an interrupt specifier at an index.

It might help to read the argument order as being similar to “node->interrupts[index].cell”.

This can be used to get information about an individual interrupt when a device generates more than one.

Example devicetree fragment:

my-serial: serial@... {
        interrupts = < 33 0 >, < 34 1 >;
};

Assuming the node’s interrupt domain has “#interrupt-cells = <2>;” and the individual cells in each interrupt specifier are named “irq” and “priority” by the node’s binding, here are some examples:

#define SERIAL DT_NODELABEL(my_serial)

Example usage                       Value
-------------                       -----
DT_IRQ_BY_IDX(SERIAL, 0, irq)          33
DT_IRQ_BY_IDX(SERIAL, 0, priority)      0
DT_IRQ_BY_IDX(SERIAL, 1, irq,          34
DT_IRQ_BY_IDX(SERIAL, 1, priority)      1

Return

the named value at the specifier given by the index

Parameters

• node_id: node identifier

• idx: logical index into the interrupt specifier array

• cell: cell name specifier

DT_IRQ_BY_NAME(node_id, name, cell)

Get a value within an interrupt specifier by name.

It might help to read the argument order as being similar to “node->interrupts.name.cell”.

This can be used to get information about an individual interrupt when a device generates more than one, if the bindings give each interrupt specifier a name.

Return

the named value at the specifier given by the index

Parameters

• node_id: node identifier

• name: lowercase-and-underscores interrupt specifier name

• cell: cell name specifier

DT_IRQ(node_id, cell)

Get an interrupt specifier’s value Equivalent to DT_IRQ_BY_IDX(node_id, 0, cell).

Return

the named value at that index

Parameters

• node_id: node identifier

• cell: cell name specifier

DT_IRQN(node_id)

Get a node’s (only) irq number.

Equivalent to DT_IRQ(node_id, irq). This is provided as a convenience for the common case where a node generates exactly one interrupt, and the IRQ number is in a cell named “irq”.

Return

the interrupt number for the node’s only interrupt

Parameters

• node_id: node identifier

For-each macros

There is currently only one “generic” for-each macro, DT_FOREACH_CHILD(), which allows iterating over the children of a devicetree node.

There are special-purpose for-each macros, like DT_INST_FOREACH_STATUS_OKAY(), but these require DT_DRV_COMPAT to be defined before use.

group devicetree-generic-foreach

Defines

DT_FOREACH_CHILD(node_id, 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”.

Example devicetree fragment:

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

Example usage:

#define LABEL_AND_COMMA(node_id) DT_LABEL(node_id),

const char *child_labels[] = {
    DT_FOREACH_CHILD(DT_NODELABEL(n), LABEL_AND_COMMA)
};

This expands to:

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

Parameters

• node_id: node identifier

• fn: macro to invoke

Existence checks

This section documents miscellaneous macros that can be used to test if a node exists, how many nodes of a certain type exist, whether a node has certain properties, etc. Some macros used for special purposes (such as DT_IRQ_HAS_IDX() and all macros which require DT_DRV_COMPAT) are documented elsewhere on this page.

group devicetree-generic-exist

Defines

DT_NODE_EXISTS(node_id)

Does a node identifier refer to a node?

Tests whether a node identifier refers to a node which exists, i.e. is defined in the devicetree.

It doesn’t matter whether or not the node has a matching binding, or what the node’s status value is. This is purely a check of whether the node exists at all.

Return

1 if the node identifier refers to a node, 0 otherwise.

Parameters

• node_id: a node identifier

DT_NODE_HAS_STATUS(node_id, status)

Does a node identifier refer to a node with a status?

Example uses:

DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), okay)
DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), disabled)

Tests whether a node identifier refers to a node which:

• exists in the devicetree, and

• has a status property matching the second argument (except that either a missing status or an “ok” status in the devicetree is treated as if it were “okay” instead)

Return

1 if the node has the given status, 0 otherwise.

Parameters

• node_id: a node identifier

• status: a status as one of the tokens okay or disabled, not a string

DT_HAS_COMPAT_STATUS_OKAY(compat)

Does the devicetree have a status “okay” node with a compatible?

Test for whether the devicetree has any nodes with status “okay” and the given compatible. That is, this returns 1 if and only if there is at least one “node_id” for which both of these expressions return 1:

DT_NODE_HAS_STATUS(node_id, okay)
DT_NODE_HAS_COMPAT(node_id, compat)

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

Return

1 if both of the above conditions are met, 0 otherwise

Parameters

• compat: lowercase-and-underscores version of a compatible

DT_NUM_INST_STATUS_OKAY(compat)

Get the number of instances of a given compatible with status “okay”.

Return

Number of instances with status “okay”

Parameters

• compat: lowercase-and-underscores version of a compatible

DT_NODE_HAS_COMPAT(node_id, compat)

Does a devicetree node match a compatible?

Example devicetree fragment:

n: node {
        compatible = "vnd,specific-device", "generic-device";
}

Example usages which evaluate to 1:

DT_NODE_HAS_COMPAT(DT_NODELABEL(n), vnd_specific_device)
DT_NODE_HAS_COMPAT(DT_NODELABEL(n), generic_device)

This macro only uses the value of the compatible property. Whether or not a particular compatible has a matching binding has no effect on its value, nor does the node’s status.

Return

1 if the node’s compatible property contains compat, 0 otherwise.

Parameters

• node_id: node identifier

• compat: lowercase-and-underscorse compatible value

DT_NODE_HAS_COMPAT_STATUS(node_id, compat, status)

Does a devicetree node have a compatible and status?

This is equivalent to:

(DT_NODE_HAS_COMPAT(node_id, compat) &&
 DT_NODE_HAS_STATUS(node_id, status))

Parameters

• node_id: node identifier

• compat: lowercase-and-underscores compatible

• status: okay or disabled as a token, not a string

DT_NODE_HAS_PROP(node_id, prop)

Does a devicetree node have a property?

Tests whether a devicetree node has a property defined.

This tests whether the property is defined at all, not whether a boolean property is true or false. To get a boolean property’s truth value, use DT_PROP(node_id, prop) instead.

Return

1 if the node has the property, 0 otherwise.

Parameters

• node_id: node identifier

• prop: lowercase-and-underscores property name

DT_PHA_HAS_CELL_AT_IDX(node_id, pha, idx, cell)

Does a phandle array have a named cell specifier at an index?

If this returns 1, then the phandle-array property “pha” has a cell named “cell” at index “idx”, and therefore DT_PHA_BY_IDX(node_id, pha, idx, cell) is valid. If it returns 0, it’s an error to use DT_PHA_BY_IDX() with the same arguments.

Return

1 if the named cell exists in the specifier at index idx, 0 otherwise.

Parameters

• node_id: node identifier

• pha: lowercase-and-underscores property with type “phandle-array”

• idx: index to check within “pha”

• cell: lowercase-and-underscores cell name whose existence to check at index “idx”

DT_PHA_HAS_CELL(node_id, pha, cell)

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

Return

1 if the named cell exists in the specifier at index 0, 0 otherwise.

Parameters

• node_id: node identifier

• pha: lowercase-and-underscores property with type “phandle-array”

• cell: lowercase-and-underscores cell name whose existence to check at index “idx”

Inter-node dependencies

The devicetree.h API has some support for tracking dependencies between nodes. Dependency tracking relies on a binary “depends on” relation between devicetree nodes, which is defined as the transitive closure of the following “directly depends on” relation:

• every non-root node directly depends on its parent node

• a node directly depends on any nodes its properties refer to by phandle

• a node directly depends on its interrupt-parent if it has an interrupts property

A dependency ordering of a devicetree is a list of its nodes, where each node n appears earlier in the list than any nodes that depend on n. A node’s dependency ordinal is then its zero-based index in that list. Thus, for two distinct devicetree nodes n1 and n2 with dependency ordinals d1 and d2, we have:

• d1 != d2

• if n1 depends on n2, then d1 > d2

• d1 > d2 does not necessarily imply that n1 depends on n2

The Zephyr build system chooses a dependency ordering of the final devicetree and assigns a dependency ordinal to each node. Dependency related information can be accessed using the following macros. The exact dependency ordering chosen is an implementation detail, but cyclic dependencies are detected and cause errors, so it’s safe to assume there are none when using these macros.

There are instance number-based conveniences as well; see DT_INST_DEP_ORD() and subsequent documentation.

group devicetree-dep-ord

Defines

DT_DEP_ORD(node_id)

Get a node’s dependency ordinal.

Return

the node’s dependency ordinal as an integer literal

Parameters

• node_id: Node identifier

DT_REQUIRES_DEP_ORDS(node_id)

Get a list of dependency ordinals of a node’s direct dependencies.

There is a comma after each ordinal in the expansion, including the last one:

DT_REQUIRES_DEP_ORDS(my_node) // required_ord_1, ..., required_ord_n,

The one case DT_REQUIRES_DEP_ORDS() expands to nothing is when given the root node identifier DT_ROOT as argument. The root has no direct dependencies; every other node at least depends on its parent.

Return

a list of dependency ordinals, with each ordinal followed by a comma (,), or an empty expansion

Parameters

• node_id: Node identifier

DT_SUPPORTS_DEP_ORDS(node_id)

Get a list of dependency ordinals of what depends directly on a node.

There is a comma after each ordinal in the expansion, including the last one:

DT_SUPPORTS_DEP_ORDS(my_node) // supported_ord_1, ..., supported_ord_n,

DT_SUPPORTS_DEP_ORDS() may expand to nothing. This happens when node_id refers to a leaf node that nothing else depends on.

Return

a list of dependency ordinals, with each ordinal followed by a comma (,), or an empty expansion

Parameters

• node_id: Node identifier

DT_INST_DEP_ORD(inst)

Get a DT_DRV_COMPAT instance’s dependency ordinal.

Equivalent to DT_DEP_ORD(DT_DRV_INST(inst)).

Return

The instance’s dependency ordinal

Parameters

• inst: instance number

DT_INST_REQUIRES_DEP_ORDS(inst)

Get a list of dependency ordinals of a DT_DRV_COMPAT instance’s direct dependencies.

Equivalent to DT_REQUIRES_DEP_ORDS(DT_DRV_INST(inst)).

Return

a list of dependency ordinals for the nodes the instance depends on directly

Parameters

• inst: instance number

DT_INST_SUPPORTS_DEP_ORDS(inst)

Get a list of dependency ordinals of what depends directly on a DT_DRV_COMPAT instance.

Equivalent to DT_SUPPORTS_DEP_ORDS(DT_DRV_INST(inst)).

Return

a list of node identifiers for the nodes that depend directly on the instance

Parameters

• inst: instance number

Bus helpers

Zephyr’s devicetree bindings language supports a bus: key which allows bindings to declare that nodes with a given compatible describe system buses. In this case, child nodes are considered to be on a bus of the given type, and the following APIs may be used.

group devicetree-generic-bus

Defines

DT_BUS(node_id)

Node’s bus controller.

Get the node identifier of the node’s bus controller. This can be used with DT_PROP() to get properties of the bus controller.

It is an error to use this with nodes which do not have bus controllers.

Example devicetree fragment:

i2c@deadbeef {
        label = "I2C_CTLR";
        status = "okay";
        clock-frequency = < 100000 >;

        i2c_device: accelerometer@12 {
                ...
        };
};

Example usage:

DT_PROP(DT_BUS(DT_NODELABEL(i2c_device)), clock_frequency) // 100000

Return

a node identifier for the node’s bus controller

Parameters

• node_id: node identifier

DT_BUS_LABEL(node_id)

Node’s bus controller’s label property.

Return

the label property of the node’s bus controller DT_BUS(node)

Parameters

• node_id: node identifier

DT_ON_BUS(node_id, bus)

Is a node on a bus of a given type?

Example devicetree overlay:

&i2c0 {
       temp: temperature-sensor@76 {
                compatible = "vnd,some-sensor";
                reg = <0x76>;
       };
};

Example usage, assuming “i2c0” is an I2C bus controller node, and therefore “temp” is on an I2C bus:

DT_ON_BUS(DT_NODELABEL(temp), i2c) // 1
DT_ON_BUS(DT_NODELABEL(temp), spi) // 0

Return

1 if the node is on a bus of the given type, 0 otherwise

Parameters

• node_id: node identifier

• bus: lowercase-and-underscores bus type as a C token (i.e. without quotes)

Instance-based APIs

These are recommended for use within device drivers. To use them, define DT_DRV_COMPAT to the lowercase-and-underscores compatible the device driver implements support for. Here is an example devicetree fragment:

serial@40001000 {
        compatible = "vnd,serial";
        status = "okay";
        current-speed = <115200>;
};

Example usage, assuming serial@40001000 is the only enabled node with compatible “vnd,serial”:

#define DT_DRV_COMPAT vnd_serial
DT_DRV_INST(0)                  // node identifier for serial@40001000
DT_INST_PROP(0, current_speed)  // 115200

Warning

Be careful making assumptions about instance numbers. See DT_INST() for the API guarantees.

As shown above, the DT_INST_* APIs are conveniences for addressing nodes by instance number. They are almost all defined in terms of one of the Generic APIs. The equivalent generic API can be found by removing INST_ from the macro name. For example, DT_INST_PROP(inst, prop) is equivalent to DT_PROP(DT_DRV_INST(inst), prop). Similarly, DT_INST_REG_ADDR(inst) is equivalent to DT_REG_ADDR(DT_DRV_INST(inst)), and so on. There are some exceptions: DT_ANY_INST_ON_BUS_STATUS_OKAY() and DT_INST_FOREACH_STATUS_OKAY() are special-purpose helpers without straightforward generic equivalents.

Since DT_DRV_INST() requires DT_DRV_COMPAT to be defined, it’s an error to use any of these without that macro defined.

Note that there are also helpers available for specific hardware; these are documented in Hardware specific APIs.

group devicetree-inst

Defines

DT_DRV_INST(inst)

Node identifier for an instance of a DT_DRV_COMPAT compatible.

Return

a node identifier for the node with DT_DRV_COMPAT compatible and instance number “inst”

Parameters

• inst: instance number

DT_INST_FOREACH_CHILD(inst, fn)

Call “fn” on all child nodes of DT_DRV_INST(inst).

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

See

DT_FOREACH_CHILD

Parameters

• inst: instance number

• fn: macro to invoke on each child node identifier

DT_INST_PROP(inst, prop)

Get a DT_DRV_COMPAT instance property.

Return

a representation of the property’s value

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

DT_INST_PROP_LEN(inst, prop)

Get a DT_DRV_COMPAT property length.

Return

logical length of the property

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

DT_INST_PROP_HAS_IDX(inst, prop, idx)

Is index “idx” valid for an array type property on a DT_DRV_COMPAT instance?

Return

1 if “idx” is a valid index into the given property, 0 otherwise.

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

• idx: index to check

DT_INST_PROP_BY_IDX(inst, prop, idx)

Get a DT_DRV_COMPAT element value in an array property.

Return

a representation of the idx-th element of the property

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

• idx: the index to get

DT_INST_PROP_OR(inst, prop, default_value)

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

Return

DT_INST_PROP(inst, prop) or default_value

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

• default_value: a fallback value to expand to

DT_INST_LABEL(inst)

Get a DT_DRV_COMPAT instance’s “label” property.

Return

instance’s label property value

Parameters

• inst: instance number

DT_INST_PROP_BY_PHANDLE(inst, ph, prop)

Get a DT_DRV_COMPAT instance’s property value from a phandle’s node.

Return

the value of “prop” as described in the DT_PROP() documentation

Parameters

• inst: instance number

• ph: lowercase-and-underscores property of “inst” with type “phandle”

• prop: lowercase-and-underscores property of the phandle’s node

DT_INST_PROP_BY_PHANDLE_IDX(inst, phs, idx, prop)

Get a DT_DRV_COMPAT instance’s property value from a phandle in a property.

Return

the value of “prop” as described in the DT_PROP() documentation

Parameters

• inst: instance number

• 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

DT_INST_PHA_BY_IDX(inst, pha, idx, cell)

Get a DT_DRV_COMPAT instance’s phandle-array specifier value at an index.

Return

the value of the cell inside the specifier at index “idx”

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• idx: logical index into the property “pha”

• cell: binding’s cell name within the specifier at index “idx”

DT_INST_PHA_BY_IDX_OR(inst, pha, idx, cell, default_value)

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

Return

DT_INST_PHA_BY_IDX(inst, pha, idx, cell) or default_value

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• idx: logical index into the property “pha”

• cell: binding’s cell name within the specifier at index “idx”

• default_value: a fallback value to expand to

DT_INST_PHA(inst, pha, cell)

Get a DT_DRV_COMPAT instance’s phandle-array specifier value Equivalent to DT_INST_PHA_BY_IDX(inst, pha, 0, cell)

Return

the cell value

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• cell: binding’s cell name for the specifier at “pha” index 0

DT_INST_PHA_OR(inst, pha, cell, default_value)

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

Return

DT_INST_PHA(inst, pha, cell) or default_value

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• cell: binding’s cell name for the specifier at “pha” index 0

• default_value: a fallback value to expand to

DT_INST_PHA_BY_NAME(inst, pha, name, cell)

Get a DT_DRV_COMPAT instance’s value within a phandle-array specifier by name.

Return

the cell value

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• name: lowercase-and-underscores name of a specifier in “pha”

• cell: binding’s cell name for the named specifier

DT_INST_PHA_BY_NAME_OR(inst, pha, name, cell, default_value)

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

Return

DT_INST_PHA_BY_NAME(inst, pha, name, cell) or default_value

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• name: lowercase-and-underscores name of a specifier in “pha”

• cell: binding’s cell name for the named specifier

• default_value: a fallback value to expand to

DT_INST_PHANDLE_BY_NAME(inst, pha, name)

Get a DT_DRV_COMPAT instance’s phandle node identifier from a phandle array by name.

Return

node identifier for the phandle at the element named “name”

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• name: lowercase-and-underscores name of an element in “pha”

DT_INST_PHANDLE_BY_IDX(inst, prop, idx)

Get a DT_DRV_COMPAT instance’s node identifier for a phandle in a property.

Return

a node identifier for the phandle at index “idx” in “prop”

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name in “inst” with type “phandle”, “phandles” or “phandle-array”

• idx: index into “prop”

DT_INST_PHANDLE(inst, prop)

Get a DT_DRV_COMPAT instance’s node identifier for a phandle property’s value.

Return

a node identifier for the node pointed to by “ph”

Parameters

• inst: instance number

• prop: lowercase-and-underscores property of “inst” with type “phandle”

DT_INST_REG_HAS_IDX(inst, idx)

is “idx” a valid register block index on a DT_DRV_COMPAT instance?

Return

1 if “idx” is a valid register block index, 0 otherwise.

Parameters

• inst: instance number

• idx: index to check

DT_INST_REG_ADDR_BY_IDX(inst, idx)

Get a DT_DRV_COMPAT instance’s idx-th register block’s address.

Return

address of the instance’s idx-th register block

Parameters

• inst: instance number

• idx: index of the register whose address to return

DT_INST_REG_SIZE_BY_IDX(inst, idx)

Get a DT_DRV_COMPAT instance’s idx-th register block’s size.

Return

size of the instance’s idx-th register block

Parameters

• inst: instance number

• idx: index of the register whose size to return

DT_INST_REG_ADDR_BY_NAME(inst, name)

Get a DT_DRV_COMPAT’s register block address by name.

Return

address of the register block with the given name

Parameters

• inst: instance number

• name: lowercase-and-underscores register specifier name

DT_INST_REG_SIZE_BY_NAME(inst, name)

Get a DT_DRV_COMPAT’s register block size by name.

Return

size of the register block with the given name

Parameters

• inst: instance number

• name: lowercase-and-underscores register specifier name

DT_INST_REG_ADDR(inst)

Get a DT_DRV_COMPAT’s (only) register block address.

Return

instance’s register block address

Parameters

• inst: instance number

DT_INST_REG_SIZE(inst)

Get a DT_DRV_COMPAT’s (only) register block size.

Return

instance’s register block size

Parameters

• inst: instance number

DT_INST_IRQ_BY_IDX(inst, idx, cell)

Get a DT_DRV_COMPAT interrupt specifier value at an index.

Return

the named value at the specifier given by the index

Parameters

• inst: instance number

• idx: logical index into the interrupt specifier array

• cell: cell name specifier

DT_INST_IRQ_BY_NAME(inst, name, cell)

Get a DT_DRV_COMPAT interrupt specifier value by name.

Return

the named value at the specifier given by the index

Parameters

• inst: instance number

• name: lowercase-and-underscores interrupt specifier name

• cell: cell name specifier

DT_INST_IRQ(inst, cell)

Get a DT_DRV_COMPAT interrupt specifier’s value.

Return

the named value at that index

Parameters

• inst: instance number

• cell: cell name specifier

DT_INST_IRQN(inst)

Get a DT_DRV_COMPAT’s (only) irq number.

Return

the interrupt number for the node’s only interrupt

Parameters

• inst: instance number

DT_INST_BUS_LABEL(inst)

Get a DT_DRV_COMPAT’s bus node’s label property.

Return

the label property of the instance’s bus controller

Parameters

• inst: instance number

DT_INST_ON_BUS(inst, bus)

Test if a DT_DRV_COMPAT’s bus type is a given type.

Return

1 if the given instance is on a bus of the given type, 0 otherwise

Parameters

• inst: instance number

• bus: a binding’s bus type as a C token, lowercased and without quotes

DT_ANY_INST_ON_BUS_STATUS_OKAY(bus)

Test if any DT_DRV_COMPAT node is on a bus of a given type and has status okay.

This is a special-purpose macro which can be useful when writing drivers for devices which can appear on multiple buses. One example is a sensor device which may be wired on an I2C or SPI bus.

Example devicetree overlay:

&i2c0 {
       temp: temperature-sensor@76 {
                compatible = "vnd,some-sensor";
                reg = <0x76>;
       };
};

Example usage, assuming “i2c0” is an I2C bus controller node, and therefore “temp” is on an I2C bus:

#define DT_DRV_COMPAT vnd_some_sensor

DT_ANY_INST_ON_BUS_STATUS_OKAY(i2c) // 1

Return

1 if any enabled node with that compatible is on that bus type, 0 otherwise

Parameters

• bus: a binding’s bus type as a C token, lowercased and without quotes

DT_INST_FOREACH_STATUS_OKAY(fn)

Call “fn” on all nodes with compatible DT_DRV_COMPAT and status “okay”.

This macro calls “fn(inst)” on each “inst” number that refers to a node with status “okay”. Whitespace is added between invocations.

Example devicetree fragment:

a {
        compatible = "vnd,device";
        status = "okay";
        label = "DEV_A";
};

b {
        compatible = "vnd,device";
        status = "okay";
        label = "DEV_B";
};

c {
        compatible = "vnd,device";
        status = "disabled";
        label = "DEV_C";
};

Example usage:

#define DT_DRV_COMPAT vnd_device
#define MY_FN(inst) DT_INST_LABEL(inst),

DT_INST_FOREACH_STATUS_OKAY(MY_FN)

This expands to:

MY_FN(0) MY_FN(1)

and from there, to either this:

"DEV_A", "DEV_B",

or this:

"DEV_B", "DEV_A",

No guarantees are made about the order that a and b appear in the expansion.

Note that “fn” is responsible for adding commas, semicolons, or other separators or terminators.

Device drivers should use this macro whenever possible to instantiate a struct device for each enabled node in the devicetree of the driver’s compatible DT_DRV_COMPAT.

Parameters

• fn: Macro to call for each enabled node. Must accept an instance number as its only parameter.

DT_INST_NODE_HAS_PROP(inst, prop)

Does a DT_DRV_COMPAT instance have a property?

Return

1 if the instance has the property, 0 otherwise.

Parameters

• inst: instance number

• prop: lowercase-and-underscores property name

DT_INST_PHA_HAS_CELL_AT_IDX(inst, pha, idx, cell)

Does a phandle array have a named cell specifier at an index for a DT_DRV_COMPAT instance?

Return

1 if the named cell exists in the specifier at index idx, 0 otherwise.

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• idx: index to check

• cell: named cell value whose existence to check

DT_INST_PHA_HAS_CELL(inst, pha, cell)

Does a phandle array have a named cell specifier at index 0 for a DT_DRV_COMPAT instance?

Return

1 if the named cell exists in the specifier at index 0, 0 otherwise.

Parameters

• inst: instance number

• pha: lowercase-and-underscores property with type “phandle-array”

• cell: named cell value whose existence to check

DT_INST_IRQ_HAS_IDX(inst, idx)

is index valid for interrupt property on a DT_DRV_COMPAT instance?

Return

1 if the idx is valid for the interrupt property 0 otherwise.

Parameters

• inst: instance number

• idx: logical index into the interrupt specifier array

DT_INST_IRQ_HAS_CELL_AT_IDX(inst, idx, cell)

Does a DT_DRV_COMPAT instance have an interrupt named cell specifier?

Return

1 if the named cell exists in the interrupt specifier at index idx 0 otherwise.

Parameters

• inst: instance number

• idx: index to check

• cell: named cell value whose existence to check

DT_INST_IRQ_HAS_CELL(inst, cell)

Does a DT_DRV_COMPAT instance have an interrupt value?

Return

1 if the named cell exists in the interrupt specifier at index 0 0 otherwise.

Parameters

• inst: instance number

• cell: named cell value whose existence to check

DT_INST_IRQ_HAS_NAME(inst, name)

Does a DT_DRV_COMPAT instance have an interrupt value?

Return

1 if “name” is a valid named specifier

Parameters

• inst: instance number

• name: lowercase-and-underscores interrupt specifier name

Hardware specific APIs

The following APIs can also be used by including <devicetree.h>; no additional include is needed.

Clocks

These conveniences may be used for nodes which describe clock sources, and properties related to them.

group devicetree-clocks

Defines

DT_CLOCKS_LABEL_BY_IDX(node_id, idx)

Get a label property from the node referenced by a pwms property at an index.

It’s an error if the clock controller node referenced by the phandle in node_id’s clocks property at index “idx” has no label property.

Example devicetree fragment:

clk1: clock-controller@... {
        label = "CLK_1";
};

clk2: clock-controller@... {
        label = "CLK_2";
};

n: node {
        clocks = <&clk1 10 20>, <&clk2 30 40>;
};

Example usage:

DT_CLOCKS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "CLK_2"

Return

the label property of the node referenced at index “idx”

See

DT_PROP_BY_PHANDLE_IDX()

Parameters

• node_id: node identifier for a node with a clocks property

• idx: logical index into clocks property

DT_CLOCKS_LABEL_BY_NAME(node_id, name)

Get a label property from a clocks property by name.

It’s an error if the clock controller node referenced by the phandle in node_id’s clocks property at the element named “name” has no label property.

Example devicetree fragment:

clk1: clock-controller@... {
        label = "CLK_1";
};

clk2: clock-controller@... {
        label = "CLK_2";
};

n: node {
        clocks = <&clk1 10 20>, <&clk2 30 40>;
        clock-names = "alpha", "beta";
};

Example usage:

DT_CLOCKS_LABEL_BY_NAME(DT_NODELABEL(n), beta) // "CLK_2"

Return

the label property of the node referenced at the named element

See

DT_PHANDLE_BY_NAME()

Parameters

• node_id: node identifier for a node with a clocks property

• name: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property

DT_CLOCKS_LABEL(node_id)

Equivalent to DT_CLOCKS_LABEL_BY_IDX(node_id, 0)

Return

the label property of the node referenced at index 0

See

DT_CLOCKS_LABEL_BY_IDX()

Parameters

• node_id: node identifier for a node with a clocks property

DT_CLOCKS_CELL_BY_IDX(node_id, idx, cell)

Get a clock specifier’s cell value at an index.

Example devicetree fragment:

clk1: clock-controller@... {
        compatible = "vnd,clock";
        #clock-cells = < 2 >;
};

n: node {
        clocks = < &clk1 10 20 >, < &clk1 30 40 >;
};

Bindings fragment for the vnd,clock compatible:

clock-cells:
  - bus
  - bits

Example usage:

DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 0, bus) // 10
DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 1, bits) // 40

Return

the cell value at index “idx”

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier for a node with a clocks property

• idx: logical index into clocks property

• cell: lowercase-and-underscores cell name

DT_CLOCKS_CELL_BY_NAME(node_id, name, cell)

Get a clock specifier’s cell value by name.

Example devicetree fragment:

clk1: clock-controller@... {
        compatible = "vnd,clock";
        #clock-cells = < 2 >;
};

n: node {
        clocks = < &clk1 10 20 >, < &clk1 30 40 >;
        clock-names = "alpha", "beta";
};

Bindings fragment for the vnd,clock compatible:

clock-cells:
  - bus
  - bits

Example usage:

DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), alpha, bus) // 10
DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), beta, bits) // 40

Return

the cell value in the specifier at the named element

See

DT_PHA_BY_NAME()

Parameters

• node_id: node identifier for a node with a clocks property

• name: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property

• cell: lowercase-and-underscores cell name

DT_CLOCKS_CELL(node_id, cell)

Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)

Return

the cell value at index 0

See

DT_CLOCKS_CELL_BY_IDX()

Parameters

• node_id: node identifier for a node with a clocks property

• cell: lowercase-and-underscores cell name

DT_INST_CLOCKS_LABEL_BY_IDX(inst, idx)

Get a label property from a DT_DRV_COMPAT instance’s clocks property at an index.

Return

the label property of the node referenced at index “idx”

See

DT_CLOCKS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into clocks property

DT_INST_CLOCKS_LABEL_BY_NAME(inst, name)

Get a label property from a DT_DRV_COMPAT instance’s clocks property by name.

Return

the label property of the node referenced at the named element

See

DT_CLOCKS_LABEL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property

DT_INST_CLOCKS_LABEL(inst)

Equivalent to DT_INST_CLOCKS_LABEL_BY_IDX(inst, 0)

Return

the label property of the node referenced at index 0

See

DT_CLOCKS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_CLOCKS_CELL_BY_IDX(inst, idx, cell)

Get a DT_DRV_COMPAT instance’s clock specifier’s cell value at an index.

Return

the cell value at index “idx”

See

DT_CLOCKS_CELL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into clocks property

• cell: lowercase-and-underscores cell name

DT_INST_CLOCKS_CELL_BY_NAME(inst, name, cell)

Get a DT_DRV_COMPAT instance’s clock specifier’s cell value by name.

Return

the cell value in the specifier at the named element

See

DT_CLOCKS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property

• cell: lowercase-and-underscores cell name

DT_INST_CLOCKS_CELL(inst, cell)

Equivalent to DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)

Return

the value of the cell inside the specifier at index 0

Parameters

• inst: DT_DRV_COMPAT instance number

• cell: lowercase-and-underscores cell name

DMA

These conveniences may be used for nodes which describe direct memory access controllers or channels, and properties related to them.

group devicetree-dmas

Defines

DT_DMAS_LABEL_BY_IDX(node_id, idx)

Get a label property from the node referenced by a dmas property at an index.

It’s an error if the DMA controller node referenced by the phandle in node_id’s dmas property at index “idx” has no label property.

Example devicetree fragment:

dma1: dma@... {
        label = "DMA_1";
};

dma2: dma@... {
        label = "DMA_2";
};

n: node {
    dmas = <&dma1 1 2 0x400 0x3>,
            <&dma2 6 3 0x404 0x5>;
};

Example usage:

DT_DMAS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "DMA_2"

Return

the label property of the node referenced at index “idx”

Parameters

• node_id: node identifier for a node with a dmas property

• idx: logical index into dmas property

DT_INST_DMAS_LABEL_BY_IDX(inst, idx)

Get a label property from a DT_DRV_COMPAT instance’s dmas property at an index.

Return

the label property of the node referenced at index “idx”

See

DT_DMAS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into dmas property

DT_DMAS_LABEL_BY_NAME(node_id, name)

Get a label property from a dmas property by name.

It’s an error if the DMA controller node referenced by the phandle in node_id’s dmas property at the element named “name” has no label property.

Example devicetree fragment:

dma1: dma@... {
        label = "DMA_1";
};

dma2: dma@... {
        label = "DMA_2";
};

n: node {
    dmas = <&dma1 1 2 0x400 0x3>,
            <&dma2 6 3 0x404 0x5>;
    dma-names = "tx", "rx";
};

Example usage:

DT_DMAS_LABEL_BY_NAME(DT_NODELABEL(n), rx) // "DMA_2"

Return

the label property of the node referenced at the named element

Parameters

• node_id: node identifier for a node with a dmas property

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

DT_INST_DMAS_LABEL_BY_NAME(inst, name)

Get a label property from a DT_DRV_COMPAT instance’s dmas property by name.

Return

the label property of the node referenced at the named element

See

DT_DMAS_LABEL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

DT_DMAS_CELL_BY_IDX(node_id, idx, cell)

Get a DMA specifier’s cell value at an index.

Example devicetree fragment:

dma1: dma@... {
        compatible = "vnd,dma";
        #dma-cells = <2>;
};

dma2: dma@... {
        compatible = "vnd,dma";
        #dma-cells = <2>;
};

n: node {
    dmas = <&dma1 1 0x400>,
           <&dma2 6 0x404>;
};

Bindings fragment for the vnd,dma compatible:

dma-cells:
  - channel
  - config

Example usage:

DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, channel) // 1
DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, channel) // 6
DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, config) // 0x400
DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, config) // 0x404

Return

the cell value at index “idx”

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier for a node with a dmas property

• idx: logical index into dmas property

• cell: lowercase-and-underscores cell name

DT_INST_DMAS_CELL_BY_IDX(inst, idx, cell)

Get a DT_DRV_COMPAT instance’s DMA specifier’s cell value at an index.

Return

the cell value at index “idx”

See

DT_DMAS_CELL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into dmas property

• cell: lowercase-and-underscores cell name

DT_DMAS_CELL_BY_NAME(node_id, name, cell)

Get a DMA specifier’s cell value by name.

Example devicetree fragment:

dma1: dma@... {
        compatible = "vnd,dma";
        #dma-cells = <2>;
};

dma2: dma@... {
        compatible = "vnd,dma";
        #dma-cells = <2>;
};

n: node {
    dmas = <&dma1 1 0x400>,
           <&dma2 6 0x404>;
    dma-names = "tx", "rx";
};

Bindings fragment for the vnd,dma compatible:

dma-cells:
  - channel
  - config

Example usage:

DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, channel) // 1
DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, channel) // 6
DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, config) // 0x400
DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, config) // 0x404

Return

the cell value in the specifier at the named element

See

DT_PHA_BY_NAME()

Parameters

• node_id: node identifier for a node with a dmas property

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

• cell: lowercase-and-underscores cell name

DT_INST_DMAS_CELL_BY_NAME(inst, name, cell)

Get a DT_DRV_COMPAT instance’s DMA specifier’s cell value by name.

Return

the cell value in the specifier at the named element

See

DT_DMAS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

• cell: lowercase-and-underscores cell name

DT_DMAS_HAS_IDX(node_id, idx)

Is index “idx” valid for a dmas property?

Return

1 if the “dmas” property has index “idx”, 0 otherwise

Parameters

• node_id: node identifier for a node with a dmas property

• idx: logical index into dmas property

DT_INST_DMAS_HAS_IDX(inst, idx)

Is index “idx” valid for a DT_DRV_COMPAT instance’s dmas property?

Return

1 if the “dmas” property has a specifier at index “idx”, 0 otherwise

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into dmas property

DT_DMAS_HAS_NAME(node_id, name)

Does a dmas property have a named element?

Return

1 if the dmas property has the named element, 0 otherwise

Parameters

• node_id: node identifier for a node with a dmas property

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

DT_INST_DMAS_HAS_NAME(inst, name)

Does a DT_DRV_COMPAT instance’s dmas property have a named element?

Return

1 if the dmas property has the named element, 0 otherwise

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property

Fixed flash partitions

These conveniences may be used for the special-purpose fixed-partitions compatible used to encode information about flash memory partitions in the device tree. See dts/bindings/mtd/partition.yaml for this compatible’s binding.

group devicetree-fixed-partition

Defines

DT_NODE_BY_FIXED_PARTITION_LABEL(label)

Get a node identifier for a fixed partition with a given label property.

Example devicetree fragment:

flash@... {
         partitions {
                 compatible = "fixed-partitions";
                 boot_partition: partition@0 {
                         label = "mcuboot";
                 };
                 slot0_partition: partition@c000 {
                         label = "image-0";
                 };
                 ...
         };
};

Example usage:

DT_NODE_BY_FIXED_PARTITION_LABEL(mcuboot) // node identifier for boot_partition
DT_NODE_BY_FIXED_PARTITION_LABEL(image_0) // node identifier for slot0_partition

Return

a node identifier for the partition with that label property

Parameters

• label: lowercase-and-underscores label property value

DT_HAS_FIXED_PARTITION_LABEL(label)

Test if a fixed partition with a given label property exists.

Return

1 if any “fixed-partitions” child node has the given label, 0 otherwise.

Parameters

• label: lowercase-and-underscores label property value

DT_FIXED_PARTITION_ID(node_id)

Get a numeric identifier for a fixed partition.

Return

the partition’s ID, a unique zero-based index number

Parameters

• node_id: node identifier for a fixed-partitions child node

DT_MTD_FROM_FIXED_PARTITION(node_id)

Get the node identifier of the flash device for a partition.

Return

the node identifier of the memory technology device that contains the fixed-partitions node.

Parameters

• node_id: node identifier for a fixed-partitions child node

GPIO

These conveniences may be used for nodes which describe GPIO controllers/pins, and properties related to them.

group devicetree-gpio

Defines

DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, idx)

Get the node identifier for the controller phandle from a gpio phandle-array property at an index.

Example devicetree fragment:

gpio1: gpio@... { };

gpio2: gpio@... { };

n: node {
        gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                <&gpio2 30 GPIO_ACTIVE_HIGH>;
};

Example usage:

DT_GPIO_CTLR_BY_IDX(DT_NODELABEL(n), gpios, 1) // DT_NODELABEL(gpio2)

Return

the node identifier for the gpio controller referenced at index “idx”

See

DT_PHANDLE_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_GPIO_CTLR(node_id, gpio_pha)

Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)

Return

a node identifier for the gpio controller at index 0 in “gpio_pha”

See

DT_GPIO_CTLR_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, idx)

Get a label property from a gpio phandle-array property at an index.

It’s an error if the GPIO controller node referenced by the phandle in node_id’s “gpio_pha” property at index “idx” has no label property.

Example devicetree fragment:

gpio1: gpio@... {
        label = "GPIO_1";
};

gpio2: gpio@... {
        label = "GPIO_2";
};

n: node {
        gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                <&gpio2 30 GPIO_ACTIVE_HIGH>;
};

Example usage:

DT_GPIO_LABEL_BY_IDX(DT_NODELABEL(n), gpios, 1) // "GPIO_2"

Return

the label property of the node referenced at index “idx”

See

DT_PHANDLE_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_GPIO_LABEL(node_id, gpio_pha)

Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)

Return

the label property of the node referenced at index 0

See

DT_GPIO_LABEL_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, idx)

Get a GPIO specifier’s pin cell at an index.

This macro only works for GPIO specifiers with cells named “pin”. Refer to the node’s binding to check if necessary.

Example devicetree fragment:

gpio1: gpio@... {
        compatible = "vnd,gpio";
        #gpio-cells = <2>;
};

gpio2: gpio@... {
        compatible = "vnd,gpio";
        #gpio-cells = <2>;
};

n: node {
        gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                <&gpio2 30 GPIO_ACTIVE_HIGH>;
};

Bindings fragment for the vnd,gpio compatible:

gpio-cells:
  - pin
  - flags

Example usage:

DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10
DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30

Return

the pin cell value at index “idx”

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_GPIO_PIN(node_id, gpio_pha)

Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)

Return

the pin cell value at index 0

See

DT_GPIO_PIN_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, idx)

Get a GPIO specifier’s flags cell at an index.

This macro expects GPIO specifiers with cells named “flags”. If there is no “flags” cell in the GPIO specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.

Example devicetree fragment:

gpio1: gpio@... {
        compatible = "vnd,gpio";
        #gpio-cells = <2>;
};

gpio2: gpio@... {
        compatible = "vnd,gpio";
        #gpio-cells = <2>;
};

n: node {
        gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                <&gpio2 30 GPIO_ACTIVE_HIGH>;
};

Bindings fragment for the vnd,gpio compatible:

gpio-cells:
  - pin
  - flags

Example usage:

DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW
DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH

Return

the flags cell value at index “idx”, or zero if there is none

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_GPIO_FLAGS(node_id, gpio_pha)

Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)

Return

the flags cell value at index 0, or zero if there is none

See

DT_GPIO_FLAGS_BY_IDX()

Parameters

• node_id: node identifier

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, idx)

Get a label property from a DT_DRV_COMPAT instance’s GPIO property at an index.

Return

the label property of the node referenced at index “idx”

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_INST_GPIO_LABEL(inst, gpio_pha)

Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)

Return

the label property of the node referenced at index 0

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, idx)

Get a DT_DRV_COMPAT instance’s GPIO specifier’s pin cell value at an index.

Return

the pin cell value at index “idx”

See

DT_GPIO_PIN_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_INST_GPIO_PIN(inst, gpio_pha)

Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)

Return

the pin cell value at index 0

See

DT_INST_GPIO_PIN_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, idx)

Get a DT_DRV_COMPAT instance’s GPIO specifier’s flags cell at an index.

Return

the flags cell value at index “idx”, or zero if there is none

See

DT_GPIO_FLAGS_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

• idx: logical index into “gpio_pha”

DT_INST_GPIO_FLAGS(inst, gpio_pha)

Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)

Return

the flags cell value at index 0, or zero if there is none

See

DT_INST_GPIO_FLAGS_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• gpio_pha: lowercase-and-underscores GPIO property with type “phandle-array”

IO channels

These are commonly used by device drivers which need to use IO channels (e.g. ADC or DAC channels) for conversion.

group devicetree-io-channels

Defines

DT_IO_CHANNELS_LABEL_BY_IDX(node_id, idx)

Get a label property from the node referenced by an io-channels property at an index.

It’s an error if the node referenced by the phandle in node_id’s io-channels property at index “idx” has no label property.

Example devicetree fragment:

adc1: adc@... {
        label = "ADC_1";
};

adc2: adc@... {
        label = "ADC_2";
};

n: node {
        io-channels = <&adc1 10>, <&adc2 20>;
};

Example usage:

DT_IO_CHANNELS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "ADC_2"

Return

the label property of the node referenced at index “idx”

See

DT_PROP_BY_PHANDLE_IDX()

Parameters

• node_id: node identifier for a node with an io-channels property

• idx: logical index into io-channels property

DT_IO_CHANNELS_LABEL_BY_NAME(node_id, name)

Get a label property from an io-channels property by name.

It’s an error if the node referenced by the phandle in node_id’s io-channels property at the element named “name” has no label property.

Example devicetree fragment:

adc1: adc@... {
        label = "ADC_1";
};

adc2: adc@... {
        label = "ADC_2";
};

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

Example usage:

DT_IO_CHANNELS_LABEL_BY_NAME(DT_NODELABEL(n), bandgap) // "ADC_2"

Return

the label property of the node referenced at the named element

See

DT_PHANDLE_BY_NAME()

Parameters

• node_id: node identifier for a node with an io-channels property

• name: lowercase-and-underscores name of an io-channels element as defined by the node’s io-channel-names property

DT_IO_CHANNELS_LABEL(node_id)

Equivalent to DT_IO_CHANNELS_LABEL_BY_IDX(node_id, 0)

Return

the label property of the node referenced at index 0

See

DT_IO_CHANNELS_LABEL_BY_IDX()

Parameters

• node_id: node identifier for a node with an io-channels property

DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, idx)

Get a label property from a DT_DRV_COMPAT instance’s io-channels property at an index.

Return

the label property of the node referenced at index “idx”

See

DT_IO_CHANNELS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into io-channels property

DT_INST_IO_CHANNELS_LABEL_BY_NAME(inst, name)

Get a label property from a DT_DRV_COMPAT instance’s io-channels property by name.

Return

the label property of the node referenced at the named element

See

DT_IO_CHANNELS_LABEL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of an io-channels element as defined by the instance’s io-channel-names property

DT_INST_IO_CHANNELS_LABEL(inst)

Equivalent to DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, 0)

Return

the label property of the node referenced at index 0

Parameters

• inst: DT_DRV_COMPAT instance number

DT_IO_CHANNELS_INPUT_BY_IDX(node_id, idx)

Get an io-channels specifier input cell at an index.

This macro only works for io-channels specifiers with cells named “input”. Refer to the node’s binding to check if necessary.

Example devicetree fragment:

adc1: adc@... {
        compatible = "vnd,adc";
        #io-channel-cells = <1>;
};

adc2: adc@... {
        compatible = "vnd,adc";
        #io-channel-cells = <1>;
};

n: node {
        io-channels = <&adc1 10>, <&adc2 20>;
};

Bindings fragment for the vnd,adc compatible:

io-channel-cells:

• input

Example usage:

DT_IO_CHANNELS_INPUT_BY_IDX(DT_NODELABEL(n), 0) // 10
DT_IO_CHANNELS_INPUT_BY_IDX(DT_NODELABEL(n), 1) // 20

Return

the input cell in the specifier at index “idx”

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier for a node with an io-channels property

• idx: logical index into io-channels property

DT_IO_CHANNELS_INPUT_BY_NAME(node_id, name)

Get an io-channels specifier input cell by name.

This macro only works for io-channels specifiers with cells named “input”. Refer to the node’s binding to check if necessary.

Example devicetree fragment:

adc1: adc@... {
        compatible = "vnd,adc";
        #io-channel-cells = <1>;
};

adc2: adc@... {
        compatible = "vnd,adc";
        #io-channel-cells = <1>;
};

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

Bindings fragment for the vnd,adc compatible:

io-channel-cells:

• input

Example usage:

DT_IO_CHANNELS_INPUT_BY_NAME(DT_NODELABEL(n), sensor) // 10
DT_IO_CHANNELS_INPUT_BY_NAME(DT_NODELABEL(n), bandgap) // 20

Return

the input cell in the specifier at the named element

See

DT_PHA_BY_NAME()

Parameters

• node_id: node identifier for a node with an io-channels property

• name: lowercase-and-underscores name of an io-channels element as defined by the node’s io-channel-names property

DT_IO_CHANNELS_INPUT(node_id)

Equivalent to DT_IO_CHANNELS_INPUT_BY_IDX(node_id, 0)

Return

the input cell in the specifier at index 0

See

DT_IO_CHANNELS_INPUT_BY_IDX()

Parameters

• node_id: node identifier for a node with an io-channels property

DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, idx)

Get an input cell from the “DT_DRV_INST(inst)” io-channels property at an index.

Return

the input cell in the specifier at index “idx”

See

DT_IO_CHANNELS_INPUT_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into io-channels property

DT_INST_IO_CHANNELS_INPUT_BY_NAME(inst, name)

Get an input cell from the “DT_DRV_INST(inst)” io-channels property by name.

Return

the input cell in the specifier at the named element

See

DT_IO_CHANNELS_INPUT_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of an io-channels element as defined by the instance’s io-channel-names property

DT_INST_IO_CHANNELS_INPUT(inst)

Equivalent to DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, 0)

Return

the input cell in the specifier at index 0

Parameters

• inst: DT_DRV_COMPAT instance number

PWM

These conveniences may be used for nodes which describe PWM controllers and properties related to them.

group devicetree-pwms

Defines

DT_PWMS_LABEL_BY_IDX(node_id, idx)

Get a label property from a pwms property at an index.

It’s an error if the PWM controller node referenced by the phandle in node_id’s pwms property at index “idx” has no label property.

Example devicetree fragment:

pwm1: pwm-controller@... {
        label = "PWM_1";
};

pwm2: pwm-controller@... {
        label = "PWM_2";
};

n: node {
        pwms = <&pwm1 1 PWM_POLARITY_NORMAL>,
               <&pwm2 3 PWM_POLARITY_INVERTED>;
};

Example usage:

DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 0) // "PWM_1"
DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "PWM_2"

Return

the label property of the node referenced at index “idx”

See

DT_PROP_BY_PHANDLE_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• idx: logical index into pwms property

DT_PWMS_LABEL_BY_NAME(node_id, name)

Get a label property from a pwms property by name.

It’s an error if the PWM controller node referenced by the phandle in node_id’s pwms property at the element named “name” has no label property.

Example devicetree fragment:

pwm1: pwm-controller@... {
        label = "PWM_1";
};

pwm2: pwm-controller@... {
        label = "PWM_2";
};

n: node {
        pwms = <&pwm1 1 PWM_POLARITY_NORMAL>,
               <&pwm2 3 PWM_POLARITY_INVERTED>;
        pwm-names = "alpha", "beta";
};

Example usage:

DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), alpha) // "PWM_1"
DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), beta)  // "PWM_2"

Return

the label property of the node referenced at the named element

See

DT_PHANDLE_BY_NAME()

Parameters

• node_id: node identifier for a node with a pwms property

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_PWMS_LABEL(node_id)

Equivalent to DT_PWMS_LABEL_BY_IDX(node_id, 0)

Return

the label property of the node referenced at index 0

See

DT_PWMS_LABEL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

DT_PWMS_CELL_BY_IDX(node_id, idx, cell)

Get PWM specifier’s cell value at an index.

Example devicetree fragment:

pwm1: pwm-controller@... {
        compatible = "vnd,pwm";
        label = "PWM_1";
        #pwm-cells = <2>;
};

pwm2: pwm-controller@... {
        compatible = "vnd,pwm";
        label = "PWM_2";
        #pwm-cells = <2>;
};

n: node {
        pwms = <&pwm1 1 200000 PWM_POLARITY_NORMAL>,
               <&pwm2 3 100000 PWM_POLARITY_INVERTED>;
};

Bindings fragment for the “vnd,pwm” compatible:

pwm-cells:
  - channel
  - period
  - flags

Example usage:

DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, channel) // 1
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, channel) // 3
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, period)  // 200000
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, period)  // 100000
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, flags)   // PWM_POLARITY_NORMAL
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, flags)   // PWM_POLARITY_INVERTED

Return

the cell value at index “idx”

See

DT_PHA_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• idx: logical index into pwms property

• cell: lowercase-and-underscores cell name

DT_PWMS_CELL_BY_NAME(node_id, name, cell)

Get a PWM specifier’s cell value by name.

Example devicetree fragment:

pwm1: pwm-controller@... {
        compatible = "vnd,pwm";
        label = "PWM_1";
        #pwm-cells = <2>;
};

pwm2: pwm-controller@... {
        compatible = "vnd,pwm";
        label = "PWM_2";
        #pwm-cells = <2>;
};

n: node {
        pwms = <&pwm1 1 200000 PWM_POLARITY_NORMAL>,
               <&pwm2 3 100000 PWM_POLARITY_INVERTED>;
        pwm-names = "alpha", "beta";
};

Bindings fragment for the “vnd,pwm” compatible:

pwm-cells:
  - channel
  - period
  - flags

Example usage:

DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, channel) // 1
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, channel)  // 3
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, period)  // 200000
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, period)   // 100000
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, flags)   // PWM_POLARITY_NORMAL
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, flags)    // PWM_POLARITY_INVERTED

Return

the cell value in the specifier at the named element

See

DT_PHA_BY_NAME()

Parameters

• node_id: node identifier for a node with a pwms property

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

• cell: lowercase-and-underscores cell name

DT_PWMS_CELL(node_id, cell)

Equivalent to DT_PWMS_CELL_BY_IDX(node_id, 0, cell)

Return

the cell value at index 0

See

DT_PWMS_CELL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• cell: lowercase-and-underscores cell name

DT_PWMS_CHANNEL_BY_IDX(node_id, idx)

Get a PWM specifier’s channel cell value at an index.

This macro only works for PWM specifiers with cells named “channel”. Refer to the node’s binding to check if necessary.

This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, channel).

Return

the channel cell value at index “idx”

See

DT_PWMS_CELL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• idx: logical index into pwms property

DT_PWMS_CHANNEL_BY_NAME(node_id, name)

Get a PWM specifier’s channel cell value by name.

This macro only works for PWM specifiers with cells named “channel”. Refer to the node’s binding to check if necessary.

This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, channel).

Return

the channel cell value in the specifier at the named element

See

DT_PWMS_CELL_BY_NAME()

Parameters

• node_id: node identifier for a node with a pwms property

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_PWMS_CHANNEL(node_id)

Equivalent to DT_PWMS_CHANNEL_BY_IDX(node_id, 0)

Return

the channel cell value at index 0

See

DT_PWMS_CHANNEL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

DT_PWMS_PERIOD_BY_IDX(node_id, idx)

Get PWM specifier’s period cell value at an index.

This macro only works for PWM specifiers with cells named “period”. Refer to the node’s binding to check if necessary.

This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, period).

Return

the period cell value at index “idx”

See

DT_PWMS_CELL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• idx: logical index into pwms property

DT_PWMS_PERIOD_BY_NAME(node_id, name)

Get a PWM specifier’s period cell value by name.

This macro only works for PWM specifiers with cells named “period”. Refer to the node’s binding to check if necessary.

This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, period).

Return

the period cell value in the specifier at the named element

See

DT_PWMS_CELL_BY_NAME()

Parameters

• node_id: node identifier for a node with a pwms property

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_PWMS_PERIOD(node_id)

Equivalent to DT_PWMS_PERIOD_BY_IDX(node_id, 0)

Return

the period cell value at index 0

See

DT_PWMS_PERIOD_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

DT_PWMS_FLAGS_BY_IDX(node_id, idx)

Get a PWM specifier’s flags cell value at an index.

This macro expects PWM specifiers with cells named “flags”. If there is no “flags” cell in the PWM specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.

This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, flags).

Return

the flags cell value at index “idx”, or zero if there is none

See

DT_PWMS_CELL_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

• idx: logical index into pwms property

DT_PWMS_FLAGS_BY_NAME(node_id, name)

Get a PWM specifier’s flags cell value by name.

This macro expects PWM specifiers with cells named “flags”. If there is no “flags” cell in the PWM specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.

This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, flags) if there is a flags cell, but expands to zero if there is none.

Return

the flags cell value in the specifier at the named element, or zero if there is none

See

DT_PWMS_CELL_BY_NAME()

Parameters

• node_id: node identifier for a node with a pwms property

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_PWMS_FLAGS(node_id)

Equivalent to DT_PWMS_FLAGS_BY_IDX(node_id, 0)

Return

the flags cell value at index 0, or zero if there is none

See

DT_PWMS_FLAGS_BY_IDX()

Parameters

• node_id: node identifier for a node with a pwms property

DT_INST_PWMS_LABEL_BY_IDX(inst, idx)

Get a label property from a DT_DRV_COMPAT instance’s pwms property by name.

Return

the label property of the node referenced at index “idx”

See

DT_PWMS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into pwms property

DT_INST_PWMS_LABEL_BY_NAME(inst, name)

Get a label property from a DT_DRV_COMPAT instance’s pwms property by name.

Return

the label property of the node referenced at the named element

See

DT_PWMS_LABEL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_INST_PWMS_LABEL(inst)

Equivalent to DT_INST_PWMS_LABEL_BY_IDX(inst, 0)

Return

the label property of the node referenced at index 0

See

DT_PWMS_LABEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_PWMS_CELL_BY_IDX(inst, idx, cell)

Get a DT_DRV_COMPAT instance’s PWM specifier’s cell value at an index.

Return

the cell value at index “idx”

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into pwms property

• cell: lowercase-and-underscores cell name

DT_INST_PWMS_CELL_BY_NAME(inst, name, cell)

Get a DT_DRV_COMPAT instance’s PWM specifier’s cell value by name.

Return

the cell value in the specifier at the named element

See

DT_PWMS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

• cell: lowercase-and-underscores cell name

DT_INST_PWMS_CELL(inst, cell)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, 0, cell)

Return

the cell value at index 0

Parameters

• inst: DT_DRV_COMPAT instance number

• cell: lowercase-and-underscores cell name

DT_INST_PWMS_CHANNEL_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, channel)

Return

the channel cell value at index “idx”

See

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into pwms property

DT_INST_PWMS_CHANNEL_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, channel)

Return

the channel cell value in the specifier at the named element

See

DT_INST_PWMS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_INST_PWMS_CHANNEL(inst)

Equivalent to DT_INST_PWMS_CHANNEL_BY_IDX(inst, 0)

Return

the channel cell value at index 0

See

DT_INST_PWMS_CHANNEL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_PWMS_PERIOD_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, period)

Return

the period cell value at index “idx”

See

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into pwms property

DT_INST_PWMS_PERIOD_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, period)

Return

the period cell value in the specifier at the named element

See

DT_INST_PWMS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_INST_PWMS_PERIOD(inst)

Equivalent to DT_INST_PWMS_PERIOD_BY_IDX(inst, 0)

Return

the period cell value at index 0

See

DT_INST_PWMS_PERIOD_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_PWMS_FLAGS_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, flags)

Return

the flags cell value at index “idx”, or zero if there is none

See

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

• idx: logical index into pwms property

DT_INST_PWMS_FLAGS_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, flags)

Return

the flags cell value in the specifier at the named element, or zero if there is none

See

DT_INST_PWMS_CELL_BY_NAME()

Parameters

• inst: DT_DRV_COMPAT instance number

• name: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property

DT_INST_PWMS_FLAGS(inst)

Equivalent to DT_INST_PWMS_FLAGS_BY_IDX(inst, 0)

Return

the flags cell value at index 0, or zero if there is none

See

DT_INST_PWMS_FLAGS_BY_IDX()

Parameters

• inst: DT_DRV_COMPAT instance number

SPI

These conveniences may be used for nodes which describe either SPI controllers or devices, depending on the case.

group devicetree-spi

Defines

DT_SPI_HAS_CS_GPIOS(spi)

Does a SPI controller node have chip select GPIOs configured?

SPI bus controllers use the “cs-gpios” property for configuring chip select GPIOs. Its value is a phandle-array which specifies the chip select lines.

Example devicetree fragment:

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;
};

spi2: spi@... {
        compatible = "vnd,spi";
};

Example usage:

DT_SPI_HAS_CS_GPIOS(DT_NODELABEL(spi1)) // 1
DT_SPI_HAS_CS_GPIOS(DT_NODELABEL(spi2)) // 0

Return

1 if “spi” has a cs-gpios property, 0 otherwise

Parameters

• spi: a SPI bus controller node identifier

DT_SPI_NUM_CS_GPIOS(spi)

Number of chip select GPIOs in a SPI controller’s cs-gpios property.

Example devicetree fragment:

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;
};

spi2: spi@... {
        compatible = "vnd,spi";
};

Example usage:

DT_SPI_NUM_CS_GPIOS(DT_NODELABEL(spi1)) // 2
DT_SPI_NUM_CS_GPIOS(DT_NODELABEL(spi2)) // 0

Return

Logical length of spi’s cs-gpios property, or 0 if “spi” doesn’t have a cs-gpios property

Parameters

• spi: a SPI bus controller node identifier

DT_SPI_DEV_HAS_CS_GPIOS(spi_dev)

Does a SPI device have a chip select line configured? Example devicetree fragment:

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;

        a: spi-dev-a@0 {
                reg = <0>;
        };

        b: spi-dev-b@1 {
                reg = <1>;
        };
};

spi2: spi@... {
        compatible = "vnd,spi";
        c: spi-dev-c@0 {
                reg = <0>;
        };
};

Example usage:

DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(a)) // 1
DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(b)) // 1
DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(c)) // 0

Return

1 if spi_dev’s bus node DT_BUS(spi_dev) has a chip select pin at index DT_REG_ADDR(spi_dev), 0 otherwise

Parameters

• spi_dev: a SPI device node identifier

DT_SPI_DEV_CS_GPIOS_LABEL(spi_dev)

Get a SPI device’s chip select GPIO controller’s label property.

Example devicetree fragment:

gpio1: gpio@... {
        label = "GPIO_1";
};

gpio2: gpio@... {
        label = "GPIO_2";
};

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;

        a: spi-dev-a@0 {
                reg = <0>;
        };

        b: spi-dev-b@1 {
                reg = <1>;
        };
};

Example usage:

DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(a)) // "GPIO_1"
DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(b)) // "GPIO_2"

Return

label property of spi_dev’s chip select GPIO controller

Parameters

• spi_dev: a SPI device node identifier

DT_SPI_DEV_CS_GPIOS_PIN(spi_dev)

Get a SPI device’s chip select GPIO pin number.

It’s an error if the GPIO specifier for spi_dev’s entry in its bus node’s cs-gpios property has no pin cell.

Example devicetree fragment:

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;

        a: spi-dev-a@0 {
                reg = <0>;
        };

        b: spi-dev-b@1 {
                reg = <1>;
        };
};

Example usage:

DT_SPI_DEV_CS_GPIOS_PIN(DT_NODELABEL(a)) // 10
DT_SPI_DEV_CS_GPIOS_PIN(DT_NODELABEL(b)) // 20

Return

pin number of spi_dev’s chip select GPIO

Parameters

• spi_dev: a SPI device node identifier

DT_SPI_DEV_CS_GPIOS_FLAGS(spi_dev)

Get a SPI device’s chip select GPIO flags.

Example devicetree fragment:

spi1: spi@... {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>;

        a: spi-dev-a@0 {
                reg = <0>;
        };
};

Example usage:

DT_SPI_DEV_CS_GPIOS_FLAGS(DT_NODELABEL(a)) // GPIO_ACTIVE_LOW

If the GPIO specifier for spi_dev’s entry in its bus node’s cs-gpios property has no flags cell, this expands to zero.

Return

flags value of spi_dev’s chip select GPIO specifier, or zero if there is none

Parameters

• spi_dev: a SPI device node identifier

DT_INST_SPI_DEV_HAS_CS_GPIOS(inst)

Equivalent to DT_SPI_DEV_HAS_CS_GPIOS(DT_DRV_INST(inst)).

Return

1 if the instance’s bus has a CS pin at index DT_INST_REG_ADDR(inst), 0 otherwise

See

DT_SPI_DEV_HAS_CS_GPIOS()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_SPI_DEV_CS_GPIOS_LABEL(inst)

Get GPIO controller name for a SPI device instance This is equivalent to DT_SPI_DEV_CS_GPIOS_LABEL(DT_DRV_INST(inst)).

Return

label property of the instance’s chip select GPIO controller

See

DT_SPI_DEV_CS_GPIOS_LABEL()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_SPI_DEV_CS_GPIOS_PIN(inst)

Equivalent to DT_SPI_DEV_CS_GPIOS_PIN(DT_DRV_INST(inst)).

Return

pin number of the instance’s chip select GPIO

See

DT_SPI_DEV_CS_GPIOS_PIN()

Parameters

• inst: DT_DRV_COMPAT instance number

DT_INST_SPI_DEV_CS_GPIOS_FLAGS(inst)

DT_SPI_DEV_CS_GPIOS_FLAGS(DT_DRV_INST(inst)).

Return

flags value of the instance’s chip select GPIO specifier, or zero if there is none

See

DT_SPI_DEV_CS_GPIOS_FLAGS()

Parameters

• inst: DT_DRV_COMPAT instance number

Chosen nodes

The special /chosen node contains properties whose values describe system-wide settings. The DT_CHOSEN() macro can be used to get a node identifier for a chosen node.

group devicetree-generic-chosen

Defines

DT_CHOSEN(prop)

Get a node identifier for a /chosen node property.

This is only valid to call if DT_HAS_CHOSEN(prop) is 1.

Return

a node identifier for the chosen node property

Parameters

• prop: lowercase-and-underscores property name for the /chosen node

DT_HAS_CHOSEN(prop)

Test if the devicetree has a /chosen node.

Return

1 if the chosen property exists and refers to a node, 0 otherwise

Parameters

• prop: lowercase-and-underscores devicetree property

There are also conveniences for commonly used zephyr-specific properties of the /chosen node. (These may also be set in dts_fixup.h files for now, though this mechanism is deprecated.)

group devicetree-zephyr

Defines

DT_CHOSEN_ZEPHYR_ENTROPY_LABEL

If there is a chosen node zephyr,entropy property which has a label property, that property’s value. Undefined otherwise.

DT_CHOSEN_ZEPHYR_FLASH_CONTROLLER_LABEL

If there is a chosen node zephyr,flash-controller property which has a label property, that property’s value. Undefined otherwise.

DT_CHOSEN_ZEPHYR_CAN_PRIMARY_LABEL

If there is a chosen node zephyr,can-primary property which has a label property, that property’s value. Undefined otherwise.

The following table documents some commonly used Zephyr-specific chosen nodes.

Often, a chosen node’s label property will be used to set the default value of a Kconfig option which in turn configures a hardware-specific subsystem setting. This is usually for backwards compatibility in cases when the Kconfig option predates devicetree support in Zephyr. In other cases, there is no Kconfig option, and the devicetree node’s label property is used directly in the source code to specify a device name.

Zephyr-specific chosen properties

Property	Purpose
zephyr,bt-c2h-uart	Sets default CONFIG_BT_CTLR_TO_HOST_UART_DEV_NAME
zephyr,bt-mon-uart	Sets default CONFIG_BT_MONITOR_ON_DEV_NAME
zephyr,bt-uart	Sets default CONFIG_BT_UART_ON_DEV_NAME
zephyr,can-primary	Sets the primary CAN controller
zephyr,ccm	Core-Coupled Memory node on some STM32 SoCs
zephyr,code-partition	Flash partition that the Zephyr image’s text section should be linked into
zephyr,console	Sets default CONFIG_UART_CONSOLE_ON_DEV_NAME
zephyr,dtcm	Data Tightly Coupled Memory node on some Arm SoCs
zephyr,entropy	A device which can be used as a system-wide entropy source
zephyr,flash	A node whose reg is sometimes used to set the defaults for CONFIG_FLASH_BASE_ADDRESS and CONFIG_FLASH_SIZE
zephyr,flash-controller	The node corresponding to the flash controller device for the zephyr,flash node
zephyr,ipc	Used by the OpenAMP subsystem to specify the inter-process communication (IPC) device
zephyr,ipc_shm	A node whose reg is used by the OpenAMP subsystem to determine the base address and size of the shared memory (SHM) usable for interprocess-communication (IPC)
zephyr,itcm	Instruction Tightly Coupled Memory node on some Arm SoCs
zephyr,shell-uart	Sets default CONFIG_UART_SHELL_ON_DEV_NAME
zephyr,sram	A node whose reg sets the base address and size of SRAM memory available to the Zephyr image, used during linking
zephyr,uart-mcumgr	UART used for Device Management
zephyr,uart-pipe	Sets default CONFIG_UART_PIPE_ON_DEV_NAME
zephyr,usb-device	USB device node. If defined and has a vbus-gpios property, these will be used by the USB subsystem to enable/disable VBUS