Devicetree API

This is a reference page for the <zephyr/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 – the ones beginning with DT_INST_ – 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.

Related code samples

GPIO with custom Devicetree binding

Use custom Devicetree binding to control a GPIO.

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.

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

Note

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

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_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_NODE_CHILD_IDX(node_id)

Get a devicetree node’s index into its parent’s list of children.

Indexes are zero-based.

It is an error to use this macro with the root node.

Example devicetree fragment:

parent {
        c1: child-1 {};
        c2: child-2 {};
};

Example usage:

DT_NODE_CHILD_IDX(DT_NODELABEL(c1)) // 0
DT_NODE_CHILD_IDX(DT_NODELABEL(c2)) // 1
Parameters:

  • node_id – node identifier

Returns:

the node’s index in its parent node’s list of children

DT_CHILD_NUM(node_id)

Get the number of child nodes of a given node.

Parameters:

  • node_id – a node identifier

Returns:

Number of child nodes

DT_CHILD_NUM_STATUS_OKAY(node_id)

Get the number of child nodes of a given node which child nodes’ status are okay.

Parameters:

  • node_id – a node identifier

Returns:

Number of child nodes which status are okay

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 identifier

  • 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 has type string, and interrupt-controller has type boolean.

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

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

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

Returns:

a representation of the property’s value

DT_PROP_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

  • for type phandle, this expands to 1 (so that a phandle can be treated as a degenerate case of phandles with length 1)

  • for type string, this expands to 1 (so that a string can be treated as a degenerate case of string-array with length 1)

These properties are handled as special cases:

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:

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

Parameters:

  • node_id – node identifier

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

  • idx – index to check

Returns:

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

DT_PROP_HAS_NAME(node_id, prop, name)

Is name name available in a foo-names property?

This property is handled as special case:

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

Example devicetree fragment:

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

Example usage:

DT_PROP_HAS_NAME(DT_NODELABEL(nx), foos, event)    // 1
DT_PROP_HAS_NAME(DT_NODELABEL(nx), foos, failure)  // 0
Parameters:

  • node_id – node identifier

  • prop – a lowercase-and-underscores prop-names type property

  • name – a lowercase-and-underscores name to check

Returns:

An expression which evaluates to 1 if “name” is an available name into the given property, and 0 otherwise.

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

The return value depends on the property’s type:

  • for types array, string-array, uint8-array, and phandles, this expands to the idx-th array element as an integer, string literal, integer, and node identifier respectively

  • for type phandle, idx must be 0 and the expansion is a node identifier (this treats phandle like a phandles of length 1)

  • for type string, idx must be 0 and the expansion is the the entire string (this treats string like string-array of length 1)

These properties are handled as special cases:

For properties of other types, behavior is undefined.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

a representation of the idx-th element of the property

DT_PROP_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_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 otherwise

DT_ENUM_HAS_VALUE(node_id, prop, value)

Does a node enumeration property have a given value?

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • value – lowercase-and-underscores enumeration value

Returns:

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

DT_STRING_TOKEN(node_id, prop)

Get a string property’s value as a token.

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

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string

Example usage:

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

Notice how:

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

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

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

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

Returns:

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

DT_STRING_TOKEN_OR(node_id, prop, default_value)

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

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

Otherwise, this expands to default_value.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

the property’s value as a token, or default_value

DT_STRING_UPPER_TOKEN(node_id, prop)

Like DT_STRING_TOKEN(), but uppercased.

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

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string

Example usage:

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

Notice how:

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

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

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

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

Returns:

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

DT_STRING_UPPER_TOKEN_OR(node_id, prop, default_value)

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

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

Otherwise, this expands to default_value.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

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

DT_STRING_UNQUOTED(node_id, prop)

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

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

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

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

Example devicetree fragment: 

n1: node-1 {
        prop = "12.7";
};
n2: node-2 {
        prop = "0.5";
}
n3: node-3 {
        prop = "A B C";
};
Example bindings fragment: 
properties:
  prop:
    type: string
Example usage: 
DT_STRING_UNQUOTED(DT_NODELABEL(n1), prop) // 12.7
DT_STRING_UNQUOTED(DT_NODELABEL(n2), prop) // 0.5
DT_STRING_UNQUOTED(DT_NODELABEL(n3), prop) // A B C

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

Returns:

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

DT_STRING_UNQUOTED_OR(node_id, prop, default_value)

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

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

Otherwise, this expands to default_value.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

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

DT_STRING_TOKEN_BY_IDX(node_id, prop, idx)

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

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

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string-array

Example usage:

DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n1), prop, 0) // f1
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n1), prop, 1) // F2
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 0) // 123_foo
DT_STRING_TOKEN_BY_IDX(DT_NODELABEL(n2), prop, 1) // 456_FOO

For more information, see DT_STRING_TOKEN.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

the element in prop at index idx as a token

DT_STRING_UPPER_TOKEN_BY_IDX(node_id, prop, idx)

Like DT_STRING_TOKEN_BY_IDX(), but uppercased.

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

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

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

Example devicetree fragment:

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

Example bindings fragment:

properties:
  prop:
    type: string-array

Example usage:

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

For more information, see DT_STRING_UPPER_TOKEN.

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

the element in prop at index idx as an uppercased token

DT_STRING_UNQUOTED_BY_IDX(node_id, prop, idx)

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

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

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

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

Example devicetree fragment: 

n1: node-1 {
        prop = "12.7", "34.1";
};
n2: node-2 {
        prop = "A B", "C D";
}
Example bindings fragment: 
properties:
  prop:
    type: string-array
Example usage: 
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n1), prop, 0) // 12.7
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n1), prop, 1) // 34.1
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n2), prop, 0) // A B
DT_STRING_UNQUOTED_BY_IDX(DT_NODELABEL(n2), prop, 1) // C D

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

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

DT_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@abcd1234 {
        #gpio-cells = <2>;
};

gpio1: gpio@1234abcd {
        #gpio-cells = <2>;
};

led: led_0 {
        gpios = <&gpio0 17 0x1>, <&gpio1 5 0x3>;
};

Bindings fragment for the gpio0 and gpio1 nodes:

gpio-cells:
  - pin
  - flags

Above, gpios has two elements:

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

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

Example usage:

#define LED DT_NODELABEL(led)

DT_PHA_BY_IDX(LED, gpios, 0, pin)   // 17
DT_PHA_BY_IDX(LED, gpios, 1, flags) // 0x3
Parameters:

  • node_id – node identifier

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

  • idx – logical index into pha

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

Returns:

the cell’s value

DT_PHA_BY_IDX_OR(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@abcd1234 {
        foobar = "ADC_1";
};

adc2: adc@1234abcd {
        foobar = "ADC_2";
};

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

Above, “io-channels” has two elements:

  • the element named "SENSOR" has phandle &adc1

  • the element named "BANDGAP" has phandle &adc2

Example usage:

#define NODE DT_NODELABEL(n)

DT_PROP(DT_PHANDLE_BY_NAME(NODE, io_channels, sensor), foobar)  // "ADC_1"
DT_PROP(DT_PHANDLE_BY_NAME(NODE, io_channels, bandgap), foobar) // "ADC_2"

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

Parameters:

  • node_id – node identifier

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

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

Returns:

a node identifier for the node with that phandle

DT_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 = "pcie-controller";
        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 = "pcie-controller";
        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 = "pcie-controller";
                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 = "pcie-controller";
                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 = "pcie-controller";
                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 = "pcie-controller";
                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 = "pcie-controller";
                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_ADDR_U64(node_id)

64-bit version of DT_REG_ADDR()

This macro version adds the appropriate suffix for 64-bit unsigned integer literals. Note that this macro is equivalent to DT_REG_ADDR() in linker/ASM context.

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_ADDR_BY_NAME_U64(node_id, name)

64-bit version of DT_REG_ADDR_BY_NAME()

This macro version adds the appropriate suffix for 64-bit unsigned integer literals. Note that this macro is equivalent to DT_REG_ADDR_BY_NAME() in linker/ASM context.

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_LEVEL(node_id)

Get the interrupt level for the node.

Parameters:

  • node_id – node identifier

Returns:

interrupt level

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@abcd1234 {
        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_IRQ_INTC_BY_IDX(node_id, idx)

Get an interrupt specifier’s interrupt controller by index. 

gpio0: gpio0 {
        interrupt-controller;
        #interrupt-cells = <2>;
};

foo: foo {
        interrupt-parent = <&gpio0>;
        interrupts = <1 1>, <2 2>;
};

bar: bar {
        interrupts-extended = <&gpio0 3 3>, <&pic0 4>;
};

pic0: pic0 {
        interrupt-controller;
        #interrupt-cells = <1>;

        qux: qux {
                interrupts = <5>, <6>;
                interrupt-names = "int1", "int2";
        };
};

Example usage: 

DT_IRQ_INTC_BY_IDX(DT_NODELABEL(foo), 0) // &gpio0
DT_IRQ_INTC_BY_IDX(DT_NODELABEL(foo), 1) // &gpio0
DT_IRQ_INTC_BY_IDX(DT_NODELABEL(bar), 0) // &gpio0
DT_IRQ_INTC_BY_IDX(DT_NODELABEL(bar), 1) // &pic0
DT_IRQ_INTC_BY_IDX(DT_NODELABEL(qux), 0) // &pic0
DT_IRQ_INTC_BY_IDX(DT_NODELABEL(qux), 1) // &pic0

Parameters:

  • node_id – node identifier

  • idx – interrupt specifier’s index

Returns:

node_id of interrupt specifier’s interrupt controller

DT_IRQ_INTC_BY_NAME(node_id, name)

Get an interrupt specifier’s interrupt controller by name. 

gpio0: gpio0 {
        interrupt-controller;
        #interrupt-cells = <2>;
};

foo: foo {
        interrupt-parent = <&gpio0>;
        interrupts = <1 1>, <2 2>;
        interrupt-names = "int1", "int2";
};

bar: bar {
        interrupts-extended = <&gpio0 3 3>, <&pic0 4>;
        interrupt-names = "int1", "int2";
};

pic0: pic0 {
        interrupt-controller;
        #interrupt-cells = <1>;

        qux: qux {
                interrupts = <5>, <6>;
                interrupt-names = "int1", "int2";
        };
};

Example usage: 

DT_IRQ_INTC_BY_NAME(DT_NODELABEL(foo), int1) // &gpio0
DT_IRQ_INTC_BY_NAME(DT_NODELABEL(foo), int2) // &gpio0
DT_IRQ_INTC_BY_NAME(DT_NODELABEL(bar), int1) // &gpio0
DT_IRQ_INTC_BY_NAME(DT_NODELABEL(bar), int2) // &pic0
DT_IRQ_INTC_BY_NAME(DT_NODELABEL(qux), int1) // &pic0
DT_IRQ_INTC_BY_NAME(DT_NODELABEL(qux), int2) // &pic0

Parameters:

  • node_id – node identifier

  • name – interrupt specifier’s name

Returns:

node_id of interrupt specifier’s interrupt controller

DT_IRQ_INTC(node_id)

Get an interrupt specifier’s interrupt controller. 

gpio0: gpio0 {
        interrupt-controller;
        #interrupt-cells = <2>;
};

foo: foo {
        interrupt-parent = <&gpio0>;
        interrupts = <1 1>;
};

bar: bar {
        interrupts-extended = <&gpio0 3 3>;
};

pic0: pic0 {
        interrupt-controller;
        #interrupt-cells = <1>;

        qux: qux {
                interrupts = <5>;
        };
};

Example usage: 

DT_IRQ_INTC(DT_NODELABEL(foo)) // &gpio0
DT_IRQ_INTC(DT_NODELABEL(bar)) // &gpio0
DT_IRQ_INTC(DT_NODELABEL(qux)) // &pic0

See also

DT_IRQ_INTC_BY_IDX()

Note

Equivalent to DT_IRQ_INTC_BY_IDX(node_id, 0)

Parameters:

  • node_id – node identifier

Returns:

node_id of interrupt specifier’s interrupt controller

DT_IRQN_BY_IDX(node_id, idx)

Get the node’s Zephyr interrupt number at index If CONFIG_MULTI_LEVEL_INTERRUPTS is enabled, the interrupt number at index will be multi-level encoded.

Parameters:

  • node_id – node identifier

  • idx – logical index into the interrupt specifier array

Returns:

the Zephyr interrupt number

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_NODE(fn)

Invokes fn for every node in the tree.

The macro fn must take one parameter, which will be a node identifier. The macro is expanded once for each node in the tree. The order that nodes are visited in is not specified.

Parameters:

  • fn – macro to invoke

DT_FOREACH_NODE_VARGS(fn, ...)

Invokes fn for every node in the tree with multiple arguments.

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

The macro is expanded once for each node in the tree. The order that nodes are visited in is not specified.

Parameters:

  • fn – macro to invoke

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

DT_FOREACH_STATUS_OKAY_NODE(fn)

Invokes fn for every status okay node in the tree.

The macro fn must take one parameter, which will be a node identifier. The macro is expanded once for each node in the tree with status okay (as usual, a missing status property is treated as status okay). The order that nodes are visited in is not specified.

Parameters:

  • fn – macro to invoke

DT_FOREACH_STATUS_OKAY_NODE_VARGS(fn, ...)

Invokes fn for every status okay node in the tree with multiple arguments.

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

The macro is expanded once for each node in the tree with status okay (as usual, a missing status property is treated as status okay). The order that nodes are visited in is not specified.

Parameters:

  • fn – macro to invoke

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

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.

The children will be iterated over in the same order as they appear in the final devicetree.

Example devicetree fragment:

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

Example usage:

#define FOOBAR_AND_COMMA(node_id) DT_PROP(node_id, foobar),

const char *child_foobars[] = {
    DT_FOREACH_CHILD(DT_NODELABEL(n), FOOBAR_AND_COMMA)
};

This expands to:

const char *child_foobars[] = {
    "foo", "bar",
};
Parameters:

  • node_id – node identifier

  • fn – macro to invoke

DT_FOREACH_CHILD_SEP(node_id, fn, sep)

Invokes fn for each child of node_id with a separator.

The macro fn must take one parameter, which will be the node identifier of a child node of node_id.

Example devicetree fragment:

n: node {
        child-1 {
                ...
        };
        child-2 {
                ...
        };
};

Example usage:

const char *child_names[] = {
    DT_FOREACH_CHILD_SEP(DT_NODELABEL(n), DT_NODE_FULL_NAME, (,))
};

This expands to:

const char *child_names[] = {
    "child-1", "child-2"
};
Parameters:

  • node_id – node identifier

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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.

The children will be iterated over in the same order as they appear in the final devicetree.

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_SEP_VARGS(node_id, fn, sep, ...)

Invokes fn for each child of node_id with separator and multiple arguments.

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

See also

DT_FOREACH_CHILD_VARGS

Parameters:

  • node_id – node identifier

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

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.

The children will be iterated over in the same order as they appear in the final devicetree.

Parameters:

  • node_id – node identifier

  • fn – macro to invoke

DT_FOREACH_CHILD_STATUS_OKAY_SEP(node_id, fn, sep)

Call fn on the child nodes with status okay with separator.

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

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

See also

DT_FOREACH_CHILD_STATUS_OKAY

Parameters:

  • node_id – node identifier

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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.

The children will be iterated over in the same order as they appear in the final devicetree.

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_CHILD_STATUS_OKAY_SEP_VARGS(node_id, fn, sep, ...)

Call fn on the child nodes with status okay with separator and multiple arguments.

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

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

See also

DT_FOREACH_CHILD_SEP_STATUS_OKAY

Parameters:

  • node_id – node identifier

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

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.

The prop argument must refer to a property that can be passed to DT_PROP_LEN().

Example devicetree fragment:

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

Example usage:

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

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

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

See also

DT_PROP_LEN

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • fn – macro to invoke

DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep)

Invokes fn for each element in the value of property prop with separator.

Example devicetree fragment:

n: node {
        my-gpios = <&gpioa 0 GPIO_ACTICE_HIGH>,
                   <&gpiob 1 GPIO_ACTIVE_HIGH>;
};

Example usage:

struct gpio_dt_spec specs[] = {
        DT_FOREACH_PROP_ELEM_SEP(DT_NODELABEL(n), my_gpios,
                                 GPIO_DT_SPEC_GET_BY_IDX, (,))
};

This expands as a first step to:

struct gpio_dt_spec specs[] = {
        GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), my_gpios, 0),
        GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), my_gpios, 1)
};

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

See also

DT_FOREACH_PROP_ELEM

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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.

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

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_PROP_ELEM_SEP_VARGS(node_id, prop, fn, sep, ...)

Invokes fn for each element in the value of property prop with multiple arguments and a separator.

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

See also

DT_FOREACH_PROP_ELEM_VARGS

Parameters:

  • node_id – node identifier

  • prop – lowercase-and-underscores property name

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

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.

Related code samples

GPIO with custom Devicetree binding

Use custom Devicetree binding to control a GPIO.

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 parent node inherits all dependencies from its child nodes

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_DEP_ORD_STR_SORTABLE(node_id)

Get a node’s dependency ordinal in string sortable form.

Parameters:

  • node_id – Node identifier

Returns:

the node’s dependency ordinal as a zero-padded 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 {
        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_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_PARENT(inst)

Get a DT_DRV_COMPAT parent’s node identifier.

See also

DT_PARENT

Parameters:

  • inst – instance number

Returns:

a node identifier for the instance’s parent

DT_INST_GPARENT(inst)

Get a DT_DRV_COMPAT grandparent’s node identifier.

See also

DT_GPARENT

Parameters:

  • inst – instance number

Returns:

a node identifier for the instance’s grandparent

DT_INST_CHILD(inst, child)

Get a node identifier for a child node of DT_DRV_INST(inst)

See also

DT_CHILD

Parameters:

  • inst – instance number

  • child – lowercase-and-underscores child node name

Returns:

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

DT_INST_CHILD_NUM(inst)

Get the number of child nodes of a given node.

This is equivalent to

See also

DT_CHILD_NUM(DT_DRV_INST(inst)).

Parameters:

  • inst – Devicetree instance number

Returns:

Number of child nodes

DT_INST_CHILD_NUM_STATUS_OKAY(inst)

Get the number of child nodes of a given node.

This is equivalent to

See also

DT_CHILD_NUM_STATUS_OKAY(DT_DRV_INST(inst)).

Parameters:

  • inst – Devicetree instance number

Returns:

Number of child nodes which status are okay

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.

The children will be iterated over in the same order as they appear in the final devicetree.

See also

DT_FOREACH_CHILD

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

DT_INST_FOREACH_CHILD_SEP(inst, fn, sep)

Call fn on all child nodes of DT_DRV_INST(inst) with a separator.

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

See also

DT_FOREACH_CHILD_SEP

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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.

The children will be iterated over in the same order as they appear in the final devicetree.

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_FOREACH_CHILD_SEP_VARGS(inst, fn, sep, ...)

Call fn on all child nodes of DT_DRV_INST(inst) with separator.

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_SEP_VARGS

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

DT_INST_FOREACH_CHILD_STATUS_OKAY(inst, fn)

Call fn on all child nodes of DT_DRV_INST(inst) with status okay.

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

See also

DT_FOREACH_CHILD_STATUS_OKAY

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

DT_INST_FOREACH_CHILD_STATUS_OKAY_SEP(inst, fn, sep)

Call fn on all child nodes of DT_DRV_INST(inst) with status okay and with separator.

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

See also

DT_FOREACH_CHILD_STATUS_OKAY_SEP

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

DT_INST_FOREACH_CHILD_STATUS_OKAY_VARGS(inst, fn, ...)

Call fn on all child nodes of DT_DRV_INST(inst) with status okay and multiple arguments.

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

See also

DT_FOREACH_CHILD_STATUS_OKAY_VARGS

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

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

DT_INST_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS(inst, fn, sep, ...)

Call fn on all child nodes of DT_DRV_INST(inst) with status okay and with separator and multiple arguments.

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

See also

DT_FOREACH_CHILD_STATUS_OKAY_SEP_VARGS

Parameters:

  • inst – instance number

  • fn – macro to invoke on each child node identifier

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

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 otherwise

DT_INST_ENUM_HAS_VALUE(inst, prop, value)

Does a DT_DRV_COMPAT enumeration property have a given value?

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • value – lowercase-and-underscores enumeration value

Returns:

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

DT_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_HAS_NAME(inst, prop, name)

Is name name available in a foo-names property?

Parameters:

  • inst – instance number

  • prop – a lowercase-and-underscores prop-names type property

  • name – a lowercase-and-underscores name to check

Returns:

An expression which evaluates to 1 if name is an available name into the given property, and 0 otherwise.

DT_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_PROP_LEN_OR(inst, prop, default_value)

Like DT_INST_PROP_LEN(), 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_LEN(inst, prop) or default_value

DT_INST_STRING_TOKEN(inst, prop)

Get a DT_DRV_COMPAT instance’s string property’s value as a token.

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

Returns:

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

DT_INST_STRING_UPPER_TOKEN(inst, prop)

Like DT_INST_STRING_TOKEN(), but uppercased.

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

Returns:

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

DT_INST_STRING_UNQUOTED(inst, prop)

Get a DT_DRV_COMPAT instance’s string property’s value as an unquoted sequence of tokens.

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

Returns:

the value of prop as a sequence of tokens, with no quotes

DT_INST_STRING_TOKEN_BY_IDX(inst, prop, idx)

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

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

the element in prop at index idx as a token

DT_INST_STRING_UPPER_TOKEN_BY_IDX(inst, prop, idx)

Like DT_INST_STRING_TOKEN_BY_IDX(), but uppercased.

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

the element in prop at index idx as an uppercased token

DT_INST_STRING_UNQUOTED_BY_IDX(inst, prop, idx)

Get an element out of string-array property as an unquoted sequence of tokens.

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • idx – the index to get

Returns:

the value of prop at index idx as a sequence of tokens, with no quotes

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_ADDR_BY_NAME_U64(inst, name)

64-bit version of DT_INST_REG_ADDR_BY_NAME()

This macro version adds the appropriate suffix for 64-bit unsigned integer literals. Note that this macro is equivalent to DT_INST_REG_ADDR_BY_NAME() in linker/ASM context.

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_ADDR_U64(inst)

64-bit version of DT_INST_REG_ADDR()

This macro version adds the appropriate suffix for 64-bit unsigned integer literals. Note that this macro is equivalent to DT_INST_REG_ADDR() in linker/ASM context.

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_LEVEL(inst)

Get a DT_DRV_COMPAT interrupt level.

Parameters:

  • inst – instance number

Returns:

interrupt level

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_INTC_BY_IDX(inst, idx)

Get a DT_DRV_COMPAT interrupt specifier’s interrupt controller by index.

Parameters:

  • inst – instance number

  • idx – interrupt specifier’s index

Returns:

node_id of interrupt specifier’s interrupt controller

DT_INST_IRQ_INTC_BY_NAME(inst, name)

Get a DT_DRV_COMPAT interrupt specifier’s interrupt controller by name.

Parameters:

  • inst – instance number

  • name – interrupt specifier’s name

Returns:

node_id of interrupt specifier’s interrupt controller

DT_INST_IRQ_INTC(inst)

Get a DT_DRV_COMPAT interrupt specifier’s interrupt controller.

See also

DT_INST_IRQ_INTC_BY_IDX()

Note

Equivalent to DT_INST_IRQ_INTC_BY_IDX(node_id, 0)

Parameters:

  • inst – instance number

Returns:

node_id of interrupt specifier’s interrupt controller

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_IRQN_BY_IDX(inst, idx)

Get a DT_DRV_COMPAT’s irq number at index.

Parameters:

  • inst – instance number

  • idx – logical index into the interrupt specifier array

Returns:

the interrupt number for the node’s idx-th 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_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_INST_STRING_TOKEN_OR(inst, name, default_value)

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

Parameters:

  • inst – instance number

  • name – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

if prop exists, its value as a token, i.e. without any quotes and with special characters converted to underscores. Othewise default_value

DT_INST_STRING_UPPER_TOKEN_OR(inst, name, default_value)

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

Parameters:

  • inst – instance number

  • name – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

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

DT_INST_STRING_UNQUOTED_OR(inst, name, default_value)

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

Parameters:

  • inst – instance number

  • name – lowercase-and-underscores property name

  • default_value – a fallback value to expand to

Returns:

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

DT_HAS_COMPAT_ON_BUS_STATUS_OKAY(compat, bus)
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_ANY_INST_HAS_PROP_STATUS_OKAY(prop)

Check if any DT_DRV_COMPAT node with status okay has a given property.

Example devicetree overlay:

&i2c0 {
    sensor0: sensor@0 {
        compatible = "vnd,some-sensor";
        status = "okay";
        reg = <0>;
        foo = <1>;
        bar = <2>;
    };

    sensor1: sensor@1 {
        compatible = "vnd,some-sensor";
        status = "okay";
        reg = <1>;
        foo = <2>;
    };

    sensor2: sensor@2 {
        compatible = "vnd,some-sensor";
        status = "disabled";
        reg = <2>;
        baz = <1>;
    };
};

Example usage:

#define DT_DRV_COMPAT vnd_some_sensor

DT_ANY_INST_HAS_PROP_STATUS_OKAY(foo) // 1
DT_ANY_INST_HAS_PROP_STATUS_OKAY(bar) // 1
DT_ANY_INST_HAS_PROP_STATUS_OKAY(baz) // 0
Parameters:

  • prop – lowercase-and-underscores property name

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";
        foobar = "DEV_A";
};

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

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

Example usage:

#define DT_DRV_COMPAT vnd_device
#define MY_FN(inst) DT_INST_PROP(inst, foobar),

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_SEP(inst, prop, fn, sep)

Invokes fn for each element of property prop for a DT_DRV_COMPAT instance with a separator.

Equivalent to DT_FOREACH_PROP_ELEM_SEP(DT_DRV_INST(inst), prop, fn, sep).

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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_FOREACH_PROP_ELEM_SEP_VARGS(inst, prop, fn, sep, ...)

Invokes fn for each element of property prop for a DT_DRV_COMPAT instance with multiple arguments and a sepatator.

Equivalent to DT_FOREACH_PROP_ELEM_SEP_VARGS(DT_DRV_INST(inst), prop, fn, sep, VA_ARGS)

See also

DT_INST_FOREACH_PROP_ELEM

Parameters:

  • inst – instance number

  • prop – lowercase-and-underscores property name

  • fn – macro to invoke

  • sep – Separator (e.g. comma or semicolon). Must be in parentheses; this is required to enable providing a comma as separator.

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

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_NODE_HAS_COMPAT(inst, compat)

Does a DT_DRV_COMPAT instance have the compatible?

Parameters:

  • inst – instance number

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

Returns:

1 if the instance matches the compatible, 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.

CAN

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

group devicetree-can

Defines

DT_CAN_TRANSCEIVER_MIN_BITRATE(node_id, min)

Get the minimum transceiver bitrate for a CAN controller.

The bitrate will be limited to the minimum bitrate supported by the CAN controller. If no CAN transceiver is present in the devicetree, the minimum bitrate will be that of the CAN controller.

Example devicetree fragment: 

transceiver0: can-phy0 {
        compatible = "vnd,can-transceiver";
        min-bitrate = <15000>;
        max-bitrate = <1000000>;
        #phy-cells = <0>;
};

can0: can@... {
        compatible = "vnd,can-controller";
        phys = <&transceiver0>;
};

can1: can@... {
        compatible = "vnd,can-controller";

        can-transceiver {
                min-bitrate = <25000>;
                max-bitrate = <2000000>;
        };
};

can2: can@... {
        compatible = "vnd,can-controller";

        can-transceiver {
                max-bitrate = <2000000>;
        };
};
Example usage: 
DT_CAN_TRANSCEIVER_MIN_BITRATE(DT_NODELABEL(can0), 10000) // 15000
DT_CAN_TRANSCEIVER_MIN_BITRATE(DT_NODELABEL(can1), 0)     // 250000
DT_CAN_TRANSCEIVER_MIN_BITRATE(DT_NODELABEL(can1), 50000) // 500000
DT_CAN_TRANSCEIVER_MIN_BITRATE(DT_NODELABEL(can2), 0)     // 0

Parameters:

  • node_id – node identifier

  • min – minimum bitrate supported by the CAN controller

Returns:

the minimum bitrate supported by the CAN controller/transceiver combination

DT_CAN_TRANSCEIVER_MAX_BITRATE(node_id, max)

Get the maximum transceiver bitrate for a CAN controller.

The bitrate will be limited to the maximum bitrate supported by the CAN controller. If no CAN transceiver is present in the devicetree, the maximum bitrate will be that of the CAN controller.

Example devicetree fragment: 

transceiver0: can-phy0 {
        compatible = "vnd,can-transceiver";
        max-bitrate = <1000000>;
        #phy-cells = <0>;
};

can0: can@... {
        compatible = "vnd,can-controller";
        phys = <&transceiver0>;
};

can1: can@... {
        compatible = "vnd,can-controller";

        can-transceiver {
                max-bitrate = <2000000>;
        };
};
Example usage: 
DT_CAN_TRANSCEIVER_MAX_BITRATE(DT_NODELABEL(can0), 5000000) // 1000000
DT_CAN_TRANSCEIVER_MAX_BITRATE(DT_NODELABEL(can1), 5000000) // 2000000
DT_CAN_TRANSCEIVER_MAX_BITRATE(DT_NODELABEL(can1), 1000000) // 1000000

Parameters:

  • node_id – node identifier

  • max – maximum bitrate supported by the CAN controller

Returns:

the maximum bitrate supported by the CAN controller/transceiver combination

DT_INST_CAN_TRANSCEIVER_MIN_BITRATE(inst, min)

Get the minimum transceiver bitrate for a DT_DRV_COMPAT CAN controller.

See also

DT_CAN_TRANSCEIVER_MIN_BITRATE()

Parameters:

  • inst – DT_DRV_COMPAT instance number

  • min – minimum bitrate supported by the CAN controller

Returns:

the minimum bitrate supported by the CAN controller/transceiver combination

DT_INST_CAN_TRANSCEIVER_MAX_BITRATE(inst, max)

Get the maximum transceiver bitrate for a DT_DRV_COMPAT CAN controller.

See also

DT_CAN_TRANSCEIVER_MAX_BITRATE()

Parameters:

  • inst – DT_DRV_COMPAT instance number

  • max – maximum bitrate supported by the CAN controller

Returns:

the maximum bitrate supported by the CAN controller/transceiver combination

Clocks

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

group devicetree-clocks

Defines

DT_CLOCKS_HAS_IDX(node_id, idx)

Test if a node has a clocks phandle-array property at a given index.

This expands to 1 if the given index is valid clocks property phandle-array index. Otherwise, it expands to 0.

Example devicetree fragment: 

n1: node-1 {
        clocks = <...>, <...>;
};

n2: node-2 {
        clocks = <...>;
};
Example usage: 
DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 0) // 1
DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 1) // 1
DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 2) // 0
DT_CLOCKS_HAS_IDX(DT_NODELABEL(n2), 1) // 0

Parameters:

  • node_id – node identifier; may or may not have any clocks property

  • idx – index of a clocks property phandle-array whose existence to check

Returns:

1 if the index exists, 0 otherwise

DT_CLOCKS_HAS_NAME(node_id, name)

Test if a node has a clock-names array property holds a given name.

This expands to 1 if the name is available as clocks-name array property cell. Otherwise, it expands to 0.

Example devicetree fragment: 

n1: node-1 {
        clocks = <...>, <...>;
        clock-names = "alpha", "beta";
};

n2: node-2 {
        clocks = <...>;
        clock-names = "alpha";
};
Example usage: 
DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), alpha) // 1
DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), beta)  // 1
DT_CLOCKS_HAS_NAME(DT_NODELABEL(n2), beta)  // 0

Parameters:

  • node_id – node identifier; may or may not have any clock-names property.

  • name – lowercase-and-underscores clock-names cell value name to check

Returns:

1 if the clock name exists, 0 otherwise

DT_NUM_CLOCKS(node_id)

Get the number of elements in a clocks property.

Example devicetree fragment: 

n1: node-1 {
        clocks = <&foo>, <&bar>;
};

n2: node-2 {
        clocks = <&foo>;
};
Example usage: 
DT_NUM_CLOCKS(DT_NODELABEL(n1)) // 2
DT_NUM_CLOCKS(DT_NODELABEL(n2)) // 1

Parameters:

  • node_id – node identifier with a clocks property

Returns:

number of elements in the property

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 by name.

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_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_HAS_IDX(inst, idx)

Equivalent to DT_CLOCKS_HAS_IDX(DT_DRV_INST(inst), idx)

Parameters:

  • inst – DT_DRV_COMPAT instance number; may or may not have any clocks property

  • idx – index of a clocks property phandle-array whose existence to check

Returns:

1 if the index exists, 0 otherwise

DT_INST_CLOCKS_HAS_NAME(inst, name)

Equivalent to DT_CLOCK_HAS_NAME(DT_DRV_INST(inst), name)

Parameters:

  • inst – DT_DRV_COMPAT instance number; may or may not have any clock-names property.

  • name – lowercase-and-underscores clock-names cell value name to check

Returns:

1 if the clock name exists, 0 otherwise

DT_INST_NUM_CLOCKS(inst)

Equivalent to DT_NUM_CLOCKS(DT_DRV_INST(inst))

Parameters:

  • inst – instance number

Returns:

number of elements in the clocks property

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_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_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_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 See fixed-partition for more details.

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_EXISTS(node_id)

Test if fixed-partition compatible node exists.

Parameters:

  • node_id – DTS node to test

Returns:

1 if node exists and is fixed-partition compatible, 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_MEM_FROM_FIXED_PARTITION(node_id)

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

Parameters:

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

Returns:

the node identifier of the internal memory that contains the fixed-partitions node, or DT_INVALID_NODE if it doesn’t exist.

DT_MTD_FROM_FIXED_PARTITION(node_id)

Get the node identifier of the flash controller 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.

DT_FIXED_PARTITION_ADDR(node_id)

Get the absolute address of a fixed partition.

Example devicetree fragment: 

&flash_controller {
        flash@1000000 {
                compatible = "soc-nv-flash";
                partitions {
                        compatible = "fixed-partitions";
                        storage_partition: partition@3a000 {
                                label = "storage";
                        };
                };
        };
};
Here, the “storage” partition is seen to belong to flash memory starting at address 0x1000000. The partition’s unit address of 0x3a000 represents an offset inside that flash memory.

Example usage: 

DT_FIXED_PARTITION_ADDR(DT_NODELABEL(storage_partition)) // 0x103a000
This macro can only be used with partitions of internal memory addressable by the CPU. Otherwise, it may produce a compile-time error, such as: __REG_IDX_0_VAL_ADDRESS’ undeclared`.

Parameters:

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

Returns:

the partition’s offset plus the base address of the flash node containing it.

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_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_NUM_GPIO_HOGS(node_id)

Get the number of GPIO hogs in a node.

This expands to the number of hogged GPIOs, or zero if there are none.

Example devicetree fragment: 

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

  n1: node-1 {
          gpio-hog;
          gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
          output-high;
  };

  n2: node-2 {
          gpio-hog;
          gpios = <3 GPIO_ACTIVE_HIGH>;
          output-low;
  };
};
Bindings fragment for the vnd,gpio compatible: 
gpio-cells:
  - pin
  - flags
Example usage: 
DT_NUM_GPIO_HOGS(DT_NODELABEL(n1)) // 2
DT_NUM_GPIO_HOGS(DT_NODELABEL(n2)) // 1

Parameters:

  • node_id – node identifier; may or may not be a GPIO hog node.

Returns:

number of hogged GPIOs in the node

DT_GPIO_HOG_PIN_BY_IDX(node_id, idx)

Get a GPIO hog 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>;

  n1: node-1 {
          gpio-hog;
          gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
          output-high;
  };

  n2: node-2 {
          gpio-hog;
          gpios = <3 GPIO_ACTIVE_HIGH>;
          output-low;
  };
};
Bindings fragment for the vnd,gpio compatible: 
gpio-cells:
  - pin
  - flags
Example usage: 
DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 0) // 0
DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n1), 1) // 1
DT_GPIO_HOG_PIN_BY_IDX(DT_NODELABEL(n2), 0) // 3

Parameters:

  • node_id – node identifier

  • idx – logical index into “gpios”

Returns:

the pin cell value at index “idx”

DT_GPIO_HOG_FLAGS_BY_IDX(node_id, idx)

Get a GPIO hog 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>;

  n1: node-1 {
          gpio-hog;
          gpios = <0 GPIO_ACTIVE_HIGH>, <1 GPIO_ACTIVE_LOW>;
          output-high;
  };

  n2: node-2 {
          gpio-hog;
          gpios = <3 GPIO_ACTIVE_HIGH>;
          output-low;
  };
};
Bindings fragment for the vnd,gpio compatible: 
gpio-cells:
  - pin
  - flags
Example usage: 
DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 0) // GPIO_ACTIVE_HIGH
DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n1), 1) // GPIO_ACTIVE_LOW
DT_GPIO_HOG_FLAGS_BY_IDX(DT_NODELABEL(n2), 0) // GPIO_ACTIVE_HIGH

Parameters:

  • node_id – node identifier

  • idx – logical index into “gpios”

Returns:

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

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

MBOX

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

group devicetree-mbox

Defines

DT_MBOX_CTLR_BY_NAME(node_id, name)

Get the node identifier for the MBOX controller from a mboxes property by name.

Example devicetree fragment: 

mbox1: mbox-controller@... { ... };

n: node {
        mboxes = <&mbox1 8>,
                 <&mbox1 9>;
        mbox-names = "tx", "rx";
};
Example usage: 
DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(mbox1)
DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(mbox1)

See also

DT_PHANDLE_BY_NAME()

Parameters:

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

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

Returns:

the node identifier for the MBOX controller in the named element

DT_MBOX_CHANNEL_BY_NAME(node_id, name)

Get a MBOX channel value by name.

Example devicetree fragment: 

mbox1: mbox@... {
        #mbox-cells = <1>;
};

n: node {
    mboxes = <&mbox1 1>,
             <&mbox1 6>;
    mbox-names = "tx", "rx";
};
Bindings fragment for the mbox compatible: 
mbox-cells:
  - channel
Example usage: 
DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), tx) // 1
DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), rx) // 6

See also

DT_PHA_BY_NAME_OR()

Parameters:

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

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

Returns:

the channel value in the specifier at the named element or 0 if no channels are supported

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_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";
        #pwm-cells = <2>;
};

pwm2: pwm-controller@... {
        compatible = "vnd,pwm";
        #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";
        #pwm-cells = <2>;
};

pwm2: pwm-controller@... {
        compatible = "vnd,pwm";
        #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_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

Reset Controller

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

group devicetree-reset-controller

Defines

DT_RESET_CTLR_BY_IDX(node_id, idx)

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

Example devicetree fragment: 

reset1: reset-controller@... { ... };

reset2: reset-controller@... { ... };

n: node {
        resets = <&reset1 10>, <&reset2 20>;
};
Example usage: 
DT_RESET_CTLR_BY_IDX(DT_NODELABEL(n), 0)) // DT_NODELABEL(reset1)
DT_RESET_CTLR_BY_IDX(DT_NODELABEL(n), 1)) // DT_NODELABEL(reset2)

See also

DT_PHANDLE_BY_IDX()

Parameters:

  • node_id – node identifier

  • idx – logical index into “resets”

Returns:

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

DT_RESET_CTLR(node_id)

Equivalent to DT_RESET_CTLR_BY_IDX(node_id, 0)

See also

DT_RESET_CTLR_BY_IDX()

Parameters:

  • node_id – node identifier

Returns:

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

DT_RESET_CTLR_BY_NAME(node_id, name)

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

Example devicetree fragment: 

reset1: reset-controller@... { ... };

reset2: reset-controller@... { ... };

n: node {
        resets = <&reset1 10>, <&reset2 20>;
        reset-names = "alpha", "beta";
};
Example usage: 
DT_RESET_CTLR_BY_NAME(DT_NODELABEL(n), alpha) // DT_NODELABEL(reset1)
DT_RESET_CTLR_BY_NAME(DT_NODELABEL(n), beta) // DT_NODELABEL(reset2)

See also

DT_PHANDLE_BY_NAME()

Parameters:

  • node_id – node identifier

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

Returns:

the node identifier for the reset controller referenced by name

DT_RESET_CELL_BY_IDX(node_id, idx, cell)

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

Example devicetree fragment: 

reset: reset-controller@... {
        compatible = "vnd,reset";
        #reset-cells = <1>;
};

n: node {
        resets = <&reset 10>;
};
Bindings fragment for the vnd,reset compatible: 
reset-cells:
  - id
Example usage: 
DT_RESET_CELL_BY_IDX(DT_NODELABEL(n), 0, id) // 10

See also

DT_PHA_BY_IDX()

Parameters:

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

  • idx – logical index into resets property

  • cell – lowercase-and-underscores cell name

Returns:

the cell value at index “idx”

DT_RESET_CELL_BY_NAME(node_id, name, cell)

Get a reset specifier’s cell value by name.

Example devicetree fragment: 

reset: reset-controller@... {
        compatible = "vnd,reset";
        #reset-cells = <1>;
};

n: node {
        resets = <&reset 10>;
        reset-names = "alpha";
};
Bindings fragment for the vnd,reset compatible: 
reset-cells:
  - id
Example usage: 
DT_RESET_CELL_BY_NAME(DT_NODELABEL(n), alpha, id) // 10

See also

DT_PHA_BY_NAME()

Parameters:

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

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

  • cell – lowercase-and-underscores cell name

Returns:

the cell value in the specifier at the named element

DT_RESET_CELL(node_id, cell)

Equivalent to DT_RESET_CELL_BY_IDX(node_id, 0, cell)

See also

DT_RESET_CELL_BY_IDX()

Parameters:

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

  • cell – lowercase-and-underscores cell name

Returns:

the cell value at index 0

DT_INST_RESET_CTLR_BY_IDX(inst, idx)

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

See also

DT_RESET_CTLR_BY_IDX()

Parameters:

  • inst – instance number

  • idx – logical index into “resets”

Returns:

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

DT_INST_RESET_CTLR(inst)

Equivalent to DT_INST_RESET_CTLR_BY_IDX(inst, 0)

See also

DT_RESET_CTLR()

Parameters:

  • inst – instance number

Returns:

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

DT_INST_RESET_CTLR_BY_NAME(inst, name)

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

See also

DT_RESET_CTLR_BY_NAME()

Parameters:

  • inst – instance number

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

Returns:

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

DT_INST_RESET_CELL_BY_IDX(inst, idx, cell)

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

See also

DT_RESET_CELL_BY_IDX()

Parameters:

  • inst – DT_DRV_COMPAT instance number

  • idx – logical index into resets property

  • cell – lowercase-and-underscores cell name

Returns:

the cell value at index “idx”

DT_INST_RESET_CELL_BY_NAME(inst, name, cell)

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

See also

DT_RESET_CELL_BY_NAME()

Parameters:

  • inst – DT_DRV_COMPAT instance number

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

  • cell – lowercase-and-underscores cell name

Returns:

the cell value in the specifier at the named element

DT_INST_RESET_CELL(inst, cell)

Equivalent to DT_INST_RESET_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

DT_RESET_ID_BY_IDX(node_id, idx)

Get a Reset Controller specifier’s id cell at an index.

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

Example devicetree fragment: 

reset: reset-controller@... {
        compatible = "vnd,reset";
        #reset-cells = <1>;
};

n: node {
        resets = <&reset 10>;
};
Bindings fragment for the vnd,reset compatible: 
reset-cells:
  - id
Example usage: 
DT_RESET_ID_BY_IDX(DT_NODELABEL(n), 0) // 10

See also

DT_PHA_BY_IDX()

Parameters:

  • node_id – node identifier

  • idx – logical index into “resets”

Returns:

the id cell value at index “idx”

DT_RESET_ID(node_id)

Equivalent to DT_RESET_ID_BY_IDX(node_id, 0)

See also

DT_RESET_ID_BY_IDX()

Parameters:

  • node_id – node identifier

Returns:

the id cell value at index 0

DT_INST_RESET_ID_BY_IDX(inst, idx)

Get a DT_DRV_COMPAT instance’s Reset Controller specifier’s id cell value at an index.

See also

DT_RESET_ID_BY_IDX()

Parameters:

  • inst – DT_DRV_COMPAT instance number

  • idx – logical index into “resets”

Returns:

the id cell value at index “idx”

DT_INST_RESET_ID(inst)

Equivalent to DT_INST_RESET_ID_BY_IDX(inst, 0)

See also

DT_INST_RESET_ID_BY_IDX()

Parameters:

  • inst – DT_DRV_COMPAT instance number

Returns:

the id cell value at index 0

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

Zephyr-specific chosen nodes

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.

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,keyboard-scan

Sets the default keyboard scan 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,gdbstub-uart

Sets UART device used by the GDB stub subsystem

zephyr,ieee802154

Used by the networking subsystem to set the IEEE 802.15.4 device

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,log-uart

Sets the UART device(s) used by the logging subsystem’s UART backend. If defined, the UART log backend would output to the devices listed in this node.

zephyr,ocm

On-chip memory node on Xilinx Zynq-7000 and ZynqMP SoCs

zephyr,osdp-uart

Sets UART device used by OSDP subsystem

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,ppp-uart

Sets UART device used by PPP

zephyr,settings-partition

Fixed partition node. If defined this selects the partition used by the NVS and FCB settings backends.

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,tracing-uart

Sets UART device used by tracing subsystem

zephyr,uart-mcumgr

UART used for Device Management

zephyr,uart-pipe

Sets UART device used by serial pipe driver

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