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_INVALID_NODE

Name for an invalid node identifier.

This supports cases where factored macros can be invoked from paths where devicetree data may or may not be available. It is a preprocessor identifier that does not match any valid devicetree node identifier.

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

Parameters

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

Returns

node identifier for the node with that path

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.

Parameters

• label – lowercase-and-underscores node label name

Returns

node identifier for the node with that label

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

Parameters

• alias – lowercase-and-underscores alias name.

Returns

node identifier for the node with that alias

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.

Parameters

• inst – instance number for compatible “compat”

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

Returns

node identifier for the node with that instance number and compatible

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))

Parameters

• node_id – node identifier

Returns

a node identifier for the node’s parent

DT_INST_PARENT(inst)

Get a DT_DRV_COMPAT parent’s node identifier.

Parameters

• inst – instance number

Returns

a node identifier for the instance’s parent

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))

Parameters

• node_id – node identifier

Returns

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

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.

Parameters

• node_id – node identifier

• child – lowercase-and-underscores child node name

Returns

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

DT_COMPAT_GET_ANY_STATUS_OKAY(compat)

Get a node identifier for a status “okay” node with a compatible.

Use this if you want to get an arbitrary enabled node with a given compatible, and you do not care which one you get. If any enabled nodes with the given compatible exist, a node identifier for one of them is returned. Otherwise, DT_INVALID_NODE is returned.

Example devicetree fragment:

 node-a {
    compatible = "vnd,device";
    status = "okay";
 };

 node-b {
    compatible = "vnd,device";
    status = "okay";
 };

 node-c {
    compatible = "vnd,device";
    status = "disabled";
 };

Example usage:

DT_COMPAT_GET_ANY_STATUS_OKAY(vnd_device)

This expands to a node identifier for either node-a or node-b. It will not expand to a node identifier for node-c, because that node does not have status “okay”.

Parameters

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

Returns

node identifier for a node with that compatible, or DT_INVALID_NODE

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) // “/”

Parameters

• node_id – node identifier

Returns

the node’s full path in the devicetree

DT_NODE_FULL_NAME(node_id)

Get a devicetree node’s name with unit-address as a string literal.

This returns the node name and unit-address from a node identifier.

Example devicetree fragment:

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

Example usage:

DT_NODE_FULL_NAME(DT_NODELABEL(node)) // “my-node@12345678”

Parameters

• node_id – node identifier

Returns

the node’s name with unit-address as a string in the devicetree

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.

Parameters

• node_id1 – first node identifer

• node_id2 – second node identifier

Returns

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

Property access

The following general-purpose macros can be used to access node properties. There are special-purpose APIs for accessing the ranges property, 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.

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

Returns

a representation of the property’s value

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 ranges, dma-ranges, reg or interrupts properties.

For other properties, behavior is undefined.

Parameters

• node_id – node identifier

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

Returns

the property’s length

DT_PROP_LEN_OR(node_id, prop, default_value)

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

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

Otherwise, this expands to default_value.

Parameters

• node_id – node identifier

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

• default_value – a fallback value to expand to

Returns

the property’s length or the given default value

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

Parameters

• node_id – node identifier

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

• idx – index to check

Returns

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

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

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

• idx – the index to get

Returns

a representation of the idx-th element of the property

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

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

• default_value – a fallback value to expand to

Returns

the property’s value or default_value

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

Parameters

• node_id – node identifier

Returns

node’s label property value

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

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

Returns

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

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

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

• default_idx_value – a fallback index value to expand to

Returns

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

DT_STRING_TOKEN(node_id, prop)

Get a string property’s value as a token.

This removes “the quotes” from string-valued properties, and converts non-alphanumeric characters to underscores. That can be useful, for example, when programmatically using the value to form a C variable or code.

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string

Example usage:

DT_STRING_TOKEN(DT_NODELABEL(n1), prop) // foo
DT_STRING_TOKEN(DT_NODELABEL(n2), prop) // FOO
DT_STRING_TOKEN(DT_NODELABEL(n3), prop) // 123_foo

Notice how:

• Unlike C identifiers, the property values may begin with a number. It’s the user’s responsibility not to use such values as the name of a C identifier.

• The uppercased “FOO” in the DTS remains FOO as a token. It is not converted to foo.

• The whitespace in the DTS “123 foo” string is converted to 123_foo as a token.

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property string name

Returns

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

DT_STRING_UPPER_TOKEN(node_id, prop)

Like DT_STRING_TOKEN(), but uppercased.

This removes “the quotes and capitalize” from string-valued properties, and converts non-alphanumeric characters to underscores. That can be useful, for example, when programmatically using the value to form a C variable or code.

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string

Example usage:

DT_STRING_UPPER_TOKEN(DT_NODELABEL(n1), prop) // FOO
DT_STRING_UPPER_TOKEN(DT_NODELABEL(n2), prop) // 123_FOO

Notice how:

• Unlike C identifiers, the property values may begin with a number. It’s the user’s responsibility not to use such values as the name of a C identifier.

• The lowercased “foo” in the DTS becomes FOO as a token, i.e. it is uppercased.

• The whitespace in the DTS “123 foo” string is converted to 123_FOO as a token, i.e. it is uppercased and whitespace becomes an underscore.

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property string name

Returns

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

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.

Parameters

• node_id – node identifier

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

Returns

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

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.

Parameters

• node_id – node identifier

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

Returns

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

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

Parameters

• node_id – node identifier

• phs – lowercase-and-underscores property with type “phandle”, “phandles”, or “phandle-array”

• idx – logical index into “phs”, which must be zero if “phs” has type “phandle”

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

Returns

the property’s value

DT_PROP_BY_PHANDLE_IDX_OR(node_id, phs, idx, prop, default_value)

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

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

Otherwise, this expands to default_value.

Parameters

• node_id – node identifier

• phs – lowercase-and-underscores property with type “phandle”, “phandles”, or “phandle-array”

• idx – logical index into “phs”, which must be zero if “phs” has type “phandle”

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

• default_value – a fallback value to expand to

Returns

the property’s value

DT_PROP_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).

Parameters

• node_id – node identifier

• ph – lowercase-and-underscores property of “node_id” with type “phandle”

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

Returns

the property’s value

DT_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

Parameters

• node_id – node identifier

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

• idx – logical index into “pha”

• cell – lowercase-and-underscores cell name within the specifier at “pha” index “idx”

Returns

the cell’s value

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

Parameters

• node_id – node identifier

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

• idx – logical index into “pha”

• cell – lowercase-and-underscores cell name within the specifier at “pha” index “idx”

• default_value – a fallback value to expand to

Returns

the cell’s value or “default_value”

DT_PHA(node_id, pha, cell)

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

Parameters

• node_id – node identifier

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

• cell – lowercase-and-underscores cell name

Returns

the cell’s value

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

Parameters

• node_id – node identifier

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

• cell – lowercase-and-underscores cell name

• default_value – a fallback value to expand to

Returns

the cell’s value or default_value

DT_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

Parameters

• node_id – node identifier

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

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

• cell – lowercase-and-underscores cell name in the named specifier

Returns

the cell’s value

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

Parameters

• node_id – node identifier

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

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

• cell – lowercase-and-underscores cell name in the named specifier

• default_value – a fallback value to expand to

Returns

the cell’s value or default_value

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

Parameters

• node_id – node identifier

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

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

Returns

a node identifier for the node with that phandle

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

Parameters

• node_id – node identifier

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

• idx – index into “prop”

Returns

node identifier for the node with the phandle at that index

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

Parameters

• node_id – node identifier

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

Returns

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

ranges property

Use these APIs instead of Property access to access the ranges property. Because this property’s semantics are defined by the devicetree specification, these macros can be used even for nodes without matching bindings. However, they take on special semantics when the node’s binding indicates it is a PCIe bus node, as defined in the PCI Bus Binding to: IEEE Std 1275-1994 Standard for Boot (Initialization Configuration) Firmware

group devicetree-ranges-prop

Defines

DT_NUM_RANGES(node_id)

Get the number of range blocks in the ranges property.

Use this instead of DT_PROP_LEN(node_id, ranges).

Example devicetree fragment:

pcie0: pcie@0 {
        compatible = "intel,pcie";
        reg = <0 1>;
        #address-cells = <3>;
        #size-cells = <2>;

        ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                 <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                 <0x3000000 0x80 0 0x80 0 0x80 0>;
};

other: other@1 {
        reg = <1 1>;

        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

DT_NUM_RANGES(DT_NODELABEL(pcie0)) // 3
DT_NUM_RANGES(DT_NODELABEL(other)) // 2

Parameters

• node_id – node identifier

DT_RANGES_HAS_IDX(node_id, idx)

Is “idx” a valid range block index?

If this returns 1, then DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(node_id, idx), DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(node_id, idx) or DT_RANGES_LENGTH_BY_IDX(node_id, idx) are valid. For DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx) the return value of DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(node_id, idx) will indicate validity. If it returns 0, it is an error to use those macros with index “idx”, including DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx).

Example devicetree fragment:

pcie0: pcie@0 {
        compatible = "intel,pcie";
        reg = <0 1>;
        #address-cells = <3>;
        #size-cells = <2>;

        ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                 <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                 <0x3000000 0x80 0 0x80 0 0x80 0>;
};

other: other@1 {
        reg = <1 1>;

        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 0) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 1) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 2) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(pcie0), 3) // 0
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 0) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 1) // 1
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 2) // 0
DT_RANGES_HAS_IDX(DT_NODELABEL(other), 3) // 0

Parameters

• node_id – node identifier

• idx – index to check

Returns

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

DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(node_id, idx)

Does a ranges property have child bus flags at index?

If this returns 1, then DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx) is valid. If it returns 0, it is an error to use this macro with index “idx”. This macro only returns 1 for PCIe buses (i.e. nodes whose bindings specify they are “pcie” bus nodes.)

Example devicetree fragment:

parent {
        #address-cells = <2>;

        pcie0: pcie@0 {
                compatible = "intel,pcie";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;

                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };

        other: other@1 {
                reg = <0 1 1>;

                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 0) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 1) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 2) // 1
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(pcie0), 3) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 0) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 1) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 2) // 0
DT_RANGES_HAS_CHILD_BUS_FLAGS_AT_IDX(DT_NODELABEL(other), 3) // 0

Parameters

• node_id – node identifier

• idx – logical index into the ranges array

Returns

1 if “idx” is a valid child bus flags index, 0 otherwise.

DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(node_id, idx)

Get the ranges property child bus flags at index.

When the node is a PCIe bus, the Child Bus Address has an extra cell used to store some flags, thus this cell is extracted from the Child Bus Address as Child Bus Flags field.

Example devicetree fragments:

parent {
        #address-cells = <2>;

        pcie0: pcie@0 {
                compatible = "intel,pcie";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;

                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };
};

Example usage:

DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x1000000
DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x2000000
DT_RANGES_CHILD_BUS_FLAGS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x3000000

Parameters

• node_id – node identifier

• idx – logical index into the ranges array

Returns

range child bus flags field at idx

DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(node_id, idx)

Get the ranges property child bus address at index.

When the node is a PCIe bus, the Child Bus Address has an extra cell used to store some flags, thus this cell is removed from the Child Bus Address.

Example devicetree fragments:

parent {
        #address-cells = <2>;

        pcie0: pcie@0 {
                compatible = "intel,pcie";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;

                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };

        other: other@1 {
                reg = <0 1 1>;

                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x10000000
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 0) // 0
DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 1) // 0x10000000

Parameters

• node_id – node identifier

• idx – logical index into the ranges array

Returns

range child bus address field at idx

DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(node_id, idx)

Get the ranges property parent bus address at index.

Similarly to DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(), this properly accounts for child bus flags cells when the node is a PCIe bus.

Example devicetree fragment:

parent {
        #address-cells = <2>;

        pcie0: pcie@0 {
                compatible = "intel,pcie";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;

                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };

        other: other@1 {
                reg = <0 1 1>;

                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x3eff0000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x10000000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 0) // 0x3eff0000
DT_RANGES_PARENT_BUS_ADDRESS_BY_IDX(DT_NODELABEL(other), 1) // 0x10000000

Parameters

• node_id – node identifier

• idx – logical index into the ranges array

Returns

range parent bus address field at idx

DT_RANGES_LENGTH_BY_IDX(node_id, idx)

Get the ranges property length at index.

Similarly to DT_RANGES_CHILD_BUS_ADDRESS_BY_IDX(), this properly accounts for child bus flags cells when the node is a PCIe bus.

Example devicetree fragment:

parent {
        #address-cells = <2>;

        pcie0: pcie@0 {
                compatible = "intel,pcie";
                reg = <0 0 1>;
                #address-cells = <3>;
                #size-cells = <2>;

                ranges = <0x1000000 0 0 0 0x3eff0000 0 0x10000>,
                         <0x2000000 0 0x10000000 0 0x10000000 0 0x2eff0000>,
                         <0x3000000 0x80 0 0x80 0 0x80 0>;
        };

        other: other@1 {
                reg = <0 1 1>;

                ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                         <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
        };
};

Example usage:

DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 0) // 0x10000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 1) // 0x2eff0000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(pcie0), 2) // 0x8000000000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(other), 0) // 0x10000
DT_RANGES_LENGTH_BY_IDX(DT_NODELABEL(other), 1) // 0x2eff0000

Parameters

• node_id – node identifier

• idx – logical index into the ranges array

Returns

range length field at idx

DT_FOREACH_RANGE(node_id, fn)

Invokes “fn” for each entry of “node_id” ranges property.

The macro “fn” must take two parameters, “node_id” which will be the node identifier of the node with the ranges property and “idx” the index of the ranges block.

Example devicetree fragment:

n: node@0 {
        reg = <0 0 1>;

        ranges = <0x0 0x0 0x0 0x3eff0000 0x10000>,
                 <0x0 0x10000000 0x0 0x10000000 0x2eff0000>;
};

Example usage:

#define RANGE_LENGTH(node_id, idx) DT_RANGES_LENGTH_BY_IDX(node_id, idx),

const uint64_t *ranges_length[] = {
        DT_FOREACH_RANGE(DT_NODELABEL(n), RANGE_LENGTH)
};

This expands to:

const char *ranges_length[] = {
    0x10000, 0x2eff0000,
};

Parameters

• node_id – node identifier

• fn – macro to invoke

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

Parameters

• node_id – node identifier

Returns

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

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

Parameters

• node_id – node identifier

• idx – index to check

Returns

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

DT_REG_ADDR_BY_IDX(node_id, idx)

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

Parameters

• node_id – node identifier

• idx – index of the register whose address to return

Returns

address of the idx-th register block

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.

Parameters

• node_id – node identifier

• idx – index of the register whose size to return

Returns

size of the idx-th register block

DT_REG_ADDR(node_id)

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

Equivalent to DT_REG_ADDR_BY_IDX(node_id, 0).

Parameters

• node_id – node identifier

Returns

node’s register block address

DT_REG_SIZE(node_id)

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

Equivalent to DT_REG_SIZE_BY_IDX(node_id, 0).

Parameters

• node_id – node identifier

Returns

node’s only register block’s size

DT_REG_ADDR_BY_NAME(node_id, name)

Get a register block’s base address by name.

Parameters

• node_id – node identifier

• name – lowercase-and-underscores register specifier name

Returns

address of the register block specified by name

DT_REG_SIZE_BY_NAME(node_id, name)

Get a register block’s size by name.

Parameters

• node_id – node identifier

• name – lowercase-and-underscores register specifier name

Returns

size of the register block specified by 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).

Parameters

• node_id – node identifier

Returns

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

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.

Parameters

• node_id – node identifier

• idx – index to check

Returns

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

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.

Parameters

• node_id – node identifier

• idx – index to check

• cell – named cell value whose existence to check

Returns

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

DT_IRQ_HAS_CELL(node_id, cell)

Equivalent to DT_IRQ_HAS_CELL_AT_IDX(node_id, 0, cell)

Parameters

• node_id – node identifier

• cell – named cell value whose existence to check

Returns

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

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.

Parameters

• node_id – node identifier

• name – lowercase-and-underscores interrupt specifier name

Returns

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

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

Parameters

• node_id – node identifier

• idx – logical index into the interrupt specifier array

• cell – cell name specifier

Returns

the named value at the specifier given by the index

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.

Parameters

• node_id – node identifier

• name – lowercase-and-underscores interrupt specifier name

• cell – cell name specifier

Returns

the named value at the specifier given by the index

DT_IRQ(node_id, cell)

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

Parameters

• node_id – node identifier

• cell – cell name specifier

Returns

the named value at that index

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

Parameters

• node_id – node identifier

Returns

the interrupt number for the node’s only interrupt

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

DT_FOREACH_CHILD_VARGS(node_id, fn, ...)

Invokes “fn” for each child of “node_id” with multiple arguments.

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

See also

DT_FOREACH_CHILD

Parameters

• node_id – node identifier

• fn – macro to invoke

• ... – variable number of arguments to pass to fn

DT_FOREACH_CHILD_STATUS_OKAY(node_id, fn)

Call “fn” on the child nodes with status “okay”.

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

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

Parameters

• node_id – node identifier

• fn – macro to invoke

DT_FOREACH_CHILD_STATUS_OKAY_VARGS(node_id, fn, ...)

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

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

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

See also

DT_FOREACH_CHILD_STATUS_OKAY

Parameters

• node_id – node identifier

• fn – macro to invoke

• ... – variable number of arguments to pass to fn

DT_FOREACH_PROP_ELEM(node_id, prop, fn)

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

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

Example devicetree fragment:

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

Example usage:

#define TIMES_TWO(node_id, prop, idx) \
        (2 * DT_PROP_BY_IDX(node_id, prop, idx)),

int array[] = {
        DT_FOREACH_PROP_ELEM(DT_NODELABEL(n), my_ints, TIMES_TWO)
};

This expands to:

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

In general, this macro expands to:

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

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

The “prop” argument must refer to a property with type string, array, uint8-array, string-array, phandles, or phandle-array. It is an error to use this macro with properties of other types.

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

• fn – macro to invoke

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

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

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

See also

DT_FOREACH_PROP_ELEM

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

• fn – macro to invoke

• ... – variable number of arguments to pass to fn

DT_FOREACH_STATUS_OKAY(compat, fn)

Invokes “fn” for each status “okay” node of a compatible.

This macro expands to:

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

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

Example devicetree fragment:

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

Example usage:

DT_FOREACH_STATUS_OKAY(foo, DT_NODE_PATH)

This expands to one of the following:

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

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

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

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

Parameters

• compat – lowercase-and-underscores devicetree compatible

• fn – Macro to call for each enabled node. Must accept a node_id as its only parameter.

DT_FOREACH_STATUS_OKAY_VARGS(compat, fn, ...)

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

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

Example devicetree fragment:

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

Example usage:

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

This expands to one of the following:

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

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

Parameters

• compat – lowercase-and-underscores devicetree compatible

• fn – Macro to call for each enabled node. Must accept a node_id as its only parameter.

• ... – Additional arguments to pass to “fn”

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.

Parameters

• node_id – a node identifier

Returns

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

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)

Parameters

• node_id – a node identifier

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

Returns

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

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

Parameters

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

Returns

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

DT_NUM_INST_STATUS_OKAY(compat)

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

Parameters

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

Returns

Number of instances with status “okay”

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.

Parameters

• node_id – node identifier

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

Returns

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

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, without quotes

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

Parameters

• node_id – node identifier

• prop – lowercase-and-underscores property name

Returns

1 if the node has the property, 0 otherwise.

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.

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”

Returns

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

DT_PHA_HAS_CELL(node_id, pha, cell)

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

Parameters

• node_id – node identifier

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

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

Returns

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

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.

Parameters

• node_id – Node identifier

Returns

the node’s dependency ordinal as an integer literal

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.

Parameters

• node_id – Node identifier

Returns

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

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.

Parameters

• node_id – Node identifier

Returns

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

DT_INST_DEP_ORD(inst)

Get a DT_DRV_COMPAT instance’s dependency ordinal.

Equivalent to DT_DEP_ORD(DT_DRV_INST(inst)).

Parameters

• inst – instance number

Returns

The instance’s dependency ordinal

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

Parameters

• inst – instance number

Returns

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

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

Parameters

• inst – instance number

Returns

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

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

Parameters

• node_id – node identifier

Returns

a node identifier for the node’s bus controller

DT_BUS_LABEL(node_id)

Node’s bus controller’s label property.

Parameters

• node_id – node identifier

Returns

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

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

Parameters

• node_id – node identifier

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

Returns

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

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.

Parameters

• inst – instance number

Returns

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

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 also

DT_FOREACH_CHILD

Parameters

• inst – instance number

• fn – macro to invoke on each child node identifier

DT_INST_FOREACH_CHILD_VARGS(inst, fn, ...)

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

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

See also

DT_FOREACH_CHILD

Parameters

• inst – instance number

• fn – macro to invoke on each child node identifier

• ... – variable number of arguments to pass to fn

DT_INST_ENUM_IDX(inst, prop)

Get a DT_DRV_COMPAT value’s index into its enumeration values.

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

Returns

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

DT_INST_ENUM_IDX_OR(inst, prop, default_idx_value)

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

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• default_idx_value – a fallback index value to expand to

Returns

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

DT_INST_PROP(inst, prop)

Get a DT_DRV_COMPAT instance property.

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

Returns

a representation of the property’s value

DT_INST_PROP_LEN(inst, prop)

Get a DT_DRV_COMPAT property length.

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

Returns

logical length of the property

DT_INST_PROP_HAS_IDX(inst, prop, idx)

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

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• idx – index to check

Returns

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

DT_INST_PROP_BY_IDX(inst, prop, idx)

Get a DT_DRV_COMPAT element value in an array property.

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• idx – the index to get

Returns

a representation of the idx-th element of the property

DT_INST_PROP_OR(inst, prop, default_value)

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

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• default_value – a fallback value to expand to

Returns

DT_INST_PROP(inst, prop) or default_value

DT_INST_LABEL(inst)

Get a DT_DRV_COMPAT instance’s “label” property.

Parameters

• inst – instance number

Returns

instance’s label property value

DT_INST_PROP_BY_PHANDLE(inst, ph, prop)

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

Parameters

• inst – instance number

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

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

Returns

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

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.

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

Returns

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

DT_INST_PHA_BY_IDX(inst, pha, idx, cell)

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

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”

Returns

the value of the cell inside 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.

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

Returns

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

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)

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

Returns

the cell value

DT_INST_PHA_OR(inst, pha, cell, default_value)

Like DT_INST_PHA(), but with a fallback to 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

Returns

DT_INST_PHA(inst, pha, cell) or default_value

DT_INST_PHA_BY_NAME(inst, pha, name, cell)

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

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

Returns

the cell value

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.

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

Returns

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

DT_INST_PHANDLE_BY_NAME(inst, pha, name)

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

Parameters

• inst – instance number

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

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

Returns

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

DT_INST_PHANDLE_BY_IDX(inst, prop, idx)

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

Parameters

• inst – instance number

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

• idx – index into “prop”

Returns

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

DT_INST_PHANDLE(inst, prop)

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

Parameters

• inst – instance number

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

Returns

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

DT_INST_REG_HAS_IDX(inst, idx)

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

Parameters

• inst – instance number

• idx – index to check

Returns

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

DT_INST_REG_ADDR_BY_IDX(inst, idx)

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

Parameters

• inst – instance number

• idx – index of the register whose address to return

Returns

address of the instance’s idx-th register block

DT_INST_REG_SIZE_BY_IDX(inst, idx)

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

Parameters

• inst – instance number

• idx – index of the register whose size to return

Returns

size of the instance’s idx-th register block

DT_INST_REG_ADDR_BY_NAME(inst, name)

Get a DT_DRV_COMPAT’s register block address by name.

Parameters

• inst – instance number

• name – lowercase-and-underscores register specifier name

Returns

address of the register block with the given name

DT_INST_REG_SIZE_BY_NAME(inst, name)

Get a DT_DRV_COMPAT’s register block size by name.

Parameters

• inst – instance number

• name – lowercase-and-underscores register specifier name

Returns

size of the register block with the given name

DT_INST_REG_ADDR(inst)

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

Parameters

• inst – instance number

Returns

instance’s register block address

DT_INST_REG_SIZE(inst)

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

Parameters

• inst – instance number

Returns

instance’s register block size

DT_INST_IRQ_BY_IDX(inst, idx, cell)

Get a DT_DRV_COMPAT interrupt specifier value at an index.

Parameters

• inst – instance number

• idx – logical index into the interrupt specifier array

• cell – cell name specifier

Returns

the named value at the specifier given by the index

DT_INST_IRQ_BY_NAME(inst, name, cell)

Get a DT_DRV_COMPAT interrupt specifier value by name.

Parameters

• inst – instance number

• name – lowercase-and-underscores interrupt specifier name

• cell – cell name specifier

Returns

the named value at the specifier given by the index

DT_INST_IRQ(inst, cell)

Get a DT_DRV_COMPAT interrupt specifier’s value.

Parameters

• inst – instance number

• cell – cell name specifier

Returns

the named value at that index

DT_INST_IRQN(inst)

Get a DT_DRV_COMPAT’s (only) irq number.

Parameters

• inst – instance number

Returns

the interrupt number for the node’s only interrupt

DT_INST_BUS(inst)

Get a DT_DRV_COMPAT’s bus node identifier.

Parameters

• inst – instance number

Returns

node identifier for the instance’s bus node

DT_INST_BUS_LABEL(inst)

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

Parameters

• inst – instance number

Returns

the label property of the instance’s bus controller

DT_INST_ON_BUS(inst, bus)

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

Parameters

• inst – instance number

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

Returns

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

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

Parameters

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

Returns

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

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_FOREACH_STATUS_OKAY_VARGS(fn, ...)

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

See also

DT_INST_FOREACH_STATUS_OKAY

Parameters

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

• ... – variable number of arguments to pass to fn

DT_INST_FOREACH_PROP_ELEM(inst, prop, fn)

Invokes “fn” for each element of property “prop” for a DT_DRV_COMPAT instance.

Equivalent to DT_FOREACH_PROP_ELEM(DT_DRV_INST(inst), prop, fn).

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• fn – macro to invoke

DT_INST_FOREACH_PROP_ELEM_VARGS(inst, prop, fn, ...)

Invokes “fn” for each element of property “prop” for a DT_DRV_COMPAT instance with multiple arguments.

Equivalent to DT_FOREACH_PROP_ELEM_VARGS(DT_DRV_INST(inst), prop, fn, VA_ARGS)

See also

DT_INST_FOREACH_PROP_ELEM

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

• fn – macro to invoke

• ... – variable number of arguments to pass to fn

DT_INST_NODE_HAS_PROP(inst, prop)

Does a DT_DRV_COMPAT instance have a property?

Parameters

• inst – instance number

• prop – lowercase-and-underscores property name

Returns

1 if the instance has the property, 0 otherwise.

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?

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

Returns

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

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?

Parameters

• inst – instance number

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

• cell – named cell value whose existence to check

Returns

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

DT_INST_IRQ_HAS_IDX(inst, idx)

is index valid for interrupt property on a DT_DRV_COMPAT instance?

Parameters

• inst – instance number

• idx – logical index into the interrupt specifier array

Returns

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

DT_INST_IRQ_HAS_CELL_AT_IDX(inst, idx, cell)

Does a DT_DRV_COMPAT instance have an interrupt named cell specifier?

Parameters

• inst – instance number

• idx – index to check

• cell – named cell value whose existence to check

Returns

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

DT_INST_IRQ_HAS_CELL(inst, cell)

Does a DT_DRV_COMPAT instance have an interrupt value?

Parameters

• inst – instance number

• cell – named cell value whose existence to check

Returns

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

DT_INST_IRQ_HAS_NAME(inst, name)

Does a DT_DRV_COMPAT instance have an interrupt value?

Parameters

• inst – instance number

• name – lowercase-and-underscores interrupt specifier name

Returns

1 if “name” is a valid named specifier

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_CTLR_BY_IDX(node_id, idx)

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

Example devicetree fragment:

clk1: clock-controller@... { ... };

clk2: clock-controller@... { ... };

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

Example usage:

DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 0)) // DT_NODELABEL(clk1)
DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 1)) // DT_NODELABEL(clk2)

See also

DT_PHANDLE_BY_IDX()

Parameters

• node_id – node identifier

• idx – logical index into “clocks”

Returns

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

DT_CLOCKS_CTLR(node_id)

Equivalent to DT_CLOCKS_CTLR_BY_IDX(node_id, 0)

See also

DT_CLOCKS_CTLR_BY_IDX()

Parameters

• node_id – node identifier

Returns

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

DT_CLOCKS_CTLR_BY_NAME(node_id, name)

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

Example devicetree fragment:

clk1: clock-controller@... { ... };

clk2: clock-controller@... { ... };

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

Example usage:

DT_CLOCKS_CTLR_BY_NAME(DT_NODELABEL(n), beta) // DT_NODELABEL(clk2)

See also

DT_PHANDLE_BY_NAME()

Parameters

• node_id – node identifier

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

Returns

the node identifier for the clock controller referenced by name

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"

See also

DT_PROP_BY_PHANDLE_IDX()

Parameters

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

• idx – logical index into clocks property

Returns

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

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"

See also

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

Returns

the label property of the node referenced at the named element

DT_CLOCKS_LABEL(node_id)

Equivalent to DT_CLOCKS_LABEL_BY_IDX(node_id, 0)

See also

DT_CLOCKS_LABEL_BY_IDX()

Parameters

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

Returns

the label property of the node referenced at index 0

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

See also

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

Returns

the cell value at index “idx”

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

See also

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

Returns

the cell value in the specifier at the named element

DT_CLOCKS_CELL(node_id, cell)

Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)

See also

DT_CLOCKS_CELL_BY_IDX()

Parameters

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

• cell – lowercase-and-underscores cell name

Returns

the cell value at index 0

DT_INST_CLOCKS_CTLR_BY_IDX(inst, idx)

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

See also

DT_CLOCKS_CTLR_BY_IDX()

Parameters

• inst – instance number

• idx – logical index into “clocks”

Returns

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

DT_INST_CLOCKS_CTLR(inst)

Equivalent to DT_INST_CLOCKS_CTLR_BY_IDX(inst, 0)

See also

DT_CLOCKS_CTLR()

Parameters

• inst – instance number

Returns

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

DT_INST_CLOCKS_CTLR_BY_NAME(inst, name)

Get the node identifier for the controller phandle from a clocks phandle-array property by name.

See also

DT_CLOCKS_CTLR_BY_NAME()

Parameters

• inst – instance number

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

Returns

the node identifier for the clock controller referenced by the named element

DT_INST_CLOCKS_LABEL_BY_IDX(inst, idx)

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

See also

DT_CLOCKS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into clocks property

Returns

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

DT_INST_CLOCKS_LABEL_BY_NAME(inst, name)

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

See also

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

Returns

the label property of the node referenced at the named element

DT_INST_CLOCKS_LABEL(inst)

Equivalent to DT_INST_CLOCKS_LABEL_BY_IDX(inst, 0)

See also

DT_CLOCKS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the label property of the node referenced at index 0

DT_INST_CLOCKS_CELL_BY_IDX(inst, idx, cell)

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

See also

DT_CLOCKS_CELL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into clocks property

• cell – lowercase-and-underscores cell name

Returns

the cell value at index “idx”

DT_INST_CLOCKS_CELL_BY_NAME(inst, name, cell)

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

See also

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

Returns

the cell value in the specifier at the named element

DT_INST_CLOCKS_CELL(inst, cell)

Equivalent to DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)

Parameters

• inst – DT_DRV_COMPAT instance number

• cell – lowercase-and-underscores cell name

Returns

the value of the cell inside the specifier at index 0

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"

Parameters

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

• idx – logical index into dmas property

Returns

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

DT_INST_DMAS_LABEL_BY_IDX(inst, idx)

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

See also

DT_DMAS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into dmas property

Returns

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

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"

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

Returns

the label property of the node referenced at the named element

DT_DMAS_CTLR_BY_IDX(node_id, idx)

Get the node identifier for the DMA controller from a dmas property at an index.

Example devicetree fragment:

dma1: dma@... { ... };

dma2: dma@... { ... };

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

Example usage:

DT_DMAS_CTLR_BY_IDX(DT_NODELABEL(n), 0) // DT_NODELABEL(dma1)
DT_DMAS_CTLR_BY_IDX(DT_NODELABEL(n), 1) // DT_NODELABEL(dma2)

See also

DT_PROP_BY_PHANDLE_IDX()

Parameters

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

• idx – logical index into dmas property

Returns

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

DT_DMAS_CTLR_BY_NAME(node_id, name)

Get the node identifier for the DMA controller from a dmas property by name.

Example devicetree fragment:

dma1: dma@... { ... };

dma2: dma@... { ... };

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

Example usage:

DT_DMAS_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(dma1)
DT_DMAS_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(dma2)

See also

DT_PHANDLE_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

Returns

the node identifier for the DMA controller in the named element

DT_DMAS_CTLR(node_id)

Equivalent to DT_DMAS_CTLR_BY_IDX(node_id, 0)

See also

DT_DMAS_CTLR_BY_IDX()

Parameters

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

Returns

the node identifier for the DMA controller at index 0 in the node’s “dmas” property

DT_INST_DMAS_LABEL_BY_NAME(inst, name)

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

See also

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

Returns

the label property of the node referenced at the named element

DT_INST_DMAS_CTLR_BY_IDX(inst, idx)

Get the node identifier for the DMA controller from a DT_DRV_COMPAT instance’s dmas property at an index.

See also

DT_DMAS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into dmas property

Returns

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

DT_INST_DMAS_CTLR_BY_NAME(inst, name)

Get the node identifier for the DMA controller from a DT_DRV_COMPAT instance’s dmas property by name.

See also

DT_DMAS_CTLR_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

Returns

the node identifier for the DMA controller in the named element

DT_INST_DMAS_CTLR(inst)

Equivalent to DT_INST_DMAS_CTLR_BY_IDX(inst, 0)

See also

DT_DMAS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the node identifier for the DMA controller at index 0 in the instance’s “dmas” 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

See also

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

Returns

the cell value at index “idx”

DT_INST_DMAS_CELL_BY_IDX(inst, idx, cell)

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

See also

DT_DMAS_CELL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into dmas property

• cell – lowercase-and-underscores cell name

Returns

the cell value at index “idx”

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

See also

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

Returns

the cell value in the specifier at the named element

DT_INST_DMAS_CELL_BY_NAME(inst, name, cell)

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

See also

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

Returns

the cell value in the specifier at the named element

DT_DMAS_HAS_IDX(node_id, idx)

Is index “idx” valid for a dmas property?

Parameters

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

• idx – logical index into dmas property

Returns

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

DT_INST_DMAS_HAS_IDX(inst, idx)

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

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into dmas property

Returns

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

DT_DMAS_HAS_NAME(node_id, name)

Does a dmas property have a 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

Returns

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

DT_INST_DMAS_HAS_NAME(inst, name)

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

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

Returns

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

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

Parameters

• label – lowercase-and-underscores label property value

Returns

a node identifier for the partition with that label property

DT_HAS_FIXED_PARTITION_LABEL(label)

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

Parameters

• label – lowercase-and-underscores label property value

Returns

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

DT_FIXED_PARTITION_ID(node_id)

Get a numeric identifier for a fixed partition.

Parameters

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

Returns

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

DT_MTD_FROM_FIXED_PARTITION(node_id)

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

Parameters

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

Returns

the node identifier of the memory technology device that contains the fixed-partitions 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)

See also

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”

Returns

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

DT_GPIO_CTLR(node_id, gpio_pha)

Equivalent to DT_GPIO_CTLR_BY_IDX(node_id, gpio_pha, 0)

See also

DT_GPIO_CTLR_BY_IDX()

Parameters

• node_id – node identifier

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

Returns

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

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"

See also

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”

Returns

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

DT_GPIO_LABEL(node_id, gpio_pha)

Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)

See also

DT_GPIO_LABEL_BY_IDX()

Parameters

• node_id – node identifier

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

Returns

the label property of the node referenced at index 0

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

See also

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”

Returns

the pin cell value at index “idx”

DT_GPIO_PIN(node_id, gpio_pha)

Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)

See also

DT_GPIO_PIN_BY_IDX()

Parameters

• node_id – node identifier

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

Returns

the pin cell value at index 0

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

See also

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”

Returns

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

DT_GPIO_FLAGS(node_id, gpio_pha)

Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)

See also

DT_GPIO_FLAGS_BY_IDX()

Parameters

• node_id – node identifier

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

Returns

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

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.

Parameters

• inst – DT_DRV_COMPAT instance number

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

• idx – logical index into “gpio_pha”

Returns

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

DT_INST_GPIO_LABEL(inst, gpio_pha)

Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)

Parameters

• inst – DT_DRV_COMPAT instance number

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

Returns

the label property of the node referenced at index 0

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.

See also

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”

Returns

the pin cell value at index “idx”

DT_INST_GPIO_PIN(inst, gpio_pha)

Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)

See also

DT_INST_GPIO_PIN_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

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

Returns

the pin cell value at index 0

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.

See also

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”

Returns

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

DT_INST_GPIO_FLAGS(inst, gpio_pha)

Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)

See also

DT_INST_GPIO_FLAGS_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

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

Returns

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

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"

See also

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

Returns

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

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"

See also

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

Returns

the label property of the node referenced at the named element

DT_IO_CHANNELS_LABEL(node_id)

Equivalent to DT_IO_CHANNELS_LABEL_BY_IDX(node_id, 0)

See also

DT_IO_CHANNELS_LABEL_BY_IDX()

Parameters

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

Returns

the label property of the node referenced at index 0

DT_IO_CHANNELS_CTLR_BY_IDX(node_id, idx)

Get the node identifier for the node referenced by an io-channels property at an index.

Example devicetree fragment:

adc1: adc@... { ... };

adc2: adc@... { ... };

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

Example usage:

DT_IO_CHANNELS_CTLR_BY_IDX(DT_NODELABEL(n), 0) // DT_NODELABEL(adc1)
DT_IO_CHANNELS_CTLR_BY_IDX(DT_NODELABEL(n), 1) // DT_NODELABEL(adc2)

See also

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

Returns

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

DT_IO_CHANNELS_CTLR_BY_NAME(node_id, name)

Get the node identifier for the node referenced by an io-channels property by name.

Example devicetree fragment:

adc1: adc@... { ... };

adc2: adc@... { ... };

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

Example usage:

DT_IO_CHANNELS_CTLR_BY_NAME(DT_NODELABEL(n), sensor) // DT_NODELABEL(adc1) DT_IO_CHANNELS_CTLR_BY_NAME(DT_NODELABEL(n), bandgap) // DT_NODELABEL(adc2)

See also

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

Returns

the node identifier for the node referenced at the named element

DT_IO_CHANNELS_CTLR(node_id)

Equivalent to DT_IO_CHANNELS_CTLR_BY_IDX(node_id, 0)

See also

DT_IO_CHANNELS_CTLR_BY_IDX()

Parameters

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

Returns

the node identifier for the node referenced at index 0 in the node’s “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.

See also

DT_IO_CHANNELS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into io-channels property

Returns

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

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.

See also

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

Returns

the label property of the node referenced at the named element

DT_INST_IO_CHANNELS_LABEL(inst)

Equivalent to DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, 0)

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the label property of the node referenced at index 0

DT_INST_IO_CHANNELS_CTLR_BY_IDX(inst, idx)

Get the node identifier from a DT_DRV_COMPAT instance’s io-channels property at an index.

See also

DT_IO_CHANNELS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into io-channels property

Returns

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

DT_INST_IO_CHANNELS_CTLR_BY_NAME(inst, name)

Get the node identifier from a DT_DRV_COMPAT instance’s io-channels property by name.

See also

DT_IO_CHANNELS_CTLR_BY_NAME()

Parameters

• inst – DT_DRV_COMPAT instance number

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

Returns

the node identifier for the node referenced at the named element

DT_INST_IO_CHANNELS_CTLR(inst)

Equivalent to DT_INST_IO_CHANNELS_CTLR_BY_IDX(inst, 0)

See also

DT_IO_CHANNELS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the node identifier for the node referenced at index 0 in the node’s “io-channels” property

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

See also

DT_PHA_BY_IDX()

Parameters

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

• idx – logical index into io-channels property

Returns

the input cell in the specifier at index “idx”

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

See also

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

Returns

the input cell in the specifier at the named element

DT_IO_CHANNELS_INPUT(node_id)

Equivalent to DT_IO_CHANNELS_INPUT_BY_IDX(node_id, 0)

See also

DT_IO_CHANNELS_INPUT_BY_IDX()

Parameters

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

Returns

the input cell in the specifier at index 0

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.

See also

DT_IO_CHANNELS_INPUT_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into io-channels property

Returns

the input cell in the specifier at index “idx”

DT_INST_IO_CHANNELS_INPUT_BY_NAME(inst, name)

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

See also

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

Returns

the input cell in the specifier at the named element

DT_INST_IO_CHANNELS_INPUT(inst)

Equivalent to DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, 0)

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the input cell in the specifier at index 0

Pinctrl (pin control)

These are used to access pin control properties by name or index.

Devicetree nodes may have properties which specify pin control (sometimes known as pin mux) settings. These are expressed using pinctrl-<index> properties within the node, where the <index> values are contiguous integers starting from 0. These may also be named using the pinctrl-names property.

Here is an example:

node {
    ...
    pinctrl-0 = <&foo &bar ...>;
    pinctrl-1 = <&baz ...>;
    pinctrl-names = "default", "sleep";
};

Above, pinctrl-0 has name "default", and pinctrl-1 has name "sleep". The pinctrl-<index> property values contain phandles. The &foo, &bar, etc. phandles within the properties point to nodes whose contents vary by platform, and which describe a pin configuration for the node.

group devicetree-pinctrl

Defines

DT_PINCTRL_BY_IDX(node_id, pc_idx, idx)

Get a node identifier for a phandle in a pinctrl property by index.

Example devicetree fragment:

n: node {
        pinctrl-0 = <&foo &bar>;
        pinctrl-1 = <&baz &blub>;
}

Example usage:

DT_PINCTRL_BY_IDX(DT_NODELABEL(n), 0, 1) // DT_NODELABEL(bar)
DT_PINCTRL_BY_IDX(DT_NODELABEL(n), 1, 0) // DT_NODELABEL(baz)

Parameters

• node_id – node with a pinctrl-‘pc_idx’ property

• pc_idx – index of the pinctrl property itself

• idx – index into the value of the pinctrl property

Returns

node identifier for the phandle at index ‘idx’ in ‘pinctrl-‘pc_idx’’

DT_PINCTRL_0(node_id, idx)

Get a node identifier from a pinctrl-0 property.

This is equivalent to:

DT_PINCTRL_BY_IDX(node_id, 0, idx)

It is provided for convenience since pinctrl-0 is commonly used.

Parameters

• node_id – node with a pinctrl-0 property

• idx – index into the pinctrl-0 property

Returns

node identifier for the phandle at index idx in the pinctrl-0 property of that node

DT_PINCTRL_BY_NAME(node_id, name, idx)

Get a node identifier for a phandle inside a pinctrl node by name.

Example devicetree fragment:

n: node {
        pinctrl-0 = <&foo &bar>;
        pinctrl-1 = <&baz &blub>;
        pinctrl-names = "default", "sleep";
};

Example usage:

DT_PINCTRL_BY_NAME(DT_NODELABEL(n), default, 1) // DT_NODELABEL(bar)
DT_PINCTRL_BY_NAME(DT_NODELABEL(n), sleep, 0) // DT_NODELABEL(baz)

Parameters

• node_id – node with a named pinctrl property

• name – lowercase-and-underscores pinctrl property name

• idx – index into the value of the named pinctrl property

Returns

node identifier for the phandle at that index in the pinctrl property

DT_PINCTRL_NAME_TO_IDX(node_id, name)

Convert a pinctrl name to its corresponding index.

Example devicetree fragment:

n: node {
        pinctrl-0 = <&foo &bar>;
        pinctrl-1 = <&baz &blub>;
        pinctrl-names = "default", "sleep";
};

Example usage:

DT_PINCTRL_NAME_TO_IDX(DT_NODELABEL(n), default) // 0
DT_PINCTRL_NAME_TO_IDX(DT_NODELABEL(n), sleep)   // 1

Parameters

• node_id – node identifier with a named pinctrl property

• name – lowercase-and-underscores name name of the pinctrl whose index to get

Returns

integer literal for the index of the pinctrl property with that name

DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx)

Convert a pinctrl property index to its name as a token.

This allows you to get a pinctrl property’s name, and “remove the

quotes” from it.

DT_PINCTRL_IDX_TO_NAME_TOKEN() can only be used if the node has a pinctrl-‘pc_idx’ property and a pinctrl-names property element for that index. It is an error to use it in other circumstances.

Example devicetree fragment:

n: node {
        pinctrl-0 = <...>;
        pinctrl-1 = <...>;
        pinctrl-names = "default", "f.o.o2";
};

Example usage:

DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 0) // default
DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 1) // f_o_o2

The same caveats and restrictions that apply to DT_STRING_TOKEN()’s return value also apply here.

Parameters

• node_id – node identifier

• pc_idx – index of a pinctrl property in that node

Returns

name of the pinctrl property, as a token, without any quotes and with non-alphanumeric characters converted to underscores

DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(node_id, pc_idx)

Like DT_PINCTRL_IDX_TO_NAME_TOKEN(), but with an uppercased result.

This does the a similar conversion as DT_PINCTRL_IDX_TO_NAME_TOKEN(node_id, pc_idx). The only difference is that alphabetical characters in the result are uppercased.

Example devicetree fragment:

n: node {
        pinctrl-0 = <...>;
        pinctrl-1 = <...>;
        pinctrl-names = "default", "f.o.o2";
};

Example usage:

DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 0) // DEFAULT
DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_NODELABEL(n), 1) // F_O_O2

The same caveats and restrictions that apply to DT_STRING_UPPER_TOKEN()’s return value also apply here.

DT_NUM_PINCTRLS_BY_IDX(node_id, pc_idx)

Get the number of phandles in a pinctrl property.

Example devicetree fragment:

n1: node-1 {
        pinctrl-0 = <&foo &bar>;
};

n2: node-2 {
        pinctrl-0 = <&baz>;
};

Example usage:

DT_NUM_PINCTRLS_BY_IDX(DT_NODELABEL(n1), 0) // 2
DT_NUM_PINCTRLS_BY_IDX(DT_NODELABEL(n2), 0) // 1

Parameters

• node_id – node identifier with a pinctrl property

• pc_idx – index of the pinctrl property itself

Returns

number of phandles in the property with that index

DT_NUM_PINCTRLS_BY_NAME(node_id, name)

Like DT_NUM_PINCTRLS_BY_IDX(), but by name instead.

Example devicetree fragment:

n: node {
        pinctrl-0 = <&foo &bar>;
        pinctrl-1 = <&baz>
        pinctrl-names = "default", "sleep";
};

Example usage:

DT_NUM_PINCTRLS_BY_NAME(DT_NODELABEL(n), default) // 2
DT_NUM_PINCTRLS_BY_NAME(DT_NODELABEL(n), sleep)   // 1

Parameters

• node_id – node identifier with a pinctrl property

• name – lowercase-and-underscores name name of the pinctrl property

Returns

number of phandles in the property with that name

DT_NUM_PINCTRL_STATES(node_id)

Get the number of pinctrl properties in a node.

This expands to 0 if there are no pinctrl-i properties. Otherwise, it expands to the number of such properties.

Example devicetree fragment:

n1: node-1 {
        pinctrl-0 = <...>;
        pinctrl-1 = <...>;
};

n2: node-2 {
};

Example usage:

DT_NUM_PINCTRL_STATES(DT_NODELABEL(n1)) // 2
DT_NUM_PINCTRL_STATES(DT_NODELABEL(n2)) // 0

Parameters

• node_id – node identifier; may or may not have any pinctrl properties

Returns

number of pinctrl properties in the node

DT_PINCTRL_HAS_IDX(node_id, pc_idx)

Test if a node has a pinctrl property with an index.

This expands to 1 if the pinctrl-‘idx’ property exists. Otherwise, it expands to 0.

Example devicetree fragment:

n1: node-1 {
        pinctrl-0 = <...>;
        pinctrl-1 = <...>;
};

n2: node-2 {
};

Example usage:

DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 0) // 1
DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 1) // 1
DT_PINCTRL_HAS_IDX(DT_NODELABEL(n1), 2) // 0
DT_PINCTRL_HAS_IDX(DT_NODELABEL(n2), 0) // 0

Parameters

• node_id – node identifier; may or may not have any pinctrl properties

• pc_idx – index of a pinctrl property whose existence to check

Returns

1 if the property exists, 0 otherwise

DT_PINCTRL_HAS_NAME(node_id, name)

Test if a node has a pinctrl property with a name.

This expands to 1 if the named pinctrl property exists. Otherwise, it expands to 0.

Example devicetree fragment:

n1: node-1 {
        pinctrl-0 = <...>;
        pinctrl-names = "default";
};

n2: node-2 {
};

Example usage:

DT_PINCTRL_HAS_NAME(DT_NODELABEL(n1), default) // 1
DT_PINCTRL_HAS_NAME(DT_NODELABEL(n1), sleep)   // 0
DT_PINCTRL_HAS_NAME(DT_NODELABEL(n2), default) // 0

Parameters

• node_id – node identifier; may or may not have any pinctrl properties

• name – lowercase-and-underscores pinctrl property name to check

Returns

1 if the property exists, 0 otherwise

DT_INST_PINCTRL_BY_IDX(inst, pc_idx, idx)

Get a node identifier for a phandle in a pinctrl property by index for a DT_DRV_COMPAT instance.

This is equivalent to DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), pc_idx, idx).

Parameters

• inst – instance number

• pc_idx – index of the pinctrl property itself

• idx – index into the value of the pinctrl property

Returns

node identifier for the phandle at index ‘idx’ in ‘pinctrl-‘pc_idx’’

DT_INST_PINCTRL_0(inst, idx)

Get a node identifier from a pinctrl-0 property for a DT_DRV_COMPAT instance.

This is equivalent to:

DT_PINCTRL_BY_IDX(DT_DRV_INST(inst), 0, idx)

It is provided for convenience since pinctrl-0 is commonly used.

Parameters

• inst – instance number

• idx – index into the pinctrl-0 property

Returns

node identifier for the phandle at index idx in the pinctrl-0 property of that instance

DT_INST_PINCTRL_BY_NAME(inst, name, idx)

Get a node identifier for a phandle inside a pinctrl node for a DT_DRV_COMPAT instance.

This is equivalent to DT_PINCTRL_BY_NAME(DT_DRV_INST(inst), name, idx).

Parameters

• inst – instance number

• name – lowercase-and-underscores pinctrl property name

• idx – index into the value of the named pinctrl property

Returns

node identifier for the phandle at that index in the pinctrl property

DT_INST_PINCTRL_NAME_TO_IDX(inst, name)

Convert a pinctrl name to its corresponding index for a DT_DRV_COMPAT instance.

This is equivalent to DT_PINCTRL_NAME_TO_IDX(DT_DRV_INST(inst), name).

Parameters

• inst – instance number

• name – lowercase-and-underscores name of the pinctrl whose index to get

Returns

integer literal for the index of the pinctrl property with that name

DT_INST_PINCTRL_IDX_TO_NAME_TOKEN(inst, pc_idx)

Convert a pinctrl index to its name as an uppercased token.

This is equivalent to DT_PINCTRL_IDX_TO_NAME_TOKEN(DT_DRV_INST(inst), pc_idx).

Parameters

• inst – instance number

• pc_idx – index of the pinctrl property itself

Returns

name of the pin control property as a token

DT_INST_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(inst, pc_idx)

Convert a pinctrl index to its name as an uppercased token.

This is equivalent to DT_PINCTRL_IDX_TO_NAME_UPPER_TOKEN(DT_DRV_INST(inst), idx).

Parameters

• inst – instance number

• pc_idx – index of the pinctrl property itself

Returns

name of the pin control property as an uppercase token

DT_INST_NUM_PINCTRLS_BY_IDX(inst, pc_idx)

Get the number of phandles in a pinctrl property for a DT_DRV_COMPAT instance.

This is equivalent to DT_NUM_PINCTRLS_BY_IDX(DT_DRV_INST(inst), pc_idx).

Parameters

• inst – instance number

• pc_idx – index of the pinctrl property itself

Returns

number of phandles in the property with that index

DT_INST_NUM_PINCTRLS_BY_NAME(inst, name)

Like DT_INST_NUM_PINCTRLS_BY_IDX(), but by name instead.

This is equivalent to DT_NUM_PINCTRLS_BY_NAME(DT_DRV_INST(inst), name).

Parameters

• inst – instance number

• name – lowercase-and-underscores name of the pinctrl property

Returns

number of phandles in the property with that name

DT_INST_NUM_PINCTRL_STATES(inst)

Get the number of pinctrl properties in a DT_DRV_COMPAT instance.

This is equivalent to DT_NUM_PINCTRL_STATES(DT_DRV_INST(inst)).

Parameters

• inst – instance number

Returns

number of pinctrl properties in the instance

DT_INST_PINCTRL_HAS_IDX(inst, pc_idx)

Test if a DT_DRV_COMPAT instance has a pinctrl property with an index.

This is equivalent to DT_PINCTRL_HAS_IDX(DT_DRV_INST(inst), pc_idx).

Parameters

• inst – instance number

• pc_idx – index of a pinctrl property whose existence to check

Returns

1 if the property exists, 0 otherwise

DT_INST_PINCTRL_HAS_NAME(inst, name)

Test if a DT_DRV_COMPAT instance has a pinctrl property with a name.

This is equivalent to DT_PINCTRL_HAS_NAME(DT_DRV_INST(inst), name).

Parameters

• inst – instance number

• name – lowercase-and-underscores pinctrl property name to check

Returns

1 if the property exists, 0 otherwise

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"

See also

DT_PROP_BY_PHANDLE_IDX()

Parameters

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

• idx – logical index into pwms property

Returns

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

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"

See also

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

Returns

the label property of the node referenced at the named element

DT_PWMS_LABEL(node_id)

Equivalent to DT_PWMS_LABEL_BY_IDX(node_id, 0)

See also

DT_PWMS_LABEL_BY_IDX()

Parameters

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

Returns

the label property of the node referenced at index 0

DT_PWMS_CTLR_BY_IDX(node_id, idx)

Get the node identifier for the PWM controller from a pwms property at an index.

Example devicetree fragment:

pwm1: pwm-controller@... { ... };

pwm2: pwm-controller@... { ... };

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

Example usage:

DT_PWMS_CTLR_BY_IDX(DT_NODELABEL(n), 0) // DT_NODELABEL(pwm1)
DT_PWMS_CTLR_BY_IDX(DT_NODELABEL(n), 1) // DT_NODELABEL(pwm2)

See also

DT_PROP_BY_PHANDLE_IDX()

Parameters

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

• idx – logical index into pwms property

Returns

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

DT_PWMS_CTLR_BY_NAME(node_id, name)

Get the node identifier for the PWM controller from a pwms property by name.

Example devicetree fragment:

pwm1: pwm-controller@... { ... };

pwm2: pwm-controller… { … };

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

Example usage:

DT_PWMS_CTLR_BY_NAME(DT_NODELABEL(n), alpha) // DT_NODELABEL(pwm1)
DT_PWMS_CTLR_BY_NAME(DT_NODELABEL(n), beta)  // DT_NODELABEL(pwm2)

See also

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

Returns

the node identifier for the PWM controller in the named element

DT_PWMS_CTLR(node_id)

Equivalent to DT_PWMS_CTLR_BY_IDX(node_id, 0)

See also

DT_PWMS_CTLR_BY_IDX()

Parameters

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

Returns

the node identifier for the PWM controller at index 0 in the node’s “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

See also

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

Returns

the cell value at index “idx”

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

See also

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

Returns

the cell value in the specifier at the named element

DT_PWMS_CELL(node_id, cell)

Equivalent to DT_PWMS_CELL_BY_IDX(node_id, 0, cell)

See also

DT_PWMS_CELL_BY_IDX()

Parameters

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

• cell – lowercase-and-underscores cell name

Returns

the cell value at index 0

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

See also

DT_PWMS_CELL_BY_IDX()

Parameters

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

• idx – logical index into pwms property

Returns

the channel cell value at index “idx”

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

See also

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

Returns

the channel cell value in the specifier at the named element

DT_PWMS_CHANNEL(node_id)

Equivalent to DT_PWMS_CHANNEL_BY_IDX(node_id, 0)

See also

DT_PWMS_CHANNEL_BY_IDX()

Parameters

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

Returns

the channel cell value at index 0

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

See also

DT_PWMS_CELL_BY_IDX()

Parameters

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

• idx – logical index into pwms property

Returns

the period cell value at index “idx”

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

See also

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

Returns

the period cell value in the specifier at the named element

DT_PWMS_PERIOD(node_id)

Equivalent to DT_PWMS_PERIOD_BY_IDX(node_id, 0)

See also

DT_PWMS_PERIOD_BY_IDX()

Parameters

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

Returns

the period cell value at index 0

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

See also

DT_PWMS_CELL_BY_IDX()

Parameters

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

• idx – logical index into pwms property

Returns

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

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.

See also

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

Returns

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

DT_PWMS_FLAGS(node_id)

Equivalent to DT_PWMS_FLAGS_BY_IDX(node_id, 0)

See also

DT_PWMS_FLAGS_BY_IDX()

Parameters

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

Returns

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

DT_INST_PWMS_LABEL_BY_IDX(inst, idx)

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

See also

DT_PWMS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

Returns

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

DT_INST_PWMS_LABEL_BY_NAME(inst, name)

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

See also

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

Returns

the label property of the node referenced at the named element

DT_INST_PWMS_LABEL(inst)

Equivalent to DT_INST_PWMS_LABEL_BY_IDX(inst, 0)

See also

DT_PWMS_LABEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the label property of the node referenced at index 0

DT_INST_PWMS_CTLR_BY_IDX(inst, idx)

Get the node identifier for the PWM controller from a DT_DRV_COMPAT instance’s pwms property at an index.

See also

DT_PWMS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

Returns

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

DT_INST_PWMS_CTLR_BY_NAME(inst, name)

Get the node identifier for the PWM controller from a DT_DRV_COMPAT instance’s pwms property by name.

See also

DT_PWMS_CTLR_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

Returns

the node identifier for the PWM controller in the named element

DT_INST_PWMS_CTLR(inst)

Equivalent to DT_INST_PWMS_CTLR_BY_IDX(inst, 0)

See also

DT_PWMS_CTLR_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the node identifier for the PWM controller at index 0 in the instance’s “pwms” property

DT_INST_PWMS_CELL_BY_IDX(inst, idx, cell)

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

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

• cell – lowercase-and-underscores cell name

Returns

the cell value at index “idx”

DT_INST_PWMS_CELL_BY_NAME(inst, name, cell)

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

See also

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

Returns

the cell value in the specifier at the named element

DT_INST_PWMS_CELL(inst, cell)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, 0, cell)

Parameters

• inst – DT_DRV_COMPAT instance number

• cell – lowercase-and-underscores cell name

Returns

the cell value at index 0

DT_INST_PWMS_CHANNEL_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, channel)

See also

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

Returns

the channel cell value at index “idx”

DT_INST_PWMS_CHANNEL_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, channel)

See also

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

Returns

the channel cell value in the specifier at the named element

DT_INST_PWMS_CHANNEL(inst)

Equivalent to DT_INST_PWMS_CHANNEL_BY_IDX(inst, 0)

See also

DT_INST_PWMS_CHANNEL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the channel cell value at index 0

DT_INST_PWMS_PERIOD_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, period)

See also

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

Returns

the period cell value at index “idx”

DT_INST_PWMS_PERIOD_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, period)

See also

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

Returns

the period cell value in the specifier at the named element

DT_INST_PWMS_PERIOD(inst)

Equivalent to DT_INST_PWMS_PERIOD_BY_IDX(inst, 0)

See also

DT_INST_PWMS_PERIOD_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

the period cell value at index 0

DT_INST_PWMS_FLAGS_BY_IDX(inst, idx)

Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, flags)

See also

DT_INST_PWMS_CELL_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

• idx – logical index into pwms property

Returns

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

DT_INST_PWMS_FLAGS_BY_NAME(inst, name)

Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, flags)

See also

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

Returns

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

DT_INST_PWMS_FLAGS(inst)

Equivalent to DT_INST_PWMS_FLAGS_BY_IDX(inst, 0)

See also

DT_INST_PWMS_FLAGS_BY_IDX()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

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

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

Parameters

• spi – a SPI bus controller node identifier

Returns

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

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

Parameters

• spi – a SPI bus controller node identifier

Returns

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

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

Parameters

• spi_dev – a SPI device node identifier

Returns

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

DT_SPI_DEV_CS_GPIOS_DT_SPEC_GET(spi_dev)

Get a SPI device’s chip select devicetree specification.

Example devicetree fragment:

gpio1: gpio@... { ... };

gpio2: gpio@... { ... };

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_DT_SPEC_GET(DT_NODELABEL(a)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
DT_SPI_DEV_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(b)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }

Parameters

• spi_dev – a SPI device node identifier

Returns

gpio_dt_spec struct corresponding with spi_dev’s chip select

DT_SPI_DEV_CS_GPIOS_CTLR(spi_dev)

Get a SPI device’s chip select GPIO controller’s node identifier.

Example devicetree fragment:

gpio1: gpio@... { ... };

gpio2: gpio@... { ... };

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_CTLR(DT_NODELABEL(a)) // DT_NODELABEL(gpio1)
DT_SPI_DEV_CS_GPIOS_CTLR(DT_NODELABEL(b)) // DT_NODELABEL(gpio2)

Parameters

• spi_dev – a SPI device node identifier

Returns

node identifier for spi_dev’s chip select GPIO controller

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"

Parameters

• spi_dev – a SPI device node identifier

Returns

label property of spi_dev’s chip select GPIO controller

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

Parameters

• spi_dev – a SPI device node identifier

Returns

pin number of spi_dev’s chip select GPIO

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.

Parameters

• spi_dev – a SPI device node identifier

Returns

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

DT_INST_SPI_DEV_HAS_CS_GPIOS(inst)

Equivalent to DT_SPI_DEV_HAS_CS_GPIOS(DT_DRV_INST(inst)).

See also

DT_SPI_DEV_HAS_CS_GPIOS()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

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

DT_INST_SPI_DEV_CS_GPIOS_CTLR(inst)

Get GPIO controller node identifier for a SPI device instance This is equivalent to DT_SPI_DEV_CS_GPIOS_CTLR(DT_DRV_INST(inst)).

See also

DT_SPI_DEV_CS_GPIOS_CTLR()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

node identifier for instance’s chip select GPIO controller

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

See also

DT_SPI_DEV_CS_GPIOS_LABEL()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

label property of the instance’s chip select GPIO controller

DT_INST_SPI_DEV_CS_GPIOS_PIN(inst)

Equivalent to DT_SPI_DEV_CS_GPIOS_PIN(DT_DRV_INST(inst)).

See also

DT_SPI_DEV_CS_GPIOS_PIN()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

pin number of the instance’s chip select GPIO

DT_INST_SPI_DEV_CS_GPIOS_FLAGS(inst)

DT_SPI_DEV_CS_GPIOS_FLAGS(DT_DRV_INST(inst)).

See also

DT_SPI_DEV_CS_GPIOS_FLAGS()

Parameters

• inst – DT_DRV_COMPAT instance number

Returns

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

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.

Parameters

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

Returns

a node identifier for the chosen node property

DT_HAS_CHOSEN(prop)

Test if the devicetree has a /chosen node.

Parameters

• prop – lowercase-and-underscores devicetree property

Returns

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

There are also conveniences for commonly used zephyr-specific properties of the /chosen node.

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.

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

Sometimes, 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 device. 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 is used directly in the source code to select a device.

Table 8 Zephyr-specific chosen properties

Property	Purpose
zephyr,bt-c2h-uart	Selects the UART used for host communication in the Bluetooth: HCI UART
zephyr,bt-mon-uart	Sets UART device used for the Bluetooth monitor logging
zephyr,bt-uart	Sets UART device used by Bluetooth
zephyr,canbus	Sets the default 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 UART device used by console driver
zephyr,display	Sets the default display controller
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,ot-uart	Used by the OpenThread to specify UART device for Spinel protocol
zephyr,pcie-controller	The node corresponding to the PCIe Controller
zephyr,shell-uart	Sets UART device used by serial shell backend
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