Devicetree API¶
This is a reference page for the <devicetree.h>
API. The API is macro
based. Use of these macros has no impact on scheduling. They can be used from
any calling context and at file scope.
Some of these require a special macro named DT_DRV_COMPAT
to be defined
before they can be used; these are discussed individually below. These macros
are generally meant for use within device drivers,
though they can be used outside of drivers with appropriate care.
Generic APIs¶
The APIs in this section can be used anywhere and do not require
DT_DRV_COMPAT
to be defined.
Node identifiers¶
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.
-
group
devicetree-generic-id
Defines
-
DT_ROOT
¶ Node identifier for the root node in the devicetree.
-
DT_PATH
(...)¶ Get a node identifier for a devicetree path.
The arguments to this macro are the names of non-root nodes in the tree required to reach the desired node, starting from the root. Non-alphanumeric characters in each name must be converted to underscores to form valid C tokens, and letters must be lowercased.
Example devicetree fragment:
/ { soc { serial1: serial@40001000 { status = "okay"; current-speed = <115200>; ... }; }; };
You can use DT_PATH(soc, serial_40001000) to get a node identifier for the serial@40001000 node. Node labels like “serial1” cannot be used as DT_PATH() arguments; use DT_NODELABEL() for those instead.
Example usage with DT_PROP() to get the current-speed property:
DT_PROP(DT_PATH(soc, serial_40001000), current_speed) // 115200
(The current-speed property is also in “lowercase-and-underscores” form when used with this API.)
When determining arguments to DT_PATH():
the first argument corresponds to a child node of the root (“soc” above)
a second argument corresponds to a child of the first argument (“serial_40001000” above, from the node name “serial@40001000” after lowercasing and changing “@” to “_”)
and so on for deeper nodes in the desired node’s path
- Return
node identifier for the node with that path
- Parameters
...
: lowercase-and-underscores node names along the node’s path, with each name given as a separate argument
-
DT_NODELABEL
(label)¶ Get a node identifier for a node label.
Convert non-alphanumeric characters in the node label to underscores to form valid C tokens, and lowercase all letters. Note that node labels are not the same thing as label properties.
Example devicetree fragment:
serial1: serial@40001000 { label = "UART_0"; status = "okay"; current-speed = <115200>; ... };
The only node label in this example is “serial1”.
The string “UART_0” is not a node label; it’s the value of a property named label.
You can use DT_NODELABEL(serial1) to get a node identifier for the serial@40001000 node. Example usage with DT_PROP() to get the current-speed property:
DT_PROP(DT_NODELABEL(serial1), current_speed) // 115200
Another example devicetree fragment:
cpu@0 { L2_0: l2-cache { cache-level = <2>; ... }; };
Example usage to get the cache-level property:
DT_PROP(DT_NODELABEL(l2_0), cache_level) // 2
Notice how “L2_0” in the devicetree is lowercased to “l2_0” in the DT_NODELABEL() argument.
- Return
node identifier for the node with that label
- Parameters
label
: lowercase-and-underscores node label name
-
DT_ALIAS
(alias)¶ Get a node identifier from /aliases.
This macro’s argument is a property of the /aliases node. It returns a node identifier for the node which is aliased. Convert non-alphanumeric characters in the alias property to underscores to form valid C tokens, and lowercase all letters.
Example devicetree fragment:
/ { aliases { my-serial = &serial1; }; soc { serial1: serial@40001000 { status = "okay"; current-speed = <115200>; ... }; }; };
You can use DT_ALIAS(my_serial) to get a node identifier for the serial@40001000 node. Notice how my-serial in the devicetree becomes my_serial in the DT_ALIAS() argument. Example usage with DT_PROP() to get the current-speed property:
DT_PROP(DT_ALIAS(my_serial), current_speed) // 115200
- Return
node identifier for the node with that alias
- Parameters
alias
: lowercase-and-underscores alias name.
-
DT_INST
(inst, compat)¶ Get a node identifier for an instance of a compatible.
All nodes with a particular compatible property value are assigned instance numbers, which are zero-based indexes specific to that compatible. You can get a node identifier for these nodes by passing DT_INST() an instance number, “inst”, along with the lowercase-and-underscores version of the compatible, “compat”.
Instance numbers have the following properties:
for each compatible, instance numbers start at 0 and are contiguous
exactly one instance number is assigned for each node with a compatible, including disabled nodes
enabled nodes (status property is “okay” or missing) are assigned the instance numbers starting from 0, and disabled nodes have instance numbers which are greater than those of any enabled node
No other guarantees are made. In particular:
instance numbers in no way reflect any numbering scheme that might exist in SoC documentation, node labels or unit addresses, or properties of the /aliases node (use DT_NODELABEL() or DT_ALIAS() for those)
there is no general guarantee that the same node will have the same instance number between builds, even if you are building the same application again in the same build directory
Example devicetree fragment:
serial1: serial@40001000 { compatible = "vnd,soc-serial"; status = "disabled"; current-speed = <9600>; ... }; serial2: serial@40002000 { compatible = "vnd,soc-serial"; status = "okay"; current-speed = <57600>; ... }; serial3: serial@40003000 { compatible = "vnd,soc-serial"; current-speed = <115200>; ... };
Assuming no other nodes in the devicetree have compatible “vnd,soc-serial”, that compatible has nodes with instance numbers 0, 1, and 2.
The nodes serial@40002000 and serial@40003000 are both enabled, so their instance numbers are 0 and 1, but no guarantees are made regarding which node has which instance number.
Since serial@40001000 is the only disabled node, it has instance number 2, since disabled nodes are assigned the largest instance numbers. Therefore:
// Could be 57600 or 115200. There is no way to be sure: // either serial@40002000 or serial@40003000 could // have instance number 0, so this could be the current-speed // property of either of those nodes. DT_PROP(DT_INST(0, vnd_soc_serial), current_speed) // Could be 57600 or 115200, for the same reason. // If the above expression expands to 57600, then // this expands to 115200, and vice-versa. DT_PROP(DT_INST(1, vnd_soc_serial), current_speed) // 9600, because there is only one disabled node, and // disabled nodes are "at the the end" of the instance // number "list". DT_PROP(DT_INST(2, vnd_soc_serial), current_speed)
Notice how “vnd,soc-serial” in the devicetree becomes vnd_soc_serial (without quotes) in the DT_INST() arguments. (As usual, current-speed in the devicetree becomes current_speed as well.)
Nodes whose “compatible” property has multiple values are assigned independent instance numbers for each compatible.
- Return
node identifier for the node with that instance number and compatible
- Parameters
inst
: instance number for compatible “compat”compat
: lowercase-and-underscores compatible, without quotes
-
DT_PARENT
(node_id)¶ Get a node identifier for a parent node.
Example devicetree fragment:
parent: parent-node { child: child-node { ... }; };
The following are equivalent ways to get the same node identifier:
DT_NODELABEL(parent) DT_PARENT(DT_NODELABEL(child))
- Return
a node identifier for the node’s parent
- Parameters
node_id
: node identifier
-
DT_CHILD
(node_id, child)¶ Get a node identifier for a child node.
Example devicetree fragment:
/ { soc-label: soc { serial1: serial@40001000 { status = "okay"; current-speed = <115200>; ... }; }; };
Example usage with DT_PROP() to get the status of the serial@40001000 node:
#define SOC_NODE DT_NODELABEL(soc_label) DT_PROP(DT_CHILD(SOC_NODE, serial_40001000), status) // "okay"
Node labels like “serial1” cannot be used as the “child” argument to this macro. Use DT_NODELABEL() for that instead.
You can also use DT_FOREACH_CHILD() to iterate over node identifiers for all of a node’s children.
- Return
node identifier for the node with the name referred to by ‘child’
- Parameters
node_id
: node identifierchild
: lowercase-and-underscores child node name
-
Property access¶
The following general-purpose macros can be used to access node properties. There are special-purpose APIs for accessing the reg property and interrupts property.
Property values can be read using these macros even if the node is disabled, as long as it has a matching binding.
-
group
devicetree-generic-prop
Defines
-
DT_PROP
(node_id, prop)¶ Get a devicetree property value.
For properties whose bindings have the following types, this macro expands to:
string: a string literal
boolean: 0 if the property is false, or 1 if it is true
int: the property’s value as an integer literal
array, uint8-array, string-array: an initializer expression in braces, whose elements are integer or string literals (like {0, 1, 2}, {“hello”, “world”}, etc.)
phandle: a node identifier for the node with that phandle
A property’s type is usually defined by its binding. In some special cases, it has an assumed type defined by the devicetree specification even when no binding is available: “compatible” has type string-array, “status” and “label” have type string, and “interrupt-controller” has type boolean.
For other properties or properties with unknown type due to a missing binding, behavior is undefined.
For usage examples, see DT_PATH(), DT_ALIAS(), DT_NODELABEL(), and DT_INST() above.
- Return
a representation of the property’s value
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property name
-
DT_PROP_LEN
(node_id, prop)¶ Get a property’s logical length.
Here, “length” is a number of elements, which may differ from the property’s size in bytes.
The return value depends on the property’s type:
for types array, string-array, and uint8-array, this expands to the number of elements in the array
for type phandles, this expands to the number of phandles
for type phandle-array, this expands to the number of phandle and specifier blocks in the property
These properties are handled as special cases:
reg property: use DT_NUM_REGS(node_id) instead
interrupts property: use DT_NUM_IRQS(node_id) instead
It is an error to use this macro with the reg or interrupts properties.
For other properties, behavior is undefined.
- Return
the property’s length
- Parameters
node_id
: node identifierprop
: a lowercase-and-underscores property with a logical length
-
DT_PROP_HAS_IDX
(node_id, prop, idx)¶ Is index “idx” valid for an array type property?
If this returns 1, then DT_PROP_BY_IDX(node_id, prop, idx) or DT_PHA_BY_IDX(node_id, prop, idx, …) are valid at index “idx”. If it returns 0, it is an error to use those macros with that index.
These properties are handled as special cases:
reg property: use DT_REG_HAS_IDX(node_id, idx) instead
interrupts property: use DT_IRQ_HAS_IDX(node_id, idx) instead
It is an error to use this macro with the reg or interrupts properties.
- Return
An expression which evaluates to 1 if “idx” is a valid index into the given property, and 0 otherwise.
- Parameters
node_id
: node identifierprop
: a lowercase-and-underscores property with a logical lengthidx
: index to check
-
DT_PROP_BY_IDX
(node_id, prop, idx)¶ Get the value at index “idx” in an array type property.
It might help to read the argument order as being similar to “node->property[index]”.
When the property’s binding has type array, string-array, uint8-array, or phandles, this expands to the idx-th array element as an integer, string literal, or node identifier respectively.
These properties are handled as special cases:
reg property: use DT_REG_ADDR_BY_IDX() or DT_REG_SIZE_BY_IDX() instead
interrupts property: use DT_IRQ_BY_IDX() instead
For non-array properties, behavior is undefined.
- Return
a representation of the idx-th element of the property
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property nameidx
: the index to get
-
DT_PROP_OR
(node_id, prop, default_value)¶ Like DT_PROP(), but with a fallback to default_value.
If the value exists, this expands to DT_PROP(node_id, prop). The default_value parameter is not expanded in this case.
Otherwise, this expands to default_value.
- Return
the property’s value or default_value
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property namedefault_value
: a fallback value to expand to
-
DT_LABEL
(node_id)¶ Equivalent to DT_PROP(node_id, label)
This is a convenience for the Zephyr device API, which uses label properties as device_get_binding() arguments.
- Return
node’s label property value
- Parameters
node_id
: node identifier
-
DT_ENUM_IDX
(node_id, prop)¶ Get a property value’s index into its enumeration values.
The return values start at zero.
Example devicetree fragment:
usb1: usb@12340000 { maximum-speed = "full-speed"; }; usb2: usb@12341000 { maximum-speed = "super-speed"; };
Example bindings fragment:
properties: maximum-speed: type: string enum: - "low-speed" - "full-speed" - "high-speed" - "super-speed"
Example usage:
DT_ENUM_IDX(DT_NODELABEL(usb1), maximum_speed) // 1 DT_ENUM_IDX(DT_NODELABEL(usb2), maximum_speed) // 3
- Return
zero-based index of the property’s value in its enum: list
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property name
-
DT_ENUM_IDX_OR
(node_id, prop, default_idx_value)¶ Like DT_ENUM_IDX(), but with a fallback to a default enum index.
If the value exists, this expands to its zero based index value thanks to DT_ENUM_IDX(node_id, prop).
Otherwise, this expands to provided default index enum value.
- Return
zero-based index of the property’s value in its enum if present, default_idx_value ohterwise
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property namedefault_idx_value
: a fallback index value to expand to
-
DT_PROP_BY_PHANDLE_IDX
(node_id, phs, idx, prop)¶ Get a property value from a phandle in a property.
This is a shorthand for:
DT_PROP(DT_PHANDLE_BY_IDX(node_id, phs, idx), prop)
That is, “prop” is a property of the phandle’s node, not a property of “node_id”.
Example devicetree fragment:
n1: node-1 { foo = <&n2 &n3>; }; n2: node-2 { bar = <42>; }; n3: node-3 { baz = <43>; };
Example usage:
#define N1 DT_NODELABEL(n1) DT_PROP_BY_PHANDLE_IDX(N1, foo, 0, bar) // 42 DT_PROP_BY_PHANDLE_IDX(N1, foo, 1, baz) // 43
- Return
the property’s value
- Parameters
node_id
: node identifierphs
: lowercase-and-underscores property with type “phandle”, “phandles”, or “phandle-array”idx
: logical index into “phs”, which must be zero if “phs” has type “phandle”prop
: lowercase-and-underscores property of the phandle’s node
-
DT_PROP_BY_PHANDLE
(node_id, ph, prop)¶ Get a property value from a phandle’s node.
This is equivalent to DT_PROP_BY_PHANDLE_IDX(node_id, ph, 0, prop).
- Return
the property’s value
- Parameters
node_id
: node identifierph
: lowercase-and-underscores property of “node_id” with type “phandle”prop
: lowercase-and-underscores property of the phandle’s node
-
DT_PHA_BY_IDX
(node_id, pha, idx, cell)¶ Get a phandle-array specifier cell value at an index.
It might help to read the argument order as being similar to “node->phandle_array[index].cell”. That is, the cell value is in the “pha” property of “node_id”, inside the specifier at index “idx”.
Example devicetree fragment:
gpio0: gpio@... { #gpio-cells = <2>; }; gpio1: gpio@... { #gpio-cells = <2>; }; led: led_0 { gpios = <&gpio0 17 0x1>, <&gpio1 5 0x3>; };
Bindings fragment for the gpio0 and gpio1 nodes:
gpio-cells: - pin - flags
Above, “gpios” has two elements:
index 0 has specifier <17 0x1>, so its “pin” cell is 17, and its “flags” cell is 0x1
index 1 has specifier <5 0x3>, so “pin” is 5 and “flags” is 0x3
Example usage:
#define LED DT_NODELABEL(led) DT_PHA_BY_IDX(LED, gpios, 0, pin) // 17 DT_PHA_BY_IDX(LED, gpios, 1, flags) // 0x3
- Return
the cell’s value
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”idx
: logical index into “pha”cell
: lowercase-and-underscores cell name within the specifier at “pha” index “idx”
-
DT_PHA_BY_IDX_OR
(node_id, pha, idx, cell, default_value)¶ Like DT_PHA_BY_IDX(), but with a fallback to default_value.
If the value exists, this expands to DT_PHA_BY_IDX(node_id, pha, idx, cell). The default_value parameter is not expanded in this case.
Otherwise, this expands to default_value.
- Return
the cell’s value or “default_value”
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”idx
: logical index into “pha”cell
: lowercase-and-underscores cell name within the specifier at “pha” index “idx”default_value
: a fallback value to expand to
-
DT_PHA
(node_id, pha, cell)¶ Equivalent to DT_PHA_BY_IDX(node_id, pha, 0, cell)
- Return
the cell’s value
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”cell
: lowercase-and-underscores cell name
-
DT_PHA_OR
(node_id, pha, cell, default_value)¶ Like DT_PHA(), but with a fallback to default_value.
If the value exists, this expands to DT_PHA(node_id, pha, cell). The default_value parameter is not expanded in this case.
Otherwise, this expands to default_value.
- Return
the cell’s value or default_value
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”cell
: lowercase-and-underscores cell namedefault_value
: a fallback value to expand to
-
DT_PHA_BY_NAME
(node_id, pha, name, cell)¶ Get a value within a phandle-array specifier by name.
This is like DT_PHA_BY_IDX(), except it treats “pha” as a structure where each array element has a name.
It might help to read the argument order as being similar to “node->phandle_struct.name.cell”. That is, the cell value is in the “pha” property of “node_id”, treated as a data structure where each array element has a name.
Example devicetree fragment:
n: node { io-channels = <&adc1 10>, <&adc2 20>; io-channel-names = "SENSOR", "BANDGAP"; };
Bindings fragment for the “adc1” and “adc2” nodes:
io-channel-cells: - input
Example usage:
DT_PHA_BY_NAME(DT_NODELABEL(n), io_channels, sensor, input) // 10 DT_PHA_BY_NAME(DT_NODELABEL(n), io_channels, bandgap, input) // 20
- Return
the cell’s value
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”name
: lowercase-and-underscores name of a specifier in “pha”cell
: lowercase-and-underscores cell name in the named specifier
-
DT_PHA_BY_NAME_OR
(node_id, pha, name, cell, default_value)¶ Like DT_PHA_BY_NAME(), but with a fallback to default_value.
If the value exists, this expands to DT_PHA_BY_NAME(node_id, pha, name, cell). The default_value parameter is not expanded in this case.
Otherwise, this expands to default_value.
- Return
the cell’s value or default_value
- Parameters
node_id
: node identifierpha
: 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 specifierdefault_value
: a fallback value to expand to
-
DT_PHANDLE_BY_NAME
(node_id, pha, name)¶ Get a phandle’s node identifier from a phandle array by name.
It might help to read the argument order as being similar to “node->phandle_struct.name.phandle”. That is, the phandle array is treated as a structure with named elements. The return value is the node identifier for a phandle inside the structure.
Example devicetree fragment:
adc1: adc@... { label = "ADC_1"; }; adc2: adc@... { label = "ADC_2"; }; n: node { io-channels = <&adc1 10>, <&adc2 20>; io-channel-names = "SENSOR", "BANDGAP"; };
Above, “io-channels” has two elements:
the element named “SENSOR” has phandle &adc1
the element named “BANDGAP” has phandle &adc2
Example usage:
#define NODE DT_NODELABEL(n) DT_LABEL(DT_PHANDLE_BY_NAME(NODE, io_channels, sensor)) // "ADC_1" DT_LABEL(DT_PHANDLE_BY_NAME(NODE, io_channels, bandgap)) // "ADC_2"
Notice how devicetree properties and names are lowercased, and non-alphanumeric characters are converted to underscores.
- Return
a node identifier for the node with that phandle
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”name
: lowercase-and-underscores name of an element in “pha”
-
DT_PHANDLE_BY_IDX
(node_id, prop, idx)¶ Get a node identifier for a phandle in a property.
When a node’s value at a logical index contains a phandle, this macro returns a node identifier for the node with that phandle.
Therefore, if “prop” has type “phandle”, “idx” must be zero. (A “phandle” type is treated as a “phandles” with a fixed length of 1).
Example devicetree fragment:
n1: node-1 { foo = <&n2 &n3>; }; n2: node-2 { ... }; n3: node-3 { ... };
Above, “foo” has type phandles and has two elements:
index 0 has phandle &n2, which is node-2’s phandle
index 1 has phandle &n3, which is node-3’s phandle
Example usage:
#define N1 DT_NODELABEL(n1) DT_PHANDLE_BY_IDX(N1, foo, 0) // node identifier for node-2 DT_PHANDLE_BY_IDX(N1, foo, 1) // node identifier for node-3
Behavior is analogous for phandle-arrays.
- Return
node identifier for the node with the phandle at that index
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property name in “node_id” with type “phandle”, “phandles” or “phandle-array”idx
: index into “prop”
-
DT_PHANDLE
(node_id, prop)¶ Get a node identifier for a phandle property’s value.
This is equivalent to DT_PHANDLE_BY_IDX(node_id, prop, 0). Its primary benefit is readability when “prop” has type “phandle”.
- Return
a node identifier for the node pointed to by “ph”
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property of “node_id” with type “phandle”
-
reg
property¶
Use these APIs instead of Property access to access the
reg
property. Because this property’s semantics are defined by the
devicetree specification, these macros can be used even for nodes without
matching bindings.
-
group
devicetree-reg-prop
Defines
-
DT_NUM_REGS
(node_id)¶ Get the number of register blocks in the reg property.
Use this instead of DT_PROP_LEN(node_id, reg).
- Return
Number of register blocks in the node’s “reg” property.
- Parameters
node_id
: node identifier
-
DT_REG_HAS_IDX
(node_id, idx)¶ Is “idx” a valid register block index?
If this returns 1, then DT_REG_ADDR_BY_IDX(node_id, idx) or DT_REG_SIZE_BY_IDX(node_id, idx) are valid. If it returns 0, it is an error to use those macros with index “idx”.
- Return
1 if “idx” is a valid register block index, 0 otherwise.
- Parameters
node_id
: node identifieridx
: index to check
-
DT_REG_ADDR_BY_IDX
(node_id, idx)¶ Get the base address of the register block at index “idx”.
- Return
address of the idx-th register block
- Parameters
node_id
: node identifieridx
: index of the register whose address to return
-
DT_REG_SIZE_BY_IDX
(node_id, idx)¶ Get the size of the register block at index “idx”.
This is the size of an individual register block, not the total number of register blocks in the property; use DT_NUM_REGS() for that.
- Return
size of the idx-th register block
- Parameters
node_id
: node identifieridx
: index of the register whose size to return
-
DT_REG_ADDR
(node_id)¶ Get a node’s (only) register block address.
Equivalent to DT_REG_ADDR_BY_IDX(node_id, 0).
- Return
node’s register block address
- Parameters
node_id
: node identifier
-
DT_REG_SIZE
(node_id)¶ Get a node’s (only) register block size.
Equivalent to DT_REG_SIZE_BY_IDX(node_id, 0).
- Return
node’s only register block’s size
- Parameters
node_id
: node identifier
-
DT_REG_ADDR_BY_NAME
(node_id, name)¶ Get a register block’s base address by name.
- Return
address of the register block specified by name
- Parameters
node_id
: node identifiername
: lowercase-and-underscores register specifier name
-
DT_REG_SIZE_BY_NAME
(node_id, name)¶ Get a register block’s size by name.
- Return
size of the register block specified by name
- Parameters
node_id
: node identifiername
: lowercase-and-underscores register specifier name
-
interrupts
property¶
Use these APIs instead of Property access to access the
interrupts
property.
Because this property’s semantics are defined by the devicetree specification, some of these macros can be used even for nodes without matching bindings. This does not apply to macros which take cell names as arguments.
-
group
devicetree-interrupts-prop
Defines
-
DT_NUM_IRQS
(node_id)¶ Get the number of interrupt sources for the node.
Use this instead of DT_PROP_LEN(node_id, interrupts).
- Return
Number of interrupt specifiers in the node’s “interrupts” property.
- Parameters
node_id
: node identifier
-
DT_IRQ_HAS_IDX
(node_id, idx)¶ Is “idx” a valid interrupt index?
If this returns 1, then DT_IRQ_BY_IDX(node_id, idx) is valid. If it returns 0, it is an error to use that macro with this index.
- Return
1 if the idx is valid for the interrupt property 0 otherwise.
- Parameters
node_id
: node identifieridx
: index to check
-
DT_IRQ_HAS_CELL_AT_IDX
(node_id, idx, cell)¶ Does an interrupts property have a named cell specifier at an index? If this returns 1, then DT_IRQ_BY_IDX(node_id, idx, cell) is valid. If it returns 0, it is an error to use that macro.
- Return
1 if the named cell exists in the interrupt specifier at index idx 0 otherwise.
- Parameters
node_id
: node identifieridx
: index to checkcell
: named cell value whose existence to check
-
DT_IRQ_HAS_CELL
(node_id, cell)¶ Equivalent to DT_IRQ_HAS_CELL_AT_IDX(node_id, 0, cell)
- Return
1 if the named cell exists in the interrupt specifier at index 0 0 otherwise.
- Parameters
node_id
: node identifiercell
: named cell value whose existence to check
-
DT_IRQ_HAS_NAME
(node_id, name)¶ Does an interrupts property have a named specifier value at an index? If this returns 1, then DT_IRQ_BY_NAME(node_id, name, cell) is valid. If it returns 0, it is an error to use that macro.
- Return
1 if “name” is a valid named specifier 0 otherwise.
- Parameters
node_id
: node identifiername
: lowercase-and-underscores interrupt specifier name
-
DT_IRQ_BY_IDX
(node_id, idx, cell)¶ Get a value within an interrupt specifier at an index.
It might help to read the argument order as being similar to “node->interrupts[index].cell”.
This can be used to get information about an individual interrupt when a device generates more than one.
Example devicetree fragment:
my-serial: serial@... { interrupts = < 33 0 >, < 34 1 >; };
Assuming the node’s interrupt domain has “#interrupt-cells = <2>;” and the individual cells in each interrupt specifier are named “irq” and “priority” by the node’s binding, here are some examples:
#define SERIAL DT_NODELABEL(my_serial) Example usage Value ------------- ----- DT_IRQ_BY_IDX(SERIAL, 0, irq) 33 DT_IRQ_BY_IDX(SERIAL, 0, priority) 0 DT_IRQ_BY_IDX(SERIAL, 1, irq, 34 DT_IRQ_BY_IDX(SERIAL, 1, priority) 1
- Return
the named value at the specifier given by the index
- Parameters
node_id
: node identifieridx
: logical index into the interrupt specifier arraycell
: cell name specifier
-
DT_IRQ_BY_NAME
(node_id, name, cell)¶ Get a value within an interrupt specifier by name.
It might help to read the argument order as being similar to “node->interrupts.name.cell”.
This can be used to get information about an individual interrupt when a device generates more than one, if the bindings give each interrupt specifier a name.
- Return
the named value at the specifier given by the index
- Parameters
node_id
: node identifiername
: lowercase-and-underscores interrupt specifier namecell
: cell name specifier
-
DT_IRQ
(node_id, cell)¶ Get an interrupt specifier’s value Equivalent to DT_IRQ_BY_IDX(node_id, 0, cell).
- Return
the named value at that index
- Parameters
node_id
: node identifiercell
: cell name specifier
-
DT_IRQN
(node_id)¶ Get a node’s (only) irq number.
Equivalent to DT_IRQ(node_id, irq). This is provided as a convenience for the common case where a node generates exactly one interrupt, and the IRQ number is in a cell named “irq”.
- Return
the interrupt number for the node’s only interrupt
- Parameters
node_id
: node identifier
-
For-each macros¶
There is currently only one “generic” for-each macro,
DT_FOREACH_CHILD()
, which allows iterating over the children of a
devicetree node.
There are special-purpose for-each macros, like
DT_INST_FOREACH_STATUS_OKAY()
, but these require DT_DRV_COMPAT
to
be defined before use.
-
group
devicetree-generic-foreach
Defines
-
DT_FOREACH_CHILD
(node_id, fn)¶ Invokes “fn” for each child of “node_id”.
The macro “fn” must take one parameter, which will be the node identifier of a child node of “node_id”.
Example devicetree fragment:
n: node { child-1 { label = "foo"; }; child-2 { label = "bar"; }; };
Example usage:
#define LABEL_AND_COMMA(node_id) DT_LABEL(node_id), const char *child_labels[] = { DT_FOREACH_CHILD(DT_NODELABEL(n), LABEL_AND_COMMA) };
This expands to:
const char *child_labels[] = { "foo", "bar", };
- Parameters
node_id
: node identifierfn
: macro to invoke
-
Existence checks¶
This section documents miscellaneous macros that can be used to test if a node
exists, how many nodes of a certain type exist, whether a node has certain
properties, etc. Some macros used for special purposes (such as
DT_IRQ_HAS_IDX()
and all macros which require DT_DRV_COMPAT
) are
documented elsewhere on this page.
-
group
devicetree-generic-exist
Defines
-
DT_NODE_EXISTS
(node_id)¶ Does a node identifier refer to a node?
Tests whether a node identifier refers to a node which exists, i.e. is defined in the devicetree.
It doesn’t matter whether or not the node has a matching binding, or what the node’s status value is. This is purely a check of whether the node exists at all.
- Return
1 if the node identifier refers to a node, 0 otherwise.
- Parameters
node_id
: a node identifier
-
DT_NODE_HAS_STATUS
(node_id, status)¶ Does a node identifier refer to a node with a status?
Example uses:
DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), okay) DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), disabled)
Tests whether a node identifier refers to a node which:
exists in the devicetree, and
has a status property matching the second argument (except that either a missing status or an “ok” status in the devicetree is treated as if it were “okay” instead)
- Return
1 if the node has the given status, 0 otherwise.
- Parameters
node_id
: a node identifierstatus
: a status as one of the tokens okay or disabled, not a string
-
DT_HAS_COMPAT_STATUS_OKAY
(compat)¶ Does the devicetree have a status “okay” node with a compatible?
Test for whether the devicetree has any nodes with status “okay” and the given compatible. That is, this returns 1 if and only if there is at least one “node_id” for which both of these expressions return 1:
DT_NODE_HAS_STATUS(node_id, okay) DT_NODE_HAS_COMPAT(node_id, compat)
As usual, both a missing status and an “ok” status are treated as “okay”.
- Return
1 if both of the above conditions are met, 0 otherwise
- Parameters
compat
: lowercase-and-underscores version of a compatible
-
DT_NUM_INST_STATUS_OKAY
(compat)¶ Get the number of instances of a given compatible with status “okay”.
- Return
Number of instances with status “okay”
- Parameters
compat
: lowercase-and-underscores version of a compatible
-
DT_NODE_HAS_COMPAT
(node_id, compat)¶ Does a devicetree node match a compatible?
Example devicetree fragment:
n: node { compatible = "vnd,specific-device", "generic-device"; }
Example usages which evaluate to 1:
DT_NODE_HAS_COMPAT(DT_NODELABEL(n), vnd_specific_device) DT_NODE_HAS_COMPAT(DT_NODELABEL(n), generic_device)
This macro only uses the value of the compatible property. Whether or not a particular compatible has a matching binding has no effect on its value, nor does the node’s status.
- Return
1 if the node’s compatible property contains compat, 0 otherwise.
- Parameters
node_id
: node identifiercompat
: lowercase-and-underscorse compatible value
-
DT_NODE_HAS_COMPAT_STATUS
(node_id, compat, status)¶ Does a devicetree node have a compatible and status?
This is equivalent to:
(DT_NODE_HAS_COMPAT(node_id, compat) && DT_NODE_HAS_STATUS(node_id, status))
- Parameters
node_id
: node identifiercompat
: lowercase-and-underscores compatiblestatus
: okay or disabled as a token, not a string
-
DT_NODE_HAS_PROP
(node_id, prop)¶ Does a devicetree node have a property?
Tests whether a devicetree node has a property defined.
This tests whether the property is defined at all, not whether a boolean property is true or false. To get a boolean property’s truth value, use DT_PROP(node_id, prop) instead.
- Return
1 if the node has the property, 0 otherwise.
- Parameters
node_id
: node identifierprop
: lowercase-and-underscores property name
-
DT_PHA_HAS_CELL_AT_IDX
(node_id, pha, idx, cell)¶ Does a phandle array have a named cell specifier at an index?
If this returns 1, then the phandle-array property “pha” has a cell named “cell” at index “idx”, and therefore DT_PHA_BY_IDX(node_id, pha, idx, cell) is valid. If it returns 0, it’s an error to use DT_PHA_BY_IDX() with the same arguments.
- Return
1 if the named cell exists in the specifier at index idx, 0 otherwise.
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”idx
: index to check within “pha”cell
: lowercase-and-underscores cell name whose existence to check at index “idx”
-
DT_PHA_HAS_CELL
(node_id, pha, cell)¶ Equivalent to DT_PHA_HAS_CELL_AT_IDX(node_id, pha, 0, cell)
- Return
1 if the named cell exists in the specifier at index 0, 0 otherwise.
- Parameters
node_id
: node identifierpha
: lowercase-and-underscores property with type “phandle-array”cell
: lowercase-and-underscores cell name whose existence to check at index “idx”
-
Inter-node dependencies¶
The devicetree.h
API has some support for tracking dependencies between
nodes. Dependency tracking relies on a binary “depends on” relation between
devicetree nodes, which is defined as the transitive closure of the following “directly
depends on” relation:
every non-root node directly depends on its parent node
a node directly depends on any nodes its properties refer to by phandle
a node directly depends on its
interrupt-parent
if it has aninterrupts
property
A dependency ordering of a devicetree is a list of its nodes, where each node
n
appears earlier in the list than any nodes that depend on n
. A node’s
dependency ordinal is then its zero-based index in that list. Thus, for two
distinct devicetree nodes n1
and n2
with dependency ordinals d1
and
d2
, we have:
d1 != d2
if
n1
depends onn2
, thend1 > d2
d1 > d2
does not necessarily imply thatn1
depends onn2
The Zephyr build system chooses a dependency ordering of the final devicetree and assigns a dependency ordinal to each node. Dependency related information can be accessed using the following macros. The exact dependency ordering chosen is an implementation detail, but cyclic dependencies are detected and cause errors, so it’s safe to assume there are none when using these macros.
There are instance number-based conveniences as well; see
DT_INST_DEP_ORD()
and subsequent documentation.
-
group
devicetree-dep-ord
Defines
-
DT_DEP_ORD
(node_id)¶ Get a node’s dependency ordinal.
- Return
the node’s dependency ordinal as an integer literal
- Parameters
node_id
: Node identifier
-
DT_REQUIRES_DEP_ORDS
(node_id)¶ Get a list of dependency ordinals of a node’s direct dependencies.
There is a comma after each ordinal in the expansion, including the last one:
DT_REQUIRES_DEP_ORDS(my_node) // required_ord_1, ..., required_ord_n,
The one case DT_REQUIRES_DEP_ORDS() expands to nothing is when given the root node identifier
DT_ROOT
as argument. The root has no direct dependencies; every other node at least depends on its parent.- Return
a list of dependency ordinals, with each ordinal followed by a comma (
,
), or an empty expansion- Parameters
node_id
: Node identifier
-
DT_SUPPORTS_DEP_ORDS
(node_id)¶ Get a list of dependency ordinals of what depends directly on a node.
There is a comma after each ordinal in the expansion, including the last one:
DT_SUPPORTS_DEP_ORDS(my_node) // supported_ord_1, ..., supported_ord_n,
DT_SUPPORTS_DEP_ORDS() may expand to nothing. This happens when
node_id
refers to a leaf node that nothing else depends on.- Return
a list of dependency ordinals, with each ordinal followed by a comma (
,
), or an empty expansion- Parameters
node_id
: Node identifier
-
DT_INST_DEP_ORD
(inst)¶ Get a DT_DRV_COMPAT instance’s dependency ordinal.
Equivalent to DT_DEP_ORD(DT_DRV_INST(inst)).
- Return
The instance’s dependency ordinal
- Parameters
inst
: instance number
-
DT_INST_REQUIRES_DEP_ORDS
(inst)¶ Get a list of dependency ordinals of a DT_DRV_COMPAT instance’s direct dependencies.
Equivalent to DT_REQUIRES_DEP_ORDS(DT_DRV_INST(inst)).
- Return
a list of dependency ordinals for the nodes the instance depends on directly
- Parameters
inst
: instance number
-
DT_INST_SUPPORTS_DEP_ORDS
(inst)¶ Get a list of dependency ordinals of what depends directly on a DT_DRV_COMPAT instance.
Equivalent to DT_SUPPORTS_DEP_ORDS(DT_DRV_INST(inst)).
- Return
a list of node identifiers for the nodes that depend directly on the instance
- Parameters
inst
: instance number
-
Bus helpers¶
Zephyr’s devicetree bindings language supports a bus:
key which allows
bindings to declare that nodes with a given compatible describe system buses.
In this case, child nodes are considered to be on a bus of the given type, and
the following APIs may be used.
-
group
devicetree-generic-bus
Defines
-
DT_BUS
(node_id)¶ Node’s bus controller.
Get the node identifier of the node’s bus controller. This can be used with DT_PROP() to get properties of the bus controller.
It is an error to use this with nodes which do not have bus controllers.
Example devicetree fragment:
i2c@deadbeef { label = "I2C_CTLR"; status = "okay"; clock-frequency = < 100000 >; i2c_device: accelerometer@12 { ... }; };
Example usage:
DT_PROP(DT_BUS(DT_NODELABEL(i2c_device)), clock_frequency) // 100000
- Return
a node identifier for the node’s bus controller
- Parameters
node_id
: node identifier
-
DT_BUS_LABEL
(node_id)¶ Node’s bus controller’s label property.
- Return
the label property of the node’s bus controller DT_BUS(node)
- Parameters
node_id
: node identifier
-
DT_ON_BUS
(node_id, bus)¶ Is a node on a bus of a given type?
Example devicetree overlay:
&i2c0 { temp: temperature-sensor@76 { compatible = "vnd,some-sensor"; reg = <0x76>; }; };
Example usage, assuming “i2c0” is an I2C bus controller node, and therefore “temp” is on an I2C bus:
DT_ON_BUS(DT_NODELABEL(temp), i2c) // 1 DT_ON_BUS(DT_NODELABEL(temp), spi) // 0
- Return
1 if the node is on a bus of the given type, 0 otherwise
- Parameters
node_id
: node identifierbus
: lowercase-and-underscores bus type as a C token (i.e. without quotes)
-
Instance-based APIs¶
These are recommended for use within device drivers. To use them, define
DT_DRV_COMPAT
to the lowercase-and-underscores compatible the device driver
implements support for. Here is an example devicetree fragment:
serial@40001000 {
compatible = "vnd,serial";
status = "okay";
current-speed = <115200>;
};
Example usage, assuming serial@40001000 is the only enabled node with compatible “vnd,serial”:
#define DT_DRV_COMPAT vnd_serial
DT_DRV_INST(0) // node identifier for serial@40001000
DT_INST_PROP(0, current_speed) // 115200
Warning
Be careful making assumptions about instance numbers. See DT_INST()
for the API guarantees.
As shown above, the DT_INST_*
APIs are conveniences for addressing nodes by
instance number. They are almost all defined in terms of one of the
Generic APIs. The equivalent generic API can be found by
removing INST_
from the macro name. For example, DT_INST_PROP(inst,
prop)
is equivalent to DT_PROP(DT_DRV_INST(inst), prop)
. Similarly,
DT_INST_REG_ADDR(inst)
is equivalent to DT_REG_ADDR(DT_DRV_INST(inst))
,
and so on. There are some exceptions: DT_ANY_INST_ON_BUS_STATUS_OKAY()
and DT_INST_FOREACH_STATUS_OKAY()
are special-purpose helpers without
straightforward generic equivalents.
Since DT_DRV_INST()
requires DT_DRV_COMPAT
to be defined, it’s an error
to use any of these without that macro defined.
Note that there are also helpers available for specific hardware; these are documented in Hardware specific APIs.
-
group
devicetree-inst
Defines
-
DT_DRV_INST
(inst)¶ Node identifier for an instance of a DT_DRV_COMPAT compatible.
- Return
a node identifier for the node with DT_DRV_COMPAT compatible and instance number “inst”
- Parameters
inst
: instance number
-
DT_INST_FOREACH_CHILD
(inst, fn)¶ Call “fn” on all child nodes of DT_DRV_INST(inst).
The macro “fn” should take one argument, which is the node identifier for the child node.
- See
- Parameters
inst
: instance numberfn
: macro to invoke on each child node identifier
-
DT_INST_PROP
(inst, prop)¶ Get a DT_DRV_COMPAT instance property.
- Return
a representation of the property’s value
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property name
-
DT_INST_PROP_LEN
(inst, prop)¶ Get a DT_DRV_COMPAT property length.
- Return
logical length of the property
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property name
-
DT_INST_PROP_HAS_IDX
(inst, prop, idx)¶ Is index “idx” valid for an array type property on a DT_DRV_COMPAT instance?
- Return
1 if “idx” is a valid index into the given property, 0 otherwise.
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property nameidx
: index to check
-
DT_INST_PROP_BY_IDX
(inst, prop, idx)¶ Get a DT_DRV_COMPAT element value in an array property.
- Return
a representation of the idx-th element of the property
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property nameidx
: the index to get
-
DT_INST_PROP_OR
(inst, prop, default_value)¶ Like DT_INST_PROP(), but with a fallback to default_value.
- Return
DT_INST_PROP(inst, prop) or default_value
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property namedefault_value
: a fallback value to expand to
-
DT_INST_LABEL
(inst)¶ Get a DT_DRV_COMPAT instance’s “label” property.
- Return
instance’s label property value
- Parameters
inst
: instance number
-
DT_INST_PROP_BY_PHANDLE
(inst, ph, prop)¶ Get a DT_DRV_COMPAT instance’s property value from a phandle’s node.
- Return
the value of “prop” as described in the DT_PROP() documentation
- Parameters
inst
: instance numberph
: lowercase-and-underscores property of “inst” with type “phandle”prop
: lowercase-and-underscores property of the phandle’s node
-
DT_INST_PROP_BY_PHANDLE_IDX
(inst, phs, idx, prop)¶ Get a DT_DRV_COMPAT instance’s property value from a phandle in a property.
- Return
the value of “prop” as described in the DT_PROP() documentation
- Parameters
inst
: instance numberphs
: lowercase-and-underscores property with type “phandle”, “phandles”, or “phandle-array”idx
: logical index into “phs”, which must be zero if “phs” has type “phandle”prop
: lowercase-and-underscores property of the phandle’s node
-
DT_INST_PHA_BY_IDX
(inst, pha, idx, cell)¶ Get a DT_DRV_COMPAT instance’s phandle-array specifier value at an index.
- Return
the value of the cell inside the specifier at index “idx”
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”idx
: logical index into the property “pha”cell
: binding’s cell name within the specifier at index “idx”
-
DT_INST_PHA_BY_IDX_OR
(inst, pha, idx, cell, default_value)¶ Like DT_INST_PHA_BY_IDX(), but with a fallback to default_value.
- Return
DT_INST_PHA_BY_IDX(inst, pha, idx, cell) or default_value
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”idx
: logical index into the property “pha”cell
: binding’s cell name within the specifier at index “idx”default_value
: a fallback value to expand to
-
DT_INST_PHA
(inst, pha, cell)¶ Get a DT_DRV_COMPAT instance’s phandle-array specifier value Equivalent to DT_INST_PHA_BY_IDX(inst, pha, 0, cell)
- Return
the cell value
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”cell
: binding’s cell name for the specifier at “pha” index 0
-
DT_INST_PHA_OR
(inst, pha, cell, default_value)¶ Like DT_INST_PHA(), but with a fallback to default_value.
- Return
DT_INST_PHA(inst, pha, cell) or default_value
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”cell
: binding’s cell name for the specifier at “pha” index 0default_value
: a fallback value to expand to
-
DT_INST_PHA_BY_NAME
(inst, pha, name, cell)¶ Get a DT_DRV_COMPAT instance’s value within a phandle-array specifier by name.
- Return
the cell value
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”name
: lowercase-and-underscores name of a specifier in “pha”cell
: binding’s cell name for the named specifier
-
DT_INST_PHA_BY_NAME_OR
(inst, pha, name, cell, default_value)¶ Like DT_INST_PHA_BY_NAME(), but with a fallback to default_value.
- Return
DT_INST_PHA_BY_NAME(inst, pha, name, cell) or default_value
- Parameters
inst
: instance numberpha
: 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 specifierdefault_value
: a fallback value to expand to
-
DT_INST_PHANDLE_BY_NAME
(inst, pha, name)¶ Get a DT_DRV_COMPAT instance’s phandle node identifier from a phandle array by name.
- Return
node identifier for the phandle at the element named “name”
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”name
: lowercase-and-underscores name of an element in “pha”
-
DT_INST_PHANDLE_BY_IDX
(inst, prop, idx)¶ Get a DT_DRV_COMPAT instance’s node identifier for a phandle in a property.
- Return
a node identifier for the phandle at index “idx” in “prop”
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property name in “inst” with type “phandle”, “phandles” or “phandle-array”idx
: index into “prop”
-
DT_INST_PHANDLE
(inst, prop)¶ Get a DT_DRV_COMPAT instance’s node identifier for a phandle property’s value.
- Return
a node identifier for the node pointed to by “ph”
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property of “inst” with type “phandle”
-
DT_INST_REG_HAS_IDX
(inst, idx)¶ is “idx” a valid register block index on a DT_DRV_COMPAT instance?
- Return
1 if “idx” is a valid register block index, 0 otherwise.
- Parameters
inst
: instance numberidx
: index to check
-
DT_INST_REG_ADDR_BY_IDX
(inst, idx)¶ Get a DT_DRV_COMPAT instance’s idx-th register block’s address.
- Return
address of the instance’s idx-th register block
- Parameters
inst
: instance numberidx
: index of the register whose address to return
-
DT_INST_REG_SIZE_BY_IDX
(inst, idx)¶ Get a DT_DRV_COMPAT instance’s idx-th register block’s size.
- Return
size of the instance’s idx-th register block
- Parameters
inst
: instance numberidx
: index of the register whose size to return
-
DT_INST_REG_ADDR_BY_NAME
(inst, name)¶ Get a DT_DRV_COMPAT’s register block address by name.
- Return
address of the register block with the given name
- Parameters
inst
: instance numbername
: lowercase-and-underscores register specifier name
-
DT_INST_REG_SIZE_BY_NAME
(inst, name)¶ Get a DT_DRV_COMPAT’s register block size by name.
- Return
size of the register block with the given name
- Parameters
inst
: instance numbername
: lowercase-and-underscores register specifier name
-
DT_INST_REG_ADDR
(inst)¶ Get a DT_DRV_COMPAT’s (only) register block address.
- Return
instance’s register block address
- Parameters
inst
: instance number
-
DT_INST_REG_SIZE
(inst)¶ Get a DT_DRV_COMPAT’s (only) register block size.
- Return
instance’s register block size
- Parameters
inst
: instance number
-
DT_INST_IRQ_BY_IDX
(inst, idx, cell)¶ Get a DT_DRV_COMPAT interrupt specifier value at an index.
- Return
the named value at the specifier given by the index
- Parameters
inst
: instance numberidx
: logical index into the interrupt specifier arraycell
: cell name specifier
-
DT_INST_IRQ_BY_NAME
(inst, name, cell)¶ Get a DT_DRV_COMPAT interrupt specifier value by name.
- Return
the named value at the specifier given by the index
- Parameters
inst
: instance numbername
: lowercase-and-underscores interrupt specifier namecell
: cell name specifier
-
DT_INST_IRQ
(inst, cell)¶ Get a DT_DRV_COMPAT interrupt specifier’s value.
- Return
the named value at that index
- Parameters
inst
: instance numbercell
: cell name specifier
-
DT_INST_IRQN
(inst)¶ Get a DT_DRV_COMPAT’s (only) irq number.
- Return
the interrupt number for the node’s only interrupt
- Parameters
inst
: instance number
-
DT_INST_BUS_LABEL
(inst)¶ Get a DT_DRV_COMPAT’s bus node’s label property.
- Return
the label property of the instance’s bus controller
- Parameters
inst
: instance number
-
DT_INST_ON_BUS
(inst, bus)¶ Test if a DT_DRV_COMPAT’s bus type is a given type.
- Return
1 if the given instance is on a bus of the given type, 0 otherwise
- Parameters
inst
: instance numberbus
: a binding’s bus type as a C token, lowercased and without quotes
-
DT_ANY_INST_ON_BUS_STATUS_OKAY
(bus)¶ Test if any DT_DRV_COMPAT node is on a bus of a given type and has status okay.
This is a special-purpose macro which can be useful when writing drivers for devices which can appear on multiple buses. One example is a sensor device which may be wired on an I2C or SPI bus.
Example devicetree overlay:
&i2c0 { temp: temperature-sensor@76 { compatible = "vnd,some-sensor"; reg = <0x76>; }; };
Example usage, assuming “i2c0” is an I2C bus controller node, and therefore “temp” is on an I2C bus:
#define DT_DRV_COMPAT vnd_some_sensor DT_ANY_INST_ON_BUS_STATUS_OKAY(i2c) // 1
- Return
1 if any enabled node with that compatible is on that bus type, 0 otherwise
- Parameters
bus
: a binding’s bus type as a C token, lowercased and without quotes
-
DT_INST_FOREACH_STATUS_OKAY
(fn)¶ Call “fn” on all nodes with compatible DT_DRV_COMPAT and status “okay”.
This macro calls “fn(inst)” on each “inst” number that refers to a node with status “okay”. Whitespace is added between invocations.
Example devicetree fragment:
a { compatible = "vnd,device"; status = "okay"; label = "DEV_A"; }; b { compatible = "vnd,device"; status = "okay"; label = "DEV_B"; }; c { compatible = "vnd,device"; status = "disabled"; label = "DEV_C"; };
Example usage:
#define DT_DRV_COMPAT vnd_device #define MY_FN(inst) DT_INST_LABEL(inst), DT_INST_FOREACH_STATUS_OKAY(MY_FN)
This expands to:
MY_FN(0) MY_FN(1)
and from there, to either this:
"DEV_A", "DEV_B",
or this:
"DEV_B", "DEV_A",
No guarantees are made about the order that a and b appear in the expansion.
Note that “fn” is responsible for adding commas, semicolons, or other separators or terminators.
Device drivers should use this macro whenever possible to instantiate a struct device for each enabled node in the devicetree of the driver’s compatible DT_DRV_COMPAT.
- Parameters
fn
: Macro to call for each enabled node. Must accept an instance number as its only parameter.
-
DT_INST_NODE_HAS_PROP
(inst, prop)¶ Does a DT_DRV_COMPAT instance have a property?
- Return
1 if the instance has the property, 0 otherwise.
- Parameters
inst
: instance numberprop
: lowercase-and-underscores property name
-
DT_INST_PHA_HAS_CELL_AT_IDX
(inst, pha, idx, cell)¶ Does a phandle array have a named cell specifier at an index for a DT_DRV_COMPAT instance?
- Return
1 if the named cell exists in the specifier at index idx, 0 otherwise.
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”idx
: index to checkcell
: named cell value whose existence to check
-
DT_INST_PHA_HAS_CELL
(inst, pha, cell)¶ Does a phandle array have a named cell specifier at index 0 for a DT_DRV_COMPAT instance?
- Return
1 if the named cell exists in the specifier at index 0, 0 otherwise.
- Parameters
inst
: instance numberpha
: lowercase-and-underscores property with type “phandle-array”cell
: named cell value whose existence to check
-
DT_INST_IRQ_HAS_IDX
(inst, idx)¶ is index valid for interrupt property on a DT_DRV_COMPAT instance?
- Return
1 if the idx is valid for the interrupt property 0 otherwise.
- Parameters
inst
: instance numberidx
: logical index into the interrupt specifier array
-
DT_INST_IRQ_HAS_CELL_AT_IDX
(inst, idx, cell)¶ Does a DT_DRV_COMPAT instance have an interrupt named cell specifier?
- Return
1 if the named cell exists in the interrupt specifier at index idx 0 otherwise.
- Parameters
inst
: instance numberidx
: index to checkcell
: named cell value whose existence to check
-
DT_INST_IRQ_HAS_CELL
(inst, cell)¶ Does a DT_DRV_COMPAT instance have an interrupt value?
- Return
1 if the named cell exists in the interrupt specifier at index 0 0 otherwise.
- Parameters
inst
: instance numbercell
: named cell value whose existence to check
-
DT_INST_IRQ_HAS_NAME
(inst, name)¶ Does a DT_DRV_COMPAT instance have an interrupt value?
- Return
1 if “name” is a valid named specifier
- Parameters
inst
: instance numbername
: lowercase-and-underscores interrupt specifier name
-
Hardware specific APIs¶
The following APIs can also be used by including <devicetree.h>
;
no additional include is needed.
Clocks¶
These conveniences may be used for nodes which describe clock sources, and properties related to them.
-
group
devicetree-clocks
Defines
-
DT_CLOCKS_LABEL_BY_IDX
(node_id, idx)¶ Get a label property from the node referenced by a pwms property at an index.
It’s an error if the clock controller node referenced by the phandle in node_id’s clocks property at index “idx” has no label property.
Example devicetree fragment:
clk1: clock-controller@... { label = "CLK_1"; }; clk2: clock-controller@... { label = "CLK_2"; }; n: node { clocks = <&clk1 10 20>, <&clk2 30 40>; };
Example usage:
DT_CLOCKS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "CLK_2"
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a clocks propertyidx
: logical index into clocks property
-
DT_CLOCKS_LABEL_BY_NAME
(node_id, name)¶ Get a label property from a clocks property by name.
It’s an error if the clock controller node referenced by the phandle in node_id’s clocks property at the element named “name” has no label property.
Example devicetree fragment:
clk1: clock-controller@... { label = "CLK_1"; }; clk2: clock-controller@... { label = "CLK_2"; }; n: node { clocks = <&clk1 10 20>, <&clk2 30 40>; clock-names = "alpha", "beta"; };
Example usage:
DT_CLOCKS_LABEL_BY_NAME(DT_NODELABEL(n), beta) // "CLK_2"
- Return
the label property of the node referenced at the named element
- See
- Parameters
node_id
: node identifier for a node with a clocks propertyname
: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property
-
DT_CLOCKS_LABEL
(node_id)¶ Equivalent to DT_CLOCKS_LABEL_BY_IDX(node_id, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
node_id
: node identifier for a node with a clocks property
-
DT_CLOCKS_CELL_BY_IDX
(node_id, idx, cell)¶ Get a clock specifier’s cell value at an index.
Example devicetree fragment:
clk1: clock-controller@... { compatible = "vnd,clock"; #clock-cells = < 2 >; }; n: node { clocks = < &clk1 10 20 >, < &clk1 30 40 >; };
Bindings fragment for the vnd,clock compatible:
clock-cells: - bus - bits
Example usage:
DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 0, bus) // 10 DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 1, bits) // 40
- Return
the cell value at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a clocks propertyidx
: logical index into clocks propertycell
: lowercase-and-underscores cell name
-
DT_CLOCKS_CELL_BY_NAME
(node_id, name, cell)¶ Get a clock specifier’s cell value by name.
Example devicetree fragment:
clk1: clock-controller@... { compatible = "vnd,clock"; #clock-cells = < 2 >; }; n: node { clocks = < &clk1 10 20 >, < &clk1 30 40 >; clock-names = "alpha", "beta"; };
Bindings fragment for the vnd,clock compatible:
clock-cells: - bus - bits
Example usage:
DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), alpha, bus) // 10 DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), beta, bits) // 40
- Return
the cell value in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with a clocks propertyname
: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names propertycell
: lowercase-and-underscores cell name
-
DT_CLOCKS_CELL
(node_id, cell)¶ Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)
- Return
the cell value at index 0
- See
- Parameters
node_id
: node identifier for a node with a clocks propertycell
: lowercase-and-underscores cell name
-
DT_INST_CLOCKS_LABEL_BY_IDX
(inst, idx)¶ Get a label property from a DT_DRV_COMPAT instance’s clocks property at an index.
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into clocks property
-
DT_INST_CLOCKS_LABEL_BY_NAME
(inst, name)¶ Get a label property from a DT_DRV_COMPAT instance’s clocks property by name.
- Return
the label property of the node referenced at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names property
-
DT_INST_CLOCKS_LABEL
(inst)¶ Equivalent to DT_INST_CLOCKS_LABEL_BY_IDX(inst, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_CLOCKS_CELL_BY_IDX
(inst, idx, cell)¶ Get a DT_DRV_COMPAT instance’s clock specifier’s cell value at an index.
- Return
the cell value at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into clocks propertycell
: lowercase-and-underscores cell name
-
DT_INST_CLOCKS_CELL_BY_NAME
(inst, name, cell)¶ Get a DT_DRV_COMPAT instance’s clock specifier’s cell value by name.
- Return
the cell value in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a clocks element as defined by the node’s clock-names propertycell
: lowercase-and-underscores cell name
-
DT_INST_CLOCKS_CELL
(inst, cell)¶ Equivalent to DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)
- Return
the value of the cell inside the specifier at index 0
- Parameters
inst
: DT_DRV_COMPAT instance numbercell
: lowercase-and-underscores cell name
-
DMA¶
These conveniences may be used for nodes which describe direct memory access controllers or channels, and properties related to them.
-
group
devicetree-dmas
Defines
-
DT_DMAS_LABEL_BY_IDX
(node_id, idx)¶ Get a label property from the node referenced by a dmas property at an index.
It’s an error if the DMA controller node referenced by the phandle in node_id’s dmas property at index “idx” has no label property.
Example devicetree fragment:
dma1: dma@... { label = "DMA_1"; }; dma2: dma@... { label = "DMA_2"; }; n: node { dmas = <&dma1 1 2 0x400 0x3>, <&dma2 6 3 0x404 0x5>; };
Example usage:
DT_DMAS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "DMA_2"
- Return
the label property of the node referenced at index “idx”
- Parameters
node_id
: node identifier for a node with a dmas propertyidx
: logical index into dmas property
-
DT_INST_DMAS_LABEL_BY_IDX
(inst, idx)¶ Get a label property from a DT_DRV_COMPAT instance’s dmas property at an index.
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into dmas property
-
DT_DMAS_LABEL_BY_NAME
(node_id, name)¶ Get a label property from a dmas property by name.
It’s an error if the DMA controller node referenced by the phandle in node_id’s dmas property at the element named “name” has no label property.
Example devicetree fragment:
dma1: dma@... { label = "DMA_1"; }; dma2: dma@... { label = "DMA_2"; }; n: node { dmas = <&dma1 1 2 0x400 0x3>, <&dma2 6 3 0x404 0x5>; dma-names = "tx", "rx"; };
Example usage:
DT_DMAS_LABEL_BY_NAME(DT_NODELABEL(n), rx) // "DMA_2"
- Return
the label property of the node referenced at the named element
- Parameters
node_id
: node identifier for a node with a dmas propertyname
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property
-
DT_INST_DMAS_LABEL_BY_NAME
(inst, name)¶ Get a label property from a DT_DRV_COMPAT instance’s dmas property by name.
- Return
the label property of the node referenced at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property
-
DT_DMAS_CELL_BY_IDX
(node_id, idx, cell)¶ Get a DMA specifier’s cell value at an index.
Example devicetree fragment:
dma1: dma@... { compatible = "vnd,dma"; #dma-cells = <2>; }; dma2: dma@... { compatible = "vnd,dma"; #dma-cells = <2>; }; n: node { dmas = <&dma1 1 0x400>, <&dma2 6 0x404>; };
Bindings fragment for the vnd,dma compatible:
dma-cells: - channel - config
Example usage:
DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, channel) // 1 DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, channel) // 6 DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 0, config) // 0x400 DT_DMAS_CELL_BY_IDX(DT_NODELABEL(n), 1, config) // 0x404
- Return
the cell value at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a dmas propertyidx
: logical index into dmas propertycell
: lowercase-and-underscores cell name
-
DT_INST_DMAS_CELL_BY_IDX
(inst, idx, cell)¶ Get a DT_DRV_COMPAT instance’s DMA specifier’s cell value at an index.
- Return
the cell value at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into dmas propertycell
: lowercase-and-underscores cell name
-
DT_DMAS_CELL_BY_NAME
(node_id, name, cell)¶ Get a DMA specifier’s cell value by name.
Example devicetree fragment:
dma1: dma@... { compatible = "vnd,dma"; #dma-cells = <2>; }; dma2: dma@... { compatible = "vnd,dma"; #dma-cells = <2>; }; n: node { dmas = <&dma1 1 0x400>, <&dma2 6 0x404>; dma-names = "tx", "rx"; };
Bindings fragment for the vnd,dma compatible:
dma-cells: - channel - config
Example usage:
DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, channel) // 1 DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, channel) // 6 DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), tx, config) // 0x400 DT_DMAS_CELL_BY_NAME(DT_NODELABEL(n), rx, config) // 0x404
- Return
the cell value in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with a dmas propertyname
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names propertycell
: lowercase-and-underscores cell name
-
DT_INST_DMAS_CELL_BY_NAME
(inst, name, cell)¶ Get a DT_DRV_COMPAT instance’s DMA specifier’s cell value by name.
- Return
the cell value in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names propertycell
: lowercase-and-underscores cell name
-
DT_DMAS_HAS_IDX
(node_id, idx)¶ Is index “idx” valid for a dmas property?
- Return
1 if the “dmas” property has index “idx”, 0 otherwise
- Parameters
node_id
: node identifier for a node with a dmas propertyidx
: logical index into dmas property
-
DT_INST_DMAS_HAS_IDX
(inst, idx)¶ Is index “idx” valid for a DT_DRV_COMPAT instance’s dmas property?
- Return
1 if the “dmas” property has a specifier at index “idx”, 0 otherwise
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into dmas property
-
DT_DMAS_HAS_NAME
(node_id, name)¶ Does a dmas property have a named element?
- Return
1 if the dmas property has the named element, 0 otherwise
- Parameters
node_id
: node identifier for a node with a dmas propertyname
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property
-
DT_INST_DMAS_HAS_NAME
(inst, name)¶ Does a DT_DRV_COMPAT instance’s dmas property have a named element?
- Return
1 if the dmas property has the named element, 0 otherwise
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a dmas element as defined by the node’s dma-names property
-
Fixed flash partitions¶
These conveniences may be used for the special-purpose fixed-partitions
compatible used to encode information about flash memory partitions in the
device tree. See dts/bindings/mtd/partition.yaml for this
compatible’s binding.
-
group
devicetree-fixed-partition
Defines
-
DT_NODE_BY_FIXED_PARTITION_LABEL
(label)¶ Get a node identifier for a fixed partition with a given label property.
Example devicetree fragment:
flash@... { partitions { compatible = "fixed-partitions"; boot_partition: partition@0 { label = "mcuboot"; }; slot0_partition: partition@c000 { label = "image-0"; }; ... }; };
Example usage:
DT_NODE_BY_FIXED_PARTITION_LABEL(mcuboot) // node identifier for boot_partition DT_NODE_BY_FIXED_PARTITION_LABEL(image_0) // node identifier for slot0_partition
- Return
a node identifier for the partition with that label property
- Parameters
label
: lowercase-and-underscores label property value
-
DT_HAS_FIXED_PARTITION_LABEL
(label)¶ Test if a fixed partition with a given label property exists.
- Return
1 if any “fixed-partitions” child node has the given label, 0 otherwise.
- Parameters
label
: lowercase-and-underscores label property value
-
DT_FIXED_PARTITION_ID
(node_id)¶ Get a numeric identifier for a fixed partition.
- Return
the partition’s ID, a unique zero-based index number
- Parameters
node_id
: node identifier for a fixed-partitions child node
-
GPIO¶
These conveniences may be used for nodes which describe GPIO controllers/pins, and properties related to them.
-
group
devicetree-gpio
Defines
-
DT_GPIO_LABEL_BY_IDX
(node_id, gpio_pha, idx)¶ Get a label property from a gpio phandle-array property at an index.
It’s an error if the GPIO controller node referenced by the phandle in node_id’s “gpio_pha” property at index “idx” has no label property.
Example devicetree fragment:
gpio1: gpio@... { label = "GPIO_1"; }; gpio2: gpio@... { label = "GPIO_2"; }; n: node { gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 30 GPIO_ACTIVE_HIGH>; };
Example usage:
DT_GPIO_LABEL_BY_IDX(DT_NODELABEL(n), gpios, 1) // "GPIO_2"
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_GPIO_LABEL
(node_id, gpio_pha)¶ Equivalent to DT_GPIO_LABEL_BY_IDX(node_id, gpio_pha, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
DT_GPIO_PIN_BY_IDX
(node_id, gpio_pha, idx)¶ Get a GPIO specifier’s pin cell at an index.
This macro only works for GPIO specifiers with cells named “pin”. Refer to the node’s binding to check if necessary.
Example devicetree fragment:
gpio1: gpio@... { compatible = "vnd,gpio"; #gpio-cells = <2>; }; gpio2: gpio@... { compatible = "vnd,gpio"; #gpio-cells = <2>; }; n: node { gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 30 GPIO_ACTIVE_HIGH>; };
Bindings fragment for the vnd,gpio compatible:
gpio-cells: - pin - flags
Example usage:
DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 0) // 10 DT_GPIO_PIN_BY_IDX(DT_NODELABEL(n), gpios, 1) // 30
- Return
the pin cell value at index “idx”
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_GPIO_PIN
(node_id, gpio_pha)¶ Equivalent to DT_GPIO_PIN_BY_IDX(node_id, gpio_pha, 0)
- Return
the pin cell value at index 0
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
DT_GPIO_FLAGS_BY_IDX
(node_id, gpio_pha, idx)¶ Get a GPIO specifier’s flags cell at an index.
This macro expects GPIO specifiers with cells named “flags”. If there is no “flags” cell in the GPIO specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.
Example devicetree fragment:
gpio1: gpio@... { compatible = "vnd,gpio"; #gpio-cells = <2>; }; gpio2: gpio@... { compatible = "vnd,gpio"; #gpio-cells = <2>; }; n: node { gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 30 GPIO_ACTIVE_HIGH>; };
Bindings fragment for the vnd,gpio compatible:
gpio-cells: - pin - flags
Example usage:
DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 0) // GPIO_ACTIVE_LOW DT_GPIO_FLAGS_BY_IDX(DT_NODELABEL(n), gpios, 1) // GPIO_ACTIVE_HIGH
- Return
the flags cell value at index “idx”, or zero if there is none
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_GPIO_FLAGS
(node_id, gpio_pha)¶ Equivalent to DT_GPIO_FLAGS_BY_IDX(node_id, gpio_pha, 0)
- Return
the flags cell value at index 0, or zero if there is none
- See
- Parameters
node_id
: node identifiergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
DT_INST_GPIO_LABEL_BY_IDX
(inst, gpio_pha, idx)¶ Get a label property from a DT_DRV_COMPAT instance’s GPIO property at an index.
- Return
the label property of the node referenced at index “idx”
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_INST_GPIO_LABEL
(inst, gpio_pha)¶ Equivalent to DT_INST_GPIO_LABEL_BY_IDX(inst, gpio_pha, 0)
- Return
the label property of the node referenced at index 0
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
DT_INST_GPIO_PIN_BY_IDX
(inst, gpio_pha, idx)¶ Get a DT_DRV_COMPAT instance’s GPIO specifier’s pin cell value at an index.
- Return
the pin cell value at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_INST_GPIO_PIN
(inst, gpio_pha)¶ Equivalent to DT_INST_GPIO_PIN_BY_IDX(inst, gpio_pha, 0)
- Return
the pin cell value at index 0
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
DT_INST_GPIO_FLAGS_BY_IDX
(inst, gpio_pha, idx)¶ Get a DT_DRV_COMPAT instance’s GPIO specifier’s flags cell at an index.
- Return
the flags cell value at index “idx”, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”idx
: logical index into “gpio_pha”
-
DT_INST_GPIO_FLAGS
(inst, gpio_pha)¶ Equivalent to DT_INST_GPIO_FLAGS_BY_IDX(inst, gpio_pha, 0)
- Return
the flags cell value at index 0, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbergpio_pha
: lowercase-and-underscores GPIO property with type “phandle-array”
-
IO channels¶
These are commonly used by device drivers which need to use IO channels (e.g. ADC or DAC channels) for conversion.
-
group
devicetree-io-channels
Defines
-
DT_IO_CHANNELS_LABEL_BY_IDX
(node_id, idx)¶ Get a label property from the node referenced by an io-channels property at an index.
It’s an error if the node referenced by the phandle in node_id’s io-channels property at index “idx” has no label property.
Example devicetree fragment:
adc1: adc@... { label = "ADC_1"; }; adc2: adc@... { label = "ADC_2"; }; n: node { io-channels = <&adc1 10>, <&adc2 20>; };
Example usage:
DT_IO_CHANNELS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "ADC_2"
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
node_id
: node identifier for a node with an io-channels propertyidx
: logical index into io-channels property
-
DT_IO_CHANNELS_LABEL_BY_NAME
(node_id, name)¶ Get a label property from an io-channels property by name.
It’s an error if the node referenced by the phandle in node_id’s io-channels property at the element named “name” has no label property.
Example devicetree fragment:
adc1: adc@... { label = "ADC_1"; }; adc2: adc@... { label = "ADC_2"; }; n: node { io-channels = <&adc1 10>, <&adc2 20>; io-channel-names = "SENSOR", "BANDGAP"; };
Example usage:
DT_IO_CHANNELS_LABEL_BY_NAME(DT_NODELABEL(n), bandgap) // "ADC_2"
- Return
the label property of the node referenced at the named element
- See
- Parameters
node_id
: node identifier for a node with an io-channels propertyname
: lowercase-and-underscores name of an io-channels element as defined by the node’s io-channel-names property
-
DT_IO_CHANNELS_LABEL
(node_id)¶ Equivalent to DT_IO_CHANNELS_LABEL_BY_IDX(node_id, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
node_id
: node identifier for a node with an io-channels property
-
DT_INST_IO_CHANNELS_LABEL_BY_IDX
(inst, idx)¶ Get a label property from a DT_DRV_COMPAT instance’s io-channels property at an index.
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into io-channels property
-
DT_INST_IO_CHANNELS_LABEL_BY_NAME
(inst, name)¶ Get a label property from a DT_DRV_COMPAT instance’s io-channels property by name.
- Return
the label property of the node referenced at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of an io-channels element as defined by the instance’s io-channel-names property
-
DT_INST_IO_CHANNELS_LABEL
(inst)¶ Equivalent to DT_INST_IO_CHANNELS_LABEL_BY_IDX(inst, 0)
- Return
the label property of the node referenced at index 0
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_IO_CHANNELS_INPUT_BY_IDX
(node_id, idx)¶ Get an io-channels specifier input cell at an index.
This macro only works for io-channels specifiers with cells named “input”. Refer to the node’s binding to check if necessary.
Example devicetree fragment:
adc1: adc@... { compatible = "vnd,adc"; #io-channel-cells = <1>; }; adc2: adc@... { compatible = "vnd,adc"; #io-channel-cells = <1>; }; n: node { io-channels = <&adc1 10>, <&adc2 20>; };
Bindings fragment for the vnd,adc compatible:
io-channel-cells:
input
Example usage:
DT_IO_CHANNELS_INPUT_BY_IDX(DT_NODELABEL(n), 0) // 10 DT_IO_CHANNELS_INPUT_BY_IDX(DT_NODELABEL(n), 1) // 20
- Return
the input cell in the specifier at index “idx”
- See
- Parameters
node_id
: node identifier for a node with an io-channels propertyidx
: logical index into io-channels property
-
DT_IO_CHANNELS_INPUT_BY_NAME
(node_id, name)¶ Get an io-channels specifier input cell by name.
This macro only works for io-channels specifiers with cells named “input”. Refer to the node’s binding to check if necessary.
Example devicetree fragment:
adc1: adc@... { compatible = "vnd,adc"; #io-channel-cells = <1>; }; adc2: adc@... { compatible = "vnd,adc"; #io-channel-cells = <1>; }; n: node { io-channels = <&adc1 10>, <&adc2 20>; io-channel-names = "SENSOR", "BANDGAP"; };
Bindings fragment for the vnd,adc compatible:
io-channel-cells:
input
Example usage:
DT_IO_CHANNELS_INPUT_BY_NAME(DT_NODELABEL(n), sensor) // 10 DT_IO_CHANNELS_INPUT_BY_NAME(DT_NODELABEL(n), bandgap) // 20
- Return
the input cell in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with an io-channels propertyname
: lowercase-and-underscores name of an io-channels element as defined by the node’s io-channel-names property
-
DT_IO_CHANNELS_INPUT
(node_id)¶ Equivalent to DT_IO_CHANNELS_INPUT_BY_IDX(node_id, 0)
- Return
the input cell in the specifier at index 0
- See
- Parameters
node_id
: node identifier for a node with an io-channels property
-
DT_INST_IO_CHANNELS_INPUT_BY_IDX
(inst, idx)¶ Get an input cell from the “DT_DRV_INST(inst)” io-channels property at an index.
- Return
the input cell in the specifier at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into io-channels property
-
DT_INST_IO_CHANNELS_INPUT_BY_NAME
(inst, name)¶ Get an input cell from the “DT_DRV_INST(inst)” io-channels property by name.
- Return
the input cell in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of an io-channels element as defined by the instance’s io-channel-names property
-
DT_INST_IO_CHANNELS_INPUT
(inst)¶ Equivalent to DT_INST_IO_CHANNELS_INPUT_BY_IDX(inst, 0)
- Return
the input cell in the specifier at index 0
- Parameters
inst
: DT_DRV_COMPAT instance number
-
PWM¶
These conveniences may be used for nodes which describe PWM controllers and properties related to them.
-
group
devicetree-pwms
Defines
-
DT_PWMS_LABEL_BY_IDX
(node_id, idx)¶ Get a label property from a pwms property at an index.
It’s an error if the PWM controller node referenced by the phandle in node_id’s pwms property at index “idx” has no label property.
Example devicetree fragment:
pwm1: pwm-controller@... { label = "PWM_1"; }; pwm2: pwm-controller@... { label = "PWM_2"; }; n: node { pwms = <&pwm1 1 PWM_POLARITY_NORMAL>, <&pwm2 3 PWM_POLARITY_INVERTED>; };
Example usage:
DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 0) // "PWM_1" DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "PWM_2"
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyidx
: logical index into pwms property
-
DT_PWMS_LABEL_BY_NAME
(node_id, name)¶ Get a label property from a pwms property by name.
It’s an error if the PWM controller node referenced by the phandle in node_id’s pwms property at the element named “name” has no label property.
Example devicetree fragment:
pwm1: pwm-controller@... { label = "PWM_1"; }; pwm2: pwm-controller@... { label = "PWM_2"; }; n: node { pwms = <&pwm1 1 PWM_POLARITY_NORMAL>, <&pwm2 3 PWM_POLARITY_INVERTED>; pwm-names = "alpha", "beta"; };
Example usage:
DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), alpha) // "PWM_1" DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), beta) // "PWM_2"
- Return
the label property of the node referenced at the named element
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyname
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_PWMS_LABEL
(node_id)¶ Equivalent to DT_PWMS_LABEL_BY_IDX(node_id, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
node_id
: node identifier for a node with a pwms property
-
DT_PWMS_CELL_BY_IDX
(node_id, idx, cell)¶ Get PWM specifier’s cell value at an index.
Example devicetree fragment:
pwm1: pwm-controller@... { compatible = "vnd,pwm"; label = "PWM_1"; #pwm-cells = <2>; }; pwm2: pwm-controller@... { compatible = "vnd,pwm"; label = "PWM_2"; #pwm-cells = <2>; }; n: node { pwms = <&pwm1 1 200000 PWM_POLARITY_NORMAL>, <&pwm2 3 100000 PWM_POLARITY_INVERTED>; };
Bindings fragment for the “vnd,pwm” compatible:
pwm-cells: - channel - period - flags
Example usage:
DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, channel) // 1 DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, channel) // 3 DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, period) // 200000 DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, period) // 100000 DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 0, flags) // PWM_POLARITY_NORMAL DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), 1, flags) // PWM_POLARITY_INVERTED
- Return
the cell value at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyidx
: logical index into pwms propertycell
: lowercase-and-underscores cell name
-
DT_PWMS_CELL_BY_NAME
(node_id, name, cell)¶ Get a PWM specifier’s cell value by name.
Example devicetree fragment:
pwm1: pwm-controller@... { compatible = "vnd,pwm"; label = "PWM_1"; #pwm-cells = <2>; }; pwm2: pwm-controller@... { compatible = "vnd,pwm"; label = "PWM_2"; #pwm-cells = <2>; }; n: node { pwms = <&pwm1 1 200000 PWM_POLARITY_NORMAL>, <&pwm2 3 100000 PWM_POLARITY_INVERTED>; pwm-names = "alpha", "beta"; };
Bindings fragment for the “vnd,pwm” compatible:
pwm-cells: - channel - period - flags
Example usage:
DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, channel) // 1 DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, channel) // 3 DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, period) // 200000 DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, period) // 100000 DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, flags) // PWM_POLARITY_NORMAL DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, flags) // PWM_POLARITY_INVERTED
- Return
the cell value in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyname
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names propertycell
: lowercase-and-underscores cell name
-
DT_PWMS_CELL
(node_id, cell)¶ Equivalent to DT_PWMS_CELL_BY_IDX(node_id, 0, cell)
- Return
the cell value at index 0
- See
- Parameters
node_id
: node identifier for a node with a pwms propertycell
: lowercase-and-underscores cell name
-
DT_PWMS_CHANNEL_BY_IDX
(node_id, idx)¶ Get a PWM specifier’s channel cell value at an index.
This macro only works for PWM specifiers with cells named “channel”. Refer to the node’s binding to check if necessary.
This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, channel).
- Return
the channel cell value at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyidx
: logical index into pwms property
-
DT_PWMS_CHANNEL_BY_NAME
(node_id, name)¶ Get a PWM specifier’s channel cell value by name.
This macro only works for PWM specifiers with cells named “channel”. Refer to the node’s binding to check if necessary.
This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, channel).
- Return
the channel cell value in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyname
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_PWMS_CHANNEL
(node_id)¶ Equivalent to DT_PWMS_CHANNEL_BY_IDX(node_id, 0)
- Return
the channel cell value at index 0
- See
- Parameters
node_id
: node identifier for a node with a pwms property
-
DT_PWMS_PERIOD_BY_IDX
(node_id, idx)¶ Get PWM specifier’s period cell value at an index.
This macro only works for PWM specifiers with cells named “period”. Refer to the node’s binding to check if necessary.
This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, period).
- Return
the period cell value at index “idx”
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyidx
: logical index into pwms property
-
DT_PWMS_PERIOD_BY_NAME
(node_id, name)¶ Get a PWM specifier’s period cell value by name.
This macro only works for PWM specifiers with cells named “period”. Refer to the node’s binding to check if necessary.
This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, period).
- Return
the period cell value in the specifier at the named element
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyname
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_PWMS_PERIOD
(node_id)¶ Equivalent to DT_PWMS_PERIOD_BY_IDX(node_id, 0)
- Return
the period cell value at index 0
- See
- Parameters
node_id
: node identifier for a node with a pwms property
-
DT_PWMS_FLAGS_BY_IDX
(node_id, idx)¶ Get a PWM specifier’s flags cell value at an index.
This macro expects PWM specifiers with cells named “flags”. If there is no “flags” cell in the PWM specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.
This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, idx, flags).
- Return
the flags cell value at index “idx”, or zero if there is none
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyidx
: logical index into pwms property
-
DT_PWMS_FLAGS_BY_NAME
(node_id, name)¶ Get a PWM specifier’s flags cell value by name.
This macro expects PWM specifiers with cells named “flags”. If there is no “flags” cell in the PWM specifier, zero is returned. Refer to the node’s binding to check specifier cell names if necessary.
This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, flags) if there is a flags cell, but expands to zero if there is none.
- Return
the flags cell value in the specifier at the named element, or zero if there is none
- See
- Parameters
node_id
: node identifier for a node with a pwms propertyname
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_PWMS_FLAGS
(node_id)¶ Equivalent to DT_PWMS_FLAGS_BY_IDX(node_id, 0)
- Return
the flags cell value at index 0, or zero if there is none
- See
- Parameters
node_id
: node identifier for a node with a pwms property
-
DT_INST_PWMS_LABEL_BY_IDX
(inst, idx)¶ Get a label property from a DT_DRV_COMPAT instance’s pwms property by name.
- Return
the label property of the node referenced at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into pwms property
-
DT_INST_PWMS_LABEL_BY_NAME
(inst, name)¶ Get a label property from a DT_DRV_COMPAT instance’s pwms property by name.
- Return
the label property of the node referenced at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_INST_PWMS_LABEL
(inst)¶ Equivalent to DT_INST_PWMS_LABEL_BY_IDX(inst, 0)
- Return
the label property of the node referenced at index 0
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_PWMS_CELL_BY_IDX
(inst, idx, cell)¶ Get a DT_DRV_COMPAT instance’s PWM specifier’s cell value at an index.
- Return
the cell value at index “idx”
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into pwms propertycell
: lowercase-and-underscores cell name
-
DT_INST_PWMS_CELL_BY_NAME
(inst, name, cell)¶ Get a DT_DRV_COMPAT instance’s PWM specifier’s cell value by name.
- Return
the cell value in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names propertycell
: lowercase-and-underscores cell name
-
DT_INST_PWMS_CELL
(inst, cell)¶ Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, 0, cell)
- Return
the cell value at index 0
- Parameters
inst
: DT_DRV_COMPAT instance numbercell
: lowercase-and-underscores cell name
-
DT_INST_PWMS_CHANNEL_BY_IDX
(inst, idx)¶ Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, channel)
- Return
the channel cell value at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into pwms property
-
DT_INST_PWMS_CHANNEL_BY_NAME
(inst, name)¶ Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, channel)
- Return
the channel cell value in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_INST_PWMS_CHANNEL
(inst)¶ Equivalent to DT_INST_PWMS_CHANNEL_BY_IDX(inst, 0)
- Return
the channel cell value at index 0
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_PWMS_PERIOD_BY_IDX
(inst, idx)¶ Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, period)
- Return
the period cell value at index “idx”
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into pwms property
-
DT_INST_PWMS_PERIOD_BY_NAME
(inst, name)¶ Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, period)
- Return
the period cell value in the specifier at the named element
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_INST_PWMS_PERIOD
(inst)¶ Equivalent to DT_INST_PWMS_PERIOD_BY_IDX(inst, 0)
- Return
the period cell value at index 0
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_PWMS_FLAGS_BY_IDX
(inst, idx)¶ Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, idx, flags)
- Return
the flags cell value at index “idx”, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance numberidx
: logical index into pwms property
-
DT_INST_PWMS_FLAGS_BY_NAME
(inst, name)¶ Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, flags)
- Return
the flags cell value in the specifier at the named element, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance numbername
: lowercase-and-underscores name of a pwms element as defined by the node’s pwm-names property
-
DT_INST_PWMS_FLAGS
(inst)¶ Equivalent to DT_INST_PWMS_FLAGS_BY_IDX(inst, 0)
- Return
the flags cell value at index 0, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
SPI¶
These conveniences may be used for nodes which describe either SPI controllers or devices, depending on the case.
-
group
devicetree-spi
Defines
-
DT_SPI_HAS_CS_GPIOS
(spi)¶ Does a SPI controller node have chip select GPIOs configured?
SPI bus controllers use the “cs-gpios” property for configuring chip select GPIOs. Its value is a phandle-array which specifies the chip select lines.
Example devicetree fragment:
spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 20 GPIO_ACTIVE_LOW>; }; spi2: spi@... { compatible = "vnd,spi"; };
Example usage:
DT_SPI_HAS_CS_GPIOS(DT_NODELABEL(spi1)) // 1 DT_SPI_HAS_CS_GPIOS(DT_NODELABEL(spi2)) // 0
- Return
1 if “spi” has a cs-gpios property, 0 otherwise
- Parameters
spi
: a SPI bus controller node identifier
-
DT_SPI_NUM_CS_GPIOS
(spi)¶ Number of chip select GPIOs in a SPI controller’s cs-gpios property.
Example devicetree fragment:
spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 20 GPIO_ACTIVE_LOW>; }; spi2: spi@... { compatible = "vnd,spi"; };
Example usage:
DT_SPI_NUM_CS_GPIOS(DT_NODELABEL(spi1)) // 2 DT_SPI_NUM_CS_GPIOS(DT_NODELABEL(spi2)) // 0
- Return
Logical length of spi’s cs-gpios property, or 0 if “spi” doesn’t have a cs-gpios property
- Parameters
spi
: a SPI bus controller node identifier
-
DT_SPI_DEV_HAS_CS_GPIOS
(spi_dev)¶ Does a SPI device have a chip select line configured? Example devicetree fragment:
spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 20 GPIO_ACTIVE_LOW>; a: spi-dev-a@0 { reg = <0>; }; b: spi-dev-b@1 { reg = <1>; }; }; spi2: spi@... { compatible = "vnd,spi"; c: spi-dev-c@0 { reg = <0>; }; };
Example usage:
DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(a)) // 1 DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(b)) // 1 DT_SPI_DEV_HAS_CS_GPIOS(DT_NODELABEL(c)) // 0
- Return
1 if spi_dev’s bus node DT_BUS(spi_dev) has a chip select pin at index DT_REG_ADDR(spi_dev), 0 otherwise
- Parameters
spi_dev
: a SPI device node identifier
-
DT_SPI_DEV_CS_GPIOS_LABEL
(spi_dev)¶ Get a SPI device’s chip select GPIO controller’s label property.
Example devicetree fragment:
gpio1: gpio@... { label = "GPIO_1"; }; gpio2: gpio@... { label = "GPIO_2"; }; spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 20 GPIO_ACTIVE_LOW>; a: spi-dev-a@0 { reg = <0>; }; b: spi-dev-b@1 { reg = <1>; }; };
Example usage:
DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(a)) // "GPIO_1" DT_SPI_DEV_CS_GPIOS_LABEL(DT_NODELABEL(b)) // "GPIO_2"
- Return
label property of spi_dev’s chip select GPIO controller
- Parameters
spi_dev
: a SPI device node identifier
-
DT_SPI_DEV_CS_GPIOS_PIN
(spi_dev)¶ Get a SPI device’s chip select GPIO pin number.
It’s an error if the GPIO specifier for spi_dev’s entry in its bus node’s cs-gpios property has no pin cell.
Example devicetree fragment:
spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>, <&gpio2 20 GPIO_ACTIVE_LOW>; a: spi-dev-a@0 { reg = <0>; }; b: spi-dev-b@1 { reg = <1>; }; };
Example usage:
DT_SPI_DEV_CS_GPIOS_PIN(DT_NODELABEL(a)) // 10 DT_SPI_DEV_CS_GPIOS_PIN(DT_NODELABEL(b)) // 20
- Return
pin number of spi_dev’s chip select GPIO
- Parameters
spi_dev
: a SPI device node identifier
-
DT_SPI_DEV_CS_GPIOS_FLAGS
(spi_dev)¶ Get a SPI device’s chip select GPIO flags.
Example devicetree fragment:
spi1: spi@... { compatible = "vnd,spi"; cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>; a: spi-dev-a@0 { reg = <0>; }; };
Example usage:
DT_SPI_DEV_CS_GPIOS_FLAGS(DT_NODELABEL(a)) // GPIO_ACTIVE_LOW
If the GPIO specifier for spi_dev’s entry in its bus node’s cs-gpios property has no flags cell, this expands to zero.
- Return
flags value of spi_dev’s chip select GPIO specifier, or zero if there is none
- Parameters
spi_dev
: a SPI device node identifier
-
DT_INST_SPI_DEV_HAS_CS_GPIOS
(inst)¶ Equivalent to DT_SPI_DEV_HAS_CS_GPIOS(DT_DRV_INST(inst)).
- Return
1 if the instance’s bus has a CS pin at index DT_INST_REG_ADDR(inst), 0 otherwise
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_SPI_DEV_CS_GPIOS_LABEL
(inst)¶ Get GPIO controller name for a SPI device instance This is equivalent to DT_SPI_DEV_CS_GPIOS_LABEL(DT_DRV_INST(inst)).
- Return
label property of the instance’s chip select GPIO controller
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_SPI_DEV_CS_GPIOS_PIN
(inst)¶ Equivalent to DT_SPI_DEV_CS_GPIOS_PIN(DT_DRV_INST(inst)).
- Return
pin number of the instance’s chip select GPIO
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
DT_INST_SPI_DEV_CS_GPIOS_FLAGS
(inst)¶ DT_SPI_DEV_CS_GPIOS_FLAGS(DT_DRV_INST(inst)).
- Return
flags value of the instance’s chip select GPIO specifier, or zero if there is none
- See
- Parameters
inst
: DT_DRV_COMPAT instance number
-
Chosen nodes¶
The special /chosen
node contains properties whose values describe
system-wide settings. The DT_CHOSEN()
macro can be used to get a node
identifier for a chosen node.
-
group
devicetree-generic-chosen
Defines
-
DT_CHOSEN
(prop)¶ Get a node identifier for a /chosen node property.
This is only valid to call if DT_HAS_CHOSEN(prop) is 1.
- Return
a node identifier for the chosen node property
- Parameters
prop
: lowercase-and-underscores property name for the /chosen node
-
DT_HAS_CHOSEN
(prop)¶ Test if the devicetree has a /chosen node.
- Return
1 if the chosen property exists and refers to a node, 0 otherwise
- Parameters
prop
: lowercase-and-underscores devicetree property
-
There are also conveniences for commonly used zephyr-specific properties of the
/chosen
node. (These may also be set in dts_fixup.h
files for now,
though this mechanism is deprecated.)
-
group
devicetree-zephyr
Defines
-
DT_CHOSEN_ZEPHYR_ENTROPY_LABEL
¶ If there is a chosen node zephyr,entropy property which has a label property, that property’s value. Undefined otherwise.
-
DT_CHOSEN_ZEPHYR_FLASH_CONTROLLER_LABEL
¶ If there is a chosen node zephyr,flash-controller property which has a label property, that property’s value. Undefined otherwise.
-
DT_CHOSEN_ZEPHYR_CAN_PRIMARY_LABEL
¶ If there is a chosen node zephyr,can-primary property which has a label property, that property’s value. Undefined otherwise.
-
The following table documents some commonly used Zephyr-specific chosen nodes.
Often, a chosen node’s label property will be used to set the default value of a Kconfig option which in turn configures a hardware-specific subsystem setting. This is usually for backwards compatibility in cases when the Kconfig option predates devicetree support in Zephyr. In other cases, there is no Kconfig option, and the devicetree node’s label property is used directly in the source code to specify a device name.
Property |
Purpose |
---|---|
zephyr,bt-c2h-uart |
Sets default |
zephyr,bt-mon-uart |
Sets default |
zephyr,bt-uart |
Sets default |
zephyr,can-primary |
Sets the primary CAN controller |
zephyr,ccm |
Core-Coupled Memory node on some STM32 SoCs |
zephyr,code-partition |
Flash partition that the Zephyr image’s text section should be linked into |
zephyr,console |
Sets default |
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 |
zephyr,flash-controller |
The node corresponding to the flash controller device for
the |
zephyr,ipc |
Used by the OpenAMP subsystem to specify the inter-process communication (IPC) device |
zephyr,ipc_shm |
A node whose |
zephyr,shell-uart |
Sets default |
zephyr,sram |
A node whose |
zephyr,uart-mcumgr |
UART used for Device Management |
zephyr,uart-pipe |
Sets default |
zephyr,usb-device |
USB device node. If defined and has a |