Devicetree¶
Zephyr uses the devicetree data structure to describe the hardware available on a board, as well as its initial configuration in an application. Note that “devicetree” – without spaces – is preferred to “devicetree”. The Devicetree specification fully defines this data structure and its source and binary representations.
Introduction¶
This figure shows how devicetree fits into the Zephyr build system:
Devicetree build flow¶
Zephyr’s build system can use a devicetree to generate C language code. This
code generation uses rules in additional files called devicetree bindings to control how devicetree data is converted to C definitions. The
generated code can be included by Zephyr device drivers
and other C sources. The C macros generated by this process all begin with
DT_.
This differs significantly from how devicetree is used on Linux. The Linux kernel would instead read the entire devicetree data structure in its binary form, parsing it at runtime in order to load and initialize device drivers. Zephyr does not work this way because the size of the devicetree binary and associated handling code would be too large to fit comfortably on the relatively constrained devices Zephyr supports.
As the name indicates, a devicetree is a tree. The human-readable text format for this tree is called DTS (for devicetree source), and is defined in the Devicetree Specification. Here is an example DTS file:
/dts-v1/;
/ {
a-node {
subnode_label: a-sub-node {
foo = <3>;
};
};
};
This example has three nodes:
A root node
A node named
a-node, which is a child of the root nodeA node named
a-sub-node, which is a child ofa-node
Nodes can be given labels, which are unique shorthands that can be used to
refer to the labeled node elsewhere in the devicetree. Above, a-sub-node
has label subnode_label.
Devicetree nodes have paths identifying their locations in the tree. Like
Unix file system paths, devicetree paths are strings separated by slashes
(/), and the root node’s path is a single slash: /. Otherwise, each
node’s path is formed by concatenating the node’s ancestors’ names with the
node’s own name, separated by slashes. For example, the full path to
a-sub-node is /a-node/a-sub-node.
Devicetree nodes can also have properties. Properties are name/value
pairs. The values are simple byte arrays. Node a-sub-node has a property
named foo, whose value is a 32-bit big-endian unsigned integer with value
3. The size and type of foo’s value are implied by the enclosing angle
brackets (< and >) in the DTS. Refer to the Devicetree Specification
for a complete list of ways to write a property value in a DTS file.
In practice, devicetree nodes correspond to some hardware, and the node hierarchy reflects the hardware’s physical layout. For example, let’s consider a board with three I2C peripherals connected to an I2C bus master on an SoC, like this:
Nodes corresponding to the I2C bus master and each I2C peripheral would be present in this board’s devicetree. Reflecting the hardware layout, the devicetree’s peripheral nodes would be children of the bus master node. Similar conventions exist for representing other types of hardware in devicetree.
The corresponding DTS would look something like this:
/ {
soc {
i2c-bus-master {
i2c-peripheral-1 {
};
i2c-peripheral-2 {
};
i2c-peripheral-3 {
};
};
};
};
Properties are used in practice to describe or configure the hardware the node represents. For example, an I2C peripheral’s node has a property whose value is the peripheral’s address on the bus.
Here’s a tree representing the same example, but with real-world node names and properties you might see when working with I2C devices.
I2C devicetree example with real-world names and properties¶
Above, node names – like i2c@40003000 – are at the top of each node, with
a gray background, except for the root node, which is shown using its path
/. Properties are shown as name=value pairs below the node names.
Some important properties are:
compatible: this says what “kind” of device the node represents. Its value is a null-terminated string in the format “vendor,device”, like
"avago,apds9960", or a sequence of these, like"ti,hdc", "ti,hdc1010". The build system uses the compatible property to find the right bindings for the node.label: the device’s name according to Zephyr’s Device Driver Model. The value can be passed to
device_get_binding()to retrieve the corresponding driver-level struct device*. This pointer can then be passed to the correct driver API by application code to interact with the device. For example, callingdevice_get_binding("I2C_0")would return a pointer to a device structure which could be passed to I2C API functions likei2c_transfer(). The generated C header will also contain a macro which expands to this string.reg: information used to address the device. This could be a memory-mapped I/O address range (as with
i2c@40003000’s reg property), an I2C bus address (as withapds9960@39and its devicetree siblings), a SPI chip select line, or some other value depending on the kind of device the node represents.
This tree has the following DTS.
/ {
soc {
i2c@40003000 {
compatible = "nordic,nrf-twim";
label = "I2C_0";
reg = <0x40003000 0x1000>;
apds9960@39 {
compatible = "avago,apds9960";
label = "APDS9960";
reg = <0x39>;
};
ti_hdc@43 {
compatible = "ti,hdc", "ti,hdc1010";
label = "HDC1010;
reg = <0x43>;
};
mma8652fc@1d {
compatible = "nxp,fxos8700", "nxp,mma8652fc";
label = "MMA8652FC";
reg = <0x1d>;
};
};
};
};
Input and output files¶
The first figure in the Introduction shows how devicetree fits into the Zephyr build system. This section describes the input and output files in more detail.
Devicetree input (green) and output (yellow) files¶
DTS files usually have .dts or .dtsi (for Devicetree Source Include)
extensions. Zephyr’s build system looks for a file named BOARD.dts in
the board definition directory; this file contains the board’s base
devicetree. See Example: FRDM-K64F and Hexiwear K64 for real-world examples.
The build system combines the board’s DTS with additional input files called
overlays to produce a final devicetree source file. Overlays are also written
in the DTS format, but have a .overlay extension to make it clear that
they’re overlays. You can specify the overlay files to use at build time using
the DTC_OVERLAY_FILE CMake variable described in
Important Build System Variables. The build system also looks for devicetree
overlays in several locations by default; see Devicetree Overlays for the
list.
Overlays can be used to add or delete nodes from the tree, or to modify node properties and their values. Along with Kconfig, devicetree overlays let you reconfigure the kernel and device drivers without modifying their source code.
Before they are combined, the C preprocessor is run on BOARD.dts and any
overlays. This allows these files to use C macros and include directives.
The combined devicetree is written to a DTS file named
BOARD.dts_compiled in the application build directory. This file
contains the final devicetree.
This devicetree and the set of Devicetree Bindings are then used to generate C
definitions using scripts in scripts/dts/. These definitions can
be included via the generated_dts_board.h header file, which the build
system places on the C preprocessor include path. This file is not generated;
it is in include/generated_dts_board.h. (Its name was chosen
for backwards compatibility.)
Do not include the generated C headers in the build directory directly. Use
generated_dts_board.h instead.
Zephyr device drivers typically use information from generated_dts_board.h
to statically allocate and initialize struct device
instances. Property values from generated_dts_board.h are usually stored in
ROM in the value pointed to by a device->config->config_info field. For
example, a struct device corresponding to an I2C peripheral would store the
peripheral address in its reg property there.
Application source code with a pointer to the struct device can then pass
it to driver APIs in include/drivers/. These API functions
usually take a struct device* as their first argument. This allows the
driver API to use information from devicetree to interact with the device
hardware.
Temporary “fixup” files are currently required for devicetree support on most
devices. These fixup files by default reside in the board and soc directories
and are named dts_fixup.h. These fixup files map the generated include
information to the current driver/source usage. They exist for historical
reasons; Zephyr is moving away from needing or using these files.
Example: FRDM-K64F and Hexiwear K64¶
The FRDM-K64F and Hexiwear K64 board devicetrees are defined in frdm_k64fs.dts and hexiwear_k64.dts respectively. Both boards have NXP SoCs from the same Kinetis SoC family, the K6X.
Common devicetree definitions for K6X are stored in nxp_k6x.dtsi, which is included by both board .dts
files. nxp_k6x.dtsi in turn includes
armv7-m.dtsi, which has common definitions
for Arm v7-M cores.
Since nxp_k6x.dtsi is meant to be
generic across K6X-based boards, it leaves many devices disabled by default
using status properties. For example, there is a CAN controller defined as
follows (with unimportant parts skipped):
can0: can@40024000 {
...
status = "disabled";
...
};
It is up to the board .dts or application overlay files to enable these
devices as desired, by setting status = "okay". The board .dts
files are also responsible for any board-specific configuration of the device,
such as adding nodes for on-board sensors, LEDs, buttons, etc.
For example, FRDM-K64 (but not Hexiwear K64) .dts enables the CAN
controller and sets the bus speed:
&can0 {
status = "okay";
bus-speed = <125000>;
};
The &can0 { ... }; syntax adds/overrides properties on the node with label
can0, i.e. the can@4002400 node defined in the .dtsi file.
Other examples of board-specific customization is pointing properties in
aliases and chosen to the right nodes (see aliases and chosen nodes), and
making GPIO/pinmux assignments.
Devicetree vs Kconfig¶
Along with devicetree, Zephyr also uses the Kconfig language to configure the source code. Whether to use devicetree or Kconfig for a particular purpose can sometimes be confusing. This section should help you decide which one to use.
In short:
Use devicetree to describe hardware and its boot-time configuration. Examples include peripherals on a board, boot-time clock frequencies, interrupt lines, etc.
Use Kconfig to configure software support to build into the final image. Examples include whether to add networking support, which drivers are needed by the application, etc.
In other words, devicetree mainly deals with hardware, and Kconfig with software.
For example, consider a board containing a SoC with 2 UART, or serial port, instances.
The fact that the board has this UART hardware is described with two UART nodes in the devicetree. These provide the UART type (via the
compatibleproperty) and certain settings such as the address range of the hardware peripheral registers in memory (via theregproperty).Additionally, the UART boot-time configuration is also described with devicetree. This could include configuration such as the RX IRQ line’s priority and the UART baud rate. These may be modifiable at runtime, but their boot-time configuration is described in devicetree.
Whether or not to include software support for UART in the build is controlled via Kconfig. Applications which do not need to use the UARTs can remove the driver source code from the build using Kconfig, even though the board’s devicetree still includes UART nodes.
As another example, consider a device with a 2.4GHz, multi-protocol radio supporting both the Bluetooth Low Energy and 802.15.4 wireless technologies.
Devicetree should be used to describe the presence of the radio hardware, what driver or drivers it’s compatible with, etc.
Boot-time configuration for the radio, such as TX power in dBm, should also be specified using devicetree.
Kconfig should determine which software features should be built for the radio, such as selecting a BLE or 802.15.4 protocol stack.
There are two noteworthy exceptions to these rules:
Devicetree’s
chosenkeyword, which allows the user to select a specific instance of a hardware device to be used for a particular purpose. An example of this is selecting a particular UART for use as the system’s console.Devicetree’s
statuskeyword, which allows the user to enable or disable a particular instance of a hardware device. This takes precedence over related Kconfig options which serve a similar purpose.
Currently supported boards¶
Devicetree is currently supported on all embedded targets except posix (boards/posix).
Adding support for a board¶
Adding devicetree support for a given board requires adding a number of files. These files will contain the DTS information that describes a platform, the bindings in YAML format, and any fixup files required to support the platform.
It is best practice to separate common peripheral information that could be
used across multiple cores, SoC families, or boards in .dtsi files,
reserving the .dts suffix for the primary DTS file for a given board.
Devicetree Source File Template¶
A board’s .dts file contains at least a version line, optional
includes, and a root node definition with model and compatible
properties. These property values denote the particular board.
/dts-v1/;
#include <vendor/soc.dtsi>
/ {
model = "Human readable board name";
compatible = "vendor,soc-on-your-board's-mcu";
/* rest of file */
};
You can use other board .dts files as a starting point.
The following is a more precise list of required files:
Base architecture support
Add architecture-specific DTS directory, if not already present. Example: dts/arm for Arm.
Add target specific devicetree files for base SoC. These should be .dtsi files to be included in the board-specific devicetree files.
Add target specific YAML binding files in the dts/bindings/ directory. Create the yaml directory if not present.
SoC family support
Add one or more SoC family .dtsi files that describe the hardware for a set of devices. The file should contain all the relevant nodes and base configuration that would be applicable to all boards utilizing that SoC family.
Add SoC family YAML binding files that describe the nodes present in the .dtsi file.
Board specific support
Add a board level .dts file that includes the SoC family .dtsi files and enables the nodes required for that specific board.
Board .dts file should specify the SRAM and FLASH devices, if present.
Flash device node might specify flash partitions. For more details see Flash Partitions
Add board-specific YAML binding files, if required. This would occur if the board has additional hardware that is not covered by the SoC family .dtsi/.yaml files.
Fixup files
Fixup files contain mappings from existing Kconfig options to the actual underlying DTS derived configuration #defines. Fixup files are temporary artifacts until additional DTS changes are made to make them unnecessary.
Overlay Files (optional)
Overlay files contain tweaks or changes to the SoC and Board support files described above. They can be used to modify devicetree configurations without having to change the SoC and Board files. See Devicetree Overlays for more information on overlay files and the Zephyr build system.
aliases and chosen nodes¶
Using an alias with a common name for a particular node makes it easier for you
to write board-independent source code. Devicetree aliases nodes are used
for this purpose, by mapping certain generic, commonly used names to specific
hardware resources:
aliases {
led0 = &led0;
sw0 = &button0;
sw1 = &button1;
uart-0 = &uart0;
uart-1 = &uart1;
};
Certain software subsystems require a specific hardware resource to bind to in
order to function properly. Some of those subsystems are used with many
different boards, which makes using the devicetree chosen nodes very
convenient. By doing, so the software subsystem can rely on having the specific
hardware peripheral assigned to it. In the following example we bind the shell
to uart1 in this board:
chosen {
zephyr,shell-uart = &uart1;
};
The full set of Zephyr-specific chosen nodes follows:
|
Generated symbol |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Adding support for devicetree in drivers¶
As drivers and other source code is converted over to make use of devicetree generated information, these drivers may require changes to match the generated #define information.
Source Tree Hierarchy¶
The devicetree files are located in a couple of different directories. The directory split is done based on architecture, and there is also a common directory where architecture agnostic devicetree and YAML binding files are located.
Assuming the current working directory is the ZEPHYR_BASE, the directory hierarchy looks like the following:
dts/common/
dts/<ARCH>/
dts/bindings/
boards/<ARCH>/<BOARD>/
The common directory contains a skeleton.dtsi which provides devicetree root
node definition. The bindings subdirectory contains YAML binding files used
to instruct how the python DTS parsing script should extract nodes information
in a format that will be usable by the system.
Example: Subset of DTS/YAML files for NXP FRDM K64F (Subject to Change):
dts/arm/armv7-m.dtsi
dts/arm/k6x/nxp_k6x.dtsi
boards/arm/frdm_k64f/frdm_k64f.dts
dts/bindings/interrupt-controller/arm,v7m-nvic.yaml
dts/bindings/gpio/nxp,kinetis-gpio.yaml
dts/bindings/pinctrl/nxp,kinetis-pinmux.yaml
dts/bindings/serial/nxp,kinetis-uart.yaml
Devicetree Bindings¶
.dts files describe the available hardware devices, but don’t tell the
system which pieces of information are useful, or what kind of configuration
output (#define’s) should be generated. Bindings provide this
information. Bindings are files in YAML format.
Configuration output is only generated for devices that have bindings.
Nodes are mapped to bindings via their compatible string(s). Take
the following node as an example:
bar-device {
compatible = "foo-company,bar-device";
...
};
This node would get mapped to a binding with this in it:
compatible: "foo-company,bar-device"
You might also run across this legacy syntax, which works the same way:
...
properties:
compatible:
constraint: "foo-company,bar-device"
...
Bindings are stored in dts/bindings/. The filename usually
matches the compatible string.
If a node has more than one compatible string, then the first binding found
is used, going from the first string to the last. For example, a node with
compatible = "foo-company,bar-device", "generic-bar-device" would get
mapped to the binding for generic-bar-device if there is no binding for
foo-company,bar-device.
If a node appears on a bus (e.g. I2C or SPI), then the bus type is also taken
into account when mapping nodes to bindings. See the description of parent
and child in the template below.
Below is a template that shows the format of binding files, stored in dts/binding-template.yaml.
title: Short description of the node
description: |
Longer free-form description of the node. Can have multiple
lines/paragraphs.
See https://yaml-multiline.info/ for formatting help.
# Used to map nodes to bindings
compatible: "manufacturer,device"
# The 'compatible' above would match this node:
#
# device {
# compatible = "manufacturer,device";
# ...
# };
#
# Assuming no binding has 'compatible: "manufacturer,device-v2"', it would also
# match this node:
#
# device {
# compatible = "manufacturer,device-v2", "manufacturer,device";
# ...
# };
#
# Strings in 'compatible' properties on nodes are tried from left to right, and
# the first binding found is used.
#
# If more than one binding for a compatible is found, an error is raised.
# Bindings can include other files, which can be used to share common
# definitions between bindings.
#
# Included files are merged into bindings with a simple recursive dictionary
# merge. It is up to the binding author to make sure that the final merged
# binding is well-formed, though it is checked by the code as well.
#
# It is an error if a key appears with a different value in a binding and in a
# file it includes, with one exception: A binding can have 'required: true' for
# some property for which the included file has 'required: false' (see the
# description of 'properties' below). The 'required: true' from the binding
# takes precedence, allowing bindings to strengthen requirements from included
# files.
#
# Note that weakening requirements by having 'required: false' where the
# included file has 'required: true' is an error. This is meant to keep the
# organization clean.
#
# The file base.yaml contains definitions for many common properties. When
# writing a new binding, it is a good idea to check if base.yaml already
# defines some of the needed properties, and including it in that case. Note
# that you can make a property defined in base.yaml obligatory like this
# (taking 'reg' as an example):
#
# reg:
# required: true
#
# This relies on the dictionary merge to fill in the other keys for 'reg', like
# 'type'.
#
# When including multiple files, any overlapping 'required' keys on properties
# in the included files are ORed together. This makes sure that a
# 'required: true' is always respected.
include: other.yaml # or [other1.yaml, other2.yaml]
# If the node describes a bus, then the bus type should be given, like below.
# The name has "child" in it since it describes the bus children of the node
# appear on.
child-bus: <string describing bus type, e.g. "i2c">
# If the node appears on a bus, then the bus type should be given, like below.
#
# When looking for a binding for a node, the code checks if the binding for the
# parent node contains 'child-bus: <bus type>'. If it does, then only bindings
# with a matching 'parent-bus: <bus type>' are considered. This allows the same
# type of device to have different bindings depending on what bus it appears
# on.
parent-bus: <string describing bus type, e.g. "i2c">
# 'properties' describes properties on the node, e.g.
#
# reg = <1 2>;
# current-speed = <115200>;
# label = "foo";
#
# This is used to check that required properties appear, and to
# control the format of output generated for them. Except for some
# special-cased properties like 'reg', only properties listed here will
# generate output.
#
# A typical property entry looks like this:
#
# <property name>:
# required: <true | false>
# type: <string | int | boolean | array | uint8-array | string-array |
# phandle | phandles | phandle-array | compound>
# description: <description of the property>
# enum:
# - <item1>
# - <item2>
# ...
# - <itemN>
# const: <string | int>
# default: <default>
#
# These types are available:
#
# - 'type: int' is for properties that are assigned a single 32-bit value,
# like
#
# frequency = <100>;
#
# - 'type: array' is for properties that are assigned zero or more 32-bit
# values, like
#
# pin-config = <1 2 3>;
#
# - 'type: uint8-array' is for properties that are assigned zero or more
# bytes with the [] syntax, like
#
# lookup-table = [89 AB CD EF];
#
# Each byte is given in hex.
#
# This type is called 'bytestring' in the Devicetree specification.
#
# - 'type: string' is for properties that are assigned a single string, like
#
# ident = "foo";
#
# - 'type: string-array' if for properties that are assigned zero or more
# strings, like
#
# idents = "foo", "bar", "baz";
#
# - 'type: boolean' is for properties used as flags that don't take a value,
# like
#
# hw-flow-control;
#
# The macro generated for the property gets set to 1 if the property exists
# on the node, and to 0 otherwise. When combined with 'required: true',
# this type just forces the flag to appear on the node. The output will
# always be 1 in that case.
#
# Warning: Since a macro is always generated for 'type: boolean'
# properties, don't use #ifdef in tests. Do this instead:
#
# #if DT_SOME_BOOLEAN_PROP == 1
#
# - 'type: phandle' is for properties that are assigned a single phandle,
# like
#
# foo = <&label>;
#
# - 'type: phandles' is for properties that are assigned zero or more
# phandles, like
#
# foo = <&label1 &label2 ...>;
#
# - 'type: phandle-array' is for properties that take a list of phandles and
# (possibly) 32-bit numbers, like
#
# pwms = <&ctrl-1 1 2 &ctrl-2 3 4>;
#
# This type requires that the property works in the standard way that
# devicetree properties like pwms, clocks, *-gpios, and io-channels work.
# Taking 'pwms' as an example, the final -s is stripped from the property
# name, and #pwm-cells is looked up in the node for the controller
# (&ctrl-1/&ctrl-2) to determine the number of data values after the
# phandle. The binding for each controller must also have a *-cells key
# (e.g. pwm-cells), giving names to data values. See below for an
# explanation of *-cells.
#
# A *-names (e.g. pwm-names) property can appear on the node as well,
# giving a name to each entry (the 'pwms' example above has two entries,
# <&ctrl-1 1 2> and <&ctrl-2 3 4>).
#
# Because other property names are derived from the name of the property by
# removing the final -s, the property name must end in -s. An error is
# raised if it doesn't.
#
# *-gpios properties are special-cased so that e.g. foo-gpios resolves to
# #gpio-cells rather than #foo-gpio-cells.
#
# All phandle-array properties support mapping through *-map properties,
# e.g. gpio-map. See the devicetree spec.
#
# - 'type: compound' is a catch-all for more complex types, e.g.
#
# foo = <&label1>, [01 02];
#
# 'type: array' and the other array types also allow splitting the value into
# several <> blocks, e.g. like this:
#
# foo = <1 2>, <3 4>; // Okay for 'type: array'
# foo = <&label1 &label2>, <&label3 &label4>; // Okay for 'type: phandles'
# foo = <&label1 1 2>, <&label2 3 4>; // Okay for 'type: phandle-array'
# etc.
#
# The optional 'default:' setting gives a value that will be used if the
# property is missing from the device tree node. If 'default: <default>' is
# given for a property <prop> and <prop> is missing, then the output will be as
# if '<prop> = <default>' had appeared (except YAML data types are used for the
# default value).
#
# Note that it only makes sense to combine 'default:' with 'required: false'.
# Combining it with 'required: true' will raise an error.
#
# See below for examples of 'default:'. Putting 'default:' on any property type
# besides those used in the examples will raise an error.
properties:
# Describes a property like 'current-speed = <115200>;'. We pretend that
# it's obligatory for the example node and set 'required: true'.
current-speed:
type: int
required: true
description: Initial baud rate for bar-device
# Describes an optional property like 'keys = "foo", "bar";'
keys:
type: string-array
required: false
description: Keys for bar-device
# Describes an optional property like 'maximum-speed = "full-speed";
# the enum specifies known values that the string property may take
maximum-speed:
type: string
required: false
description: Configures USB controllers to work up to a specific speed.
enum:
- "low-speed"
- "full-speed"
- "high-speed"
- "super-speed"
# Describes a required property '#address-cells = <1>'; the const
# specifies that the value for the property is expected to be the value 1
"#address-cells":
type: int
required: true
const: 1
int-with-default:
type: int
required: false
default: 123
array-with-default:
type: array
required: false
default: [1, 2, 3] # Same as 'array-with-default = <1 2 3>'
string-with-default:
type: string
required: false
default: "foo"
string-array-with-default:
type: string-array
required: false
default: ["foo", "bar"] # Same as 'string-array-with-default = "foo", "bar"'
uint8-array-with-default:
type: uint8-array
required: false
default: [0x12, 0x34] # Same as 'uint8-array-with-default = [12 34]'
# 'child-binding' can be used when a node has children that all share the same
# properties. Each child gets the contents of 'child-binding' as its binding
# (though an explicit 'compatible = ...' on the child node takes precedence, if
# a binding is found for it).
#
# The example below is for a binding for PWM LEDs, where the child nodes are
# required to have a 'pwms' property. It corresponds to this .dts structure
# (assuming the binding has 'compatible: "pwm-leds"'):
#
# pwmleds {
# compatible = "pwm-leds";
#
# red_pwm_led {
# pwms = <&pwm3 4 15625000>;
# };
# green_pwm_led {
# pwms = <&pwm3 0 15625000>;
# };
# ...
# };
child-binding:
title: PWM LED
description: LED that uses PWM
properties:
pwms:
type: phandle-array
required: true
# 'child-binding' also works recursively. For example, the binding below would
# provide a binding for the 'grandchild' node in this .dts (assuming
# 'compatible: "foo"'):
#
# parent {
# compatible = "foo";
# child {
# grandchild {
# prop = <123>;
# };
# };
# }
#
# WARNING: Due to implementation issues with legacy code, only up to two levels
# of 'child-binding:' nesting (like below) is supported. This restriction will
# go away in Zephyr 2.2.
child-binding:
title: ...
description: ...
...
child-binding:
title: ...
description: ...
properties:
prop:
type: int
required: true
# If the binding describes an interrupt controller, GPIO controller, pinmux
# device, or any other node referenced by other nodes via 'phandle-array'
# properties, then *-cells should be given.
#
# To understand the purpose of *-cells, assume that some node has
#
# pwms = <&pwm-ctrl 1 2>;
#
# , where &pwm-ctrl refers to a node whose binding is this file.
#
# The <1 2> part of the property value is called a *specifier* (this
# terminology is from the devicetree specification), and contains additional
# data associated with the GPIO. Here, the specifier has two cells, and the
# node pointed at by &gpio-ctrl is expected to have '#pwm-cells = <2>'.
#
# *-cells gives a name to each cell in the specifier. These names are used when
# generating identifiers.
#
# In this example, assume that 1 refers to a pin and that 2 is a flag value.
# This gives a *-cells assignment like below.
pwm-cells:
- channel # name of first cell
- period # name of second cell
# If the specifier is empty (e.g. '#clock-cells = <0>'), then *-cells can
# either be omitted (recommended) or set to an empty array. Note that an empty
# array is specified as e.g. 'clock-cells: []' in YAML.
# As a special case, all *-gpio properties map to the key 'gpio-cells',
# regardless of prefix
gpio-cells:
- pin
- flags
# This older syntax is deprecated and will generate a warning when used. It
# works as a catch-all, where the name of the referencing 'phandle-array'
# property doesn't matter.
"#cells":
- pin
- flags
Legacy binding syntax¶
Various parts of the binding syntax were simplified and generalized for the Zephyr 2.1 release.
The binding below shows various legacy syntax.
title: ...
description: ...
inherits:
!include foo.yaml
parent:
bus: spi
properties:
compatible:
constraint: "company,device"
type: string-array
frequency:
type: int
category: optional
sub-node:
properties:
child-prop:
type: int
category: required
# Assume this is a binding for an interrupt controller
"#cells":
- irq
- priority
- flags
This should now be written like this:
title: ...
description: ...
compatible: "company,device"
include: foo.yaml
parent-bus: spi
properties:
frequency:
type: int
required: false
child-binding:
title: ...
description: ...
properties:
child-prop:
type: int
required: true
interrupt-cells:
- irq
- priority
- cells
The legacy syntax is still supported for backwards compatibility, but generates deprecation warnings. Support will be dropped in the Zephyr 2.3 release.
Include files generation¶
At build time, after a board’s .dts file has been processed by the DTC
(Devicetree Compiler), a corresponding .dts_compiled file is generated
under the zephyr directory.
This .dts_compiled file is processed by the python DTS parsing script
and generates an include file named
include/generated/generated_dts_board_unfixed.h
that holds all the information extracted from the DTS file with
the format specified by the YAML bindings. For example:
/* gpio_keys */
#define DT_GPIO_KEYS_0 1
/* button_0 */
#define DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER "GPIO_2"
#define DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS 0
#define DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN 6
#define DT_GPIO_KEYS_BUTTON_0_LABEL "User SW2"
#define DT_GPIO_KEYS_SW1_GPIOS_CONTROLLER DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER
#define DT_GPIO_KEYS_SW1_GPIOS_FLAGS DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS
#define DT_GPIO_KEYS_SW1_GPIOS_PIN DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN
#define DT_ALIAS_SW1_GPIOS_CONTROLLE DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER
#define DT_ALIAS_SW1_GPIOS_FLAGS DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS
#define DT_ALIAS_SW1_GPIOS_PIN DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN
#define DT_ALIAS_SW1_LABEL DT_GPIO_KEYS_BUTTON_0_LABEL
Additionally, a file named generated_dts_board_fixups.h is
generated in the same directory concatenating all board-related fixup files.
The include file include/generated_dts_board.h includes both these generated
files, giving Zephyr C source files access to the board’s devicetree information.
GPIO Nexus Nodes¶
Each board has a set of General Purpose Input/Output (GPIO) peripherals that can be accessed through the GPIO module. Many boards provide headers that allow shields from other vendors to be mounted on their boards. Each shield identifies its hardware in a devicetree overlay.
GPIOs accessed by the shield peripherals must be identified using the
shield GPIO abstraction, for example from the arduino-r3-header
compatible. Boards that provide the header must map the header pins
to SOC-specific pins. This is accomplished by including a nexus
node that looks like the following into the board devicetree file:
arduino_header: connector {
compatible = "arduino-header-r3";
#gpio-cells = <2>;
gpio-map-mask = <0xffffffff 0xffffffc0>;
gpio-map-pass-thru = <0 0x3f>;
gpio-map = <0 0 &gpioa 0 0>, /* A0 */
<1 0 &gpioa 1 0>, /* A1 */
<2 0 &gpioa 4 0>, /* A2 */
<3 0 &gpiob 0 0>, /* A3 */
<4 0 &gpioc 1 0>, /* A4 */
<5 0 &gpioc 0 0>, /* A5 */
<6 0 &gpioa 3 0>, /* D0 */
<7 0 &gpioa 2 0>, /* D1 */
<8 0 &gpioa 10 0>, /* D2 */
<9 0 &gpiob 3 0>, /* D3 */
<10 0 &gpiob 5 0>, /* D4 */
<11 0 &gpiob 4 0>, /* D5 */
<12 0 &gpiob 10 0>, /* D6 */
<13 0 &gpioa 8 0>, /* D7 */
<14 0 &gpioa 9 0>, /* D8 */
<15 0 &gpioc 7 0>, /* D9 */
<16 0 &gpiob 6 0>, /* D10 */
<17 0 &gpioa 7 0>, /* D11 */
<18 0 &gpioa 6 0>, /* D12 */
<19 0 &gpioa 5 0>, /* D13 */
<20 0 &gpiob 9 0>, /* D14 */
<21 0 &gpiob 8 0>; /* D15 */
};
This specifies how Arduino pin references like <&arduino_header 11
0> are converted to SOC gpio pin references like <&gpiob 4 0>.
In Zephyr GPIO specifiers generally have two parameters (indicated by
#gpio-cells = <2>): the pin number and a set of flags. The low 6
bits of the flags correspond to features that can be configured in
devicetree. In some cases it’s necessary to use a non-zero flag value
to tell the driver how a particular pin behaves, as with:
drdy-gpios = <&arduino_header 11 GPIO_ACTIVE_LOW>;
After preprocessing this becomes <&arduino_header 11 1>. Normally
the presence of such a flag would cause the map lookup to fail,
because there is no map entry with a non-zero flags value. The
gpio-map-mask property specifies that, for lookup, all bits of the
pin and all but the low 6 bits of the flags are used to identify the
specifier. Then the gpio-map-pass-thru specifies that the low 6
bits of the flags are copied over, so the SOC GPIO reference becomes
<&gpiob 4 1> as intended.
See nexus node for more information about this capability.
Flash Partitions¶
Device tree can be used to describe a partition layout for any flash device in the system.
Two important uses for this mechanism are:
To force the Zephyr image to be linked into a specific area on Flash.
This is useful, for example, if the Zephyr image must be linked at some offset from the flash device’s start, to be loaded by a bootloader at runtime.
To generate compile-time definitions for the partition layout, which can be shared by Zephyr subsystems and applications to operate on specific areas in flash.
This is useful, for example, to create areas for storing file systems or other persistent state. These defines only describe the boundaries of each partition. They don’t, for example, initialize a partition’s flash contents with a file system.
Partitions are generally managed using device tree overlays. Refer to Devicetree Overlays for details on using overlay files.
Defining Partitions¶
The partition layout for a flash device is described inside the
partitions child node of the flash device’s node in the device
tree.
You can define partitions for any flash device on the system.
Most Zephyr-supported SoCs with flash support in device tree
will define a label flash0. This label refers to the primary
on-die flash programmed to run Zephyr. To generate partitions
for this device, add the following snippet to a device tree overlay
file:
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
/* Define your partitions here; see below */
};
};
To define partitions for another flash device, modify the above to either use its label or provide a complete path to the flash device node in the device tree.
The content of the partitions node looks like this:
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
partition1_label: partition@START_OFFSET_1 {
label = "partition1_name";
reg = <0xSTART_OFFSET_1 0xSIZE_1>;
};
/* ... */
partitionN_label: partition@START_OFFSET_N {
label = "partitionN_name";
reg = <0xSTART_OFFSET_N 0xSIZE_N>;
};
};
Where:
partitionX_labelare device tree labels that can be used elsewhere in the device tree to refer to the partitionpartitionX_namecontrols how defines generated by the Zephyr build system for this partition will be namedSTART_OFFSET_xis the start offset in hexadecimal notation of the partition from the beginning of the flash deviceSIZE_xis the hexadecimal size, in bytes, of the flash partition
The partitions do not have to cover the entire flash device. The device tree compiler currently does not check if partitions overlap; you must ensure they do not when defining them.
Example Primary Flash Partition Layout¶
Here is a complete (but hypothetical) example device tree overlay snippet illustrating these ideas. Notice how the partitions do not overlap, but also do not cover the entire device.
&flash0 {
partitions {
compatible = "fixed-partitions";
#address-cells = <1>;
#size-cells = <1>;
code_dts_label: partition@8000 {
label = "zephyr-code";
reg = <0x00008000 0x34000>;
};
data_dts_label: partition@70000 {
label = "application-data";
reg = <0x00070000 0xD000>;
};
};
};
Linking Zephyr Within a Partition¶
To force the linker to output a Zephyr image within a given flash partition, add this to a device tree overlay:
/ {
chosen {
zephyr,code-partition = &slot0_partition;
};
};
If the chosen node has no zephyr,code-partition property, the
application image link uses the entire flash device. If a
zephyr,code-partition property is defined, the application link
will be restricted to that partition.
Flash Partition Macros¶
The Zephyr build system generates definitions for each flash device
partition. These definitions are available to any files which
include <zephyr.h>.
Consider this flash partition:
dts_label: partition@START_OFFSET {
label = "def-name";
reg = <0xSTART_OFFSET 0xSIZE>;
};
The build system will generate the following corresponding defines:
#define FLASH_AREA_DEF_NAME_LABEL "def-name"
#define FLASH_AREA_DEF_NAME_OFFSET_0 0xSTART_OFFSET
#define FLASH_AREA_DEF_NAME_SIZE_0 0xSIZE
#define FLASH_AREA_DEF_NAME_OFFSET FLASH_AREA_MCUBOOT_OFFSET_0
#define FLASH_AREA_DEF_NAME_SIZE FLASH_AREA_MCUBOOT_SIZE_0
As you can see, the label property is capitalized when forming the
macro names. Other simple conversions to ensure it is a valid C
identifier, such as converting “-” to “_”, are also performed. The
offsets and sizes are available as well.
MCUboot Partitions¶
MCUboot is a secure bootloader for 32-bit microcontrollers.
Some Zephyr boards provide definitions for the flash partitions which are required to build MCUboot itself, as well as any applications which must be chain-loaded by MCUboot.
The device tree labels for these partitions are:
- boot_partition
This is the partition where the bootloader is expected to be placed. MCUboot’s build system will attempt to link the MCUboot image into this partition.
- slot0_partition
MCUboot loads the executable application image from this partition. Any application bootable by MCUboot must be linked to run from this partition.
- slot1_partition
This is the partition which stores firmware upgrade images. Zephyr applications which receive firmware updates must ensure the upgrade images are placed in this partition (the Zephyr DFU subsystem can be used for this purpose). MCUboot checks for upgrade images in this partition, and can move them to
slot0_partitionfor execution. Theslot0_partitionandslot1_partitionmust be the same size.- scratch_partition
This partition is used as temporary storage while swapping the contents of
slot0_partitionandslot1_partition.
Important
Upgrade images are only temporarily stored in slot1_partition.
They must be linked to execute of out of slot0_partition.
See the MCUboot documentation for more details on these partitions.
File System Partitions¶
- storage_partition
This is the area where e.g. NFFS expects its partition.