From 85fa523cf0cf00dc7e90bb4dba35e71923e2a665 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 4 Oct 2019 13:34:15 -0700 Subject: [PATCH] doc: dts: add more explanations, with diagrams Re-work the introductory sections of the devicetree documentation, adding several figures and cross-references to other useful parts of the documentation. Signed-off-by: Marti Bolivar --- doc/guides/dts/index.rst | 484 +++++++---- doc/guides/dts/zephyr_dt_build_flow.png | Bin 0 -> 17450 bytes doc/guides/dts/zephyr_dt_build_flow.svg | 357 ++++++++ doc/guides/dts/zephyr_dt_i2c_example.png | Bin 0 -> 47078 bytes doc/guides/dts/zephyr_dt_i2c_example.svg | 741 ++++++++++++++++ doc/guides/dts/zephyr_dt_i2c_high_level.png | Bin 0 -> 9700 bytes doc/guides/dts/zephyr_dt_i2c_high_level.svg | 3 + doc/guides/dts/zephyr_dt_inputs_outputs.png | Bin 0 -> 77043 bytes doc/guides/dts/zephyr_dt_inputs_outputs.svg | 880 ++++++++++++++++++++ 9 files changed, 2297 insertions(+), 168 deletions(-) create mode 100644 doc/guides/dts/zephyr_dt_build_flow.png create mode 100644 doc/guides/dts/zephyr_dt_build_flow.svg create mode 100644 doc/guides/dts/zephyr_dt_i2c_example.png create mode 100644 doc/guides/dts/zephyr_dt_i2c_example.svg create mode 100644 doc/guides/dts/zephyr_dt_i2c_high_level.png create mode 100644 doc/guides/dts/zephyr_dt_i2c_high_level.svg create mode 100644 doc/guides/dts/zephyr_dt_inputs_outputs.png create mode 100644 doc/guides/dts/zephyr_dt_inputs_outputs.svg diff --git a/doc/guides/dts/index.rst b/doc/guides/dts/index.rst index 775a5ae1b27..4cd08f13419 100644 --- a/doc/guides/dts/index.rst +++ b/doc/guides/dts/index.rst @@ -1,177 +1,327 @@ .. _device-tree: -Device Tree -########### +Devicetree +########## -.. contents:: - :local: - :depth: 2 +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 "device tree". The +`Devicetree specification`_ fully defines this data structure and its source +and binary representations. + +.. _device-tree-intro: Introduction ************ -Device tree is a way of describing hardware and configuration information -for boards. Device tree was adopted for use in the Linux kernel for the -PowerPC architecture. However, it is now in use for ARM and other -architectures. +.. _Devicetree specification: https://www.devicetree.org/ -The device tree is a data structure for dynamically describing hardware -using a Device Tree Source (DTS) data structure language, instead of -hard coding every detail of a board's hardware into the operating system. +This figure shows how devicetree fits into the Zephyr build system: -In Linux, DTS is compiled into a compact Device Tree Blob (DTB) using a Device -Tree Compiler (DTC), then the hardware-describing DTB is passed to the operating -system at boot time. This allows the same compiled Linux kernel to support -different hardware configurations within an architecture family (e.g., ARM, -x86, PowerPC) and moves a significant part of the hardware description out of -the kernel binary itself. +.. figure:: zephyr_dt_build_flow.png + :figclass: align-center -For larger systems, the flexibility this offers offsets the extra runtime memory -overhead incurred. But the primary targets for Zephyr -applications are small micro-controller systems with limited memory -resources. So instead of requiring the additional runtime memory -to store the DTB blob and the code to parse it, the DTS information -is used at compile time. + Devicetree build flow -Device tree uses a specific format to describe the device nodes in a system. -This format is described in the `Device Tree Specification`_. +Zephyr's build system can use a devicetree to generate C language code. This +code generation uses rules in additional files called :ref:`devicetree bindings +` to control how devicetree data is converted to C definitions. The +generated code can be included by Zephyr :ref:`device drivers ` +and other C sources. The C macros generated by this process all begin with +``DT_``. -.. _Device Tree Specification: https://github.com/devicetree-org/devicetree-specification/releases +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. -More device tree information can be found at the `device tree repository`_. +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: -.. _device tree repository: https://git.kernel.org/pub/scm/utils/dtc/dtc.git +.. code-block:: none + /dts-v1/; -System build requirements -************************* + / { + a-node { + subnode_label: a-sub-node { + foo = <3>; + }; + }; + }; -The Zephyr device tree feature requires a device tree compiler (DTC) and Python -YAML packages. Refer to the installation guide for your specific host OS: +This example has three nodes: -* :ref:`installing_zephyr_win` -* :ref:`installation_linux` -* :ref:`installing_zephyr_mac` +#. A root node +#. A node named ``a-node``, which is a child of the root node +#. A node named ``a-sub-node``, which is a child of ``a-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``. -Zephyr and Device Tree +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: + +.. figure:: zephyr_dt_i2c_high_level.png + :alt: representation of a board with three I2C peripherals + :figclass: align-center + +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: + +.. code-block:: none + + / { + 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. + +.. figure:: zephyr_dt_i2c_example.png + :figclass: align-center + + 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 :ref:`device_drivers`. The + value can be passed to :c:func:`device_get_binding()` to retrieve the + corresponding driver-level :ref:`struct device* `. This + pointer can then be passed to the correct driver API by application code to + interact with the device. For example, calling + ``device_get_binding("I2C_0")`` would return a pointer to a device + structure which could be passed to :ref:`I2C API ` functions like + :c:func:`i2c_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 with ``apds9960@39`` and 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. + +.. code-block:: none + + / { + 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 ********************** -Device Tree provides a unified description of a hardware system used in an -application. It is used in Zephyr to describe hardware and provide a boot-time -configuration of this hardware. +The first figure in the :ref:`device-tree-intro` shows how devicetree fits into +the Zephyr build system. This section describes the input and output files in +more detail. -In Zephyr, the device tree is also used to describe Zephyr-specific -configuration information. This Zephyr-specific information augments the device -tree descriptions and sits on top of it, rather than diverging from it. The -main reason for this is to leverage existing device tree files that a SoC vendor -may already have defined for a given platform. +.. figure:: zephyr_dt_inputs_outputs.png + :figclass: align-center -The device tree files are compiled using the device tree compiler. The compiler -runs the .dts file through the C preprocessor to resolve any macro or #defines -utilized in the file. The output of the compile is another dts formatted file. + Devicetree input (green) and output (yellow) files -After compilation, a Python script extracts information from the compiled -device tree file using rules specified in *bindings* (see the :ref:`bindings` -section). The extracted information is placed in a header file that is used by -the rest of the code as the project is compiled. +DTS files usually have ``.dts`` or ``.dtsi`` (for Devicetree Source Include) +extensions. Zephyr's build system looks for a file named :file:`BOARD.dts` in +the board definition directory; this file contains the board's base +devicetree. See :ref:`dt_k6x_example` for real-world examples. -Temporary fixup files are required for device tree 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. +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 :file:`.overlay` extension to make it clear that +they're overlays. You can specify the overlay files to use at build time using +the :makevar:`DTC_OVERLAY_FILE` CMake variable described in +:ref:`important-build-vars`. The build system also looks for devicetree +overlays in several locations by default; see :ref:`application_dt` for the +list. -The Python code that deals with device tree and bindings is in -:zephyr_file:`scripts/dts/`. +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 :file:`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 +:file:`BOARD.dts_compiled` in the application build directory. This file +contains the final devicetree. + +This devicetree and the set of :ref:`bindings` are then used to generate C +definitions using scripts in :zephyr_file:`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 :zephyr_file:`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 :ref:`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 :zephyr_file:`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. .. _dt_vs_kconfig: -Device Tree vs Kconfig -********************** +Devicetree vs Kconfig +********************* -As mentioned above there are several tools used to configure the build with -Zephyr. -The two main ones, Device Tree and Kconfig, might seem to overlap in purpose, -but in fact they do not. This section serves as a reference to help you decide -whether to place configuration items in Device Tree or 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. -The scope of each configuration tool can be summarized as follows: +In short: -* Device Tree is used to describe the **hardware** and its **boot-time - configuration**. -* Kconfig is used to describe which **software features** will be built into - the final image, and their **configuration**. +* 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. -Hence Device Tree deals mostly with hardware and Kconfig with software. -A couple of noteworthy exceptions are: +In other words, devicetree mainly deals with hardware, and Kconfig with +software. -* Device Tree's ``chosen`` keyword, which allows the user to select a - particular instance of a hardware device to be used for a concrete purpose - by the software. An example of this is selecting a particular UART for use as - the system's console. -* Device Tree's ``status`` keyword, which allows the user to enable or disable - a particular instance of a hardware device in the Device Tree file itself. - This takes precedence over Kconfig. +For example, consider a board containing a SoC with 2 UART, or serial port, +instances. -To further clarify this separation, let's use a particular, well-known -example to illustrate this: serial ports a.k.a. UARTs. Let's consider a -board containing a SoC with 2 UART 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 ``compatible`` + property) and certain settings such as the address range of the hardware + peripheral registers in memory (via the ``reg`` property). +* 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. -* The fact that the target hardware **contains** 2 UARTs is described with Device - Tree. This includes the UART type, its driver compatibility and certain - immutable (i.e. not software-configurable) settings such as the base address - of the hardware peripheral in memory or its interrupt line. -* Additionally, **hardware boot-time configuration** is also described with Device - Tree. This includes things such as the IRQ priority and boot-time UART - baudrate. These may also be modifiable at runtime later, but their boot-time - default configuration is described in Device Tree. -* The fact that the user intends to include **software support** for UART in the - build is described in Kconfig. Through the use of Kconfig, users can opt not - to include support for this particular hardware item if they don't require it. +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. -Another example is a device with a 2.4GHz, multi-protocol radio supporting -both the Bluetooth Low Energy and 802.15.4 wireless technologies. In this case: +* 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. -* Device Tree describes the presence of a radio peripheral compatible with a - certain radio driver. -* Additional hardware boot-time configuration settings may also be present - in the Device Tree files. In this particular case it could be a - default TX power in dBm if the hardware does have a simple, cross-wireless - technology register for that. -* Kconfig will describe which **protocol stack** is to be used with that radio. - The user may decide to select BLE or 802.15.4, which will both depend on - the presence of a compatible radio in the Device Tree files. +There are two noteworthy **exceptions** to these rules: -Device tree file formats -************************ +* Devicetree's ``chosen`` keyword, 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 ``status`` keyword, 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. -Hardware and software is described inside of device tree files in clear text format. -These files have the file suffix of .dtsi or .dts. The .dtsi files are meant to -be included by other files. Typically for a given board you have some number of -.dtsi include files that pull in common device descriptions that are used across -a given SoC family. +.. _dt_k6x_example: -Example: FRDM K64F Board and Hexiwear K64 -========================================= +Example: FRDM-K64F and Hexiwear K64 +=================================== .. Give the filenames instead of the full paths below, as it's easier to read. The cramped 'foo.dts' style avoids extra spaces before commas. -These boards are defined in :zephyr_file:`frdm_k64fs.dts -` and :zephyr_file:`hexiwear_k64.dts -`. They are based on the same NXP -Kinetis SoC family, the K6X. +The FRDM-K64F and Hexiwear K64 board devicetrees are defined in +:zephyr_file:`frdm_k64fs.dts ` and +:zephyr_file:`hexiwear_k64.dts ` +respectively. Both boards have NXP SoCs from the same Kinetis SoC family, the +K6X. -Common definitions for K6X are stored in :zephyr_file:`nxp_k6x.dtsi +Common devicetree definitions for K6X are stored in :zephyr_file:`nxp_k6x.dtsi `, which is included by both board :file:`.dts` files. :zephyr_file:`nxp_k6x.dtsi` in turn includes -:zephyr_file:`armv7-m.dtsi`, which has common -definitions for ARMv7-M-based systems. +:zephyr_file:`armv7-m.dtsi`, which has common definitions +for Arm v7-M cores. Since :zephyr_file:`nxp_k6x.dtsi` is meant to be -generic across K6X-based boards, it leaves many devices disabled by default. -For example, there is a CAN controller defined as follows (with unimportant -parts skipped): +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): .. code-block:: none @@ -181,12 +331,13 @@ parts skipped): ... }; -It is up to the board :file:`.dts` files to enable devices (by setting -``status = "okay"``). The board :file:`.dts` files are also responsible for any -board-specific configuration of the device. +It is up to the board :file:`.dts` or application overlay files to enable these +devices as desired, by setting ``status = "okay"``. The board :file:`.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) enables the CAN controller, also -setting the bus speed: +For example, FRDM-K64 (but not Hexiwear K64) :file:`.dts` enables the CAN +controller and sets the bus speed: .. code-block:: none @@ -196,61 +347,58 @@ setting the bus speed: }; The ``&can0 { ... };`` syntax adds/overrides properties on the node with label -``can0``, i.e. the ``can@4002400`` node. +``can0``, i.e. the ``can@4002400`` node defined in the :file:`.dtsi` file. Other examples of board-specific customization is pointing properties in ``aliases`` and ``chosen`` to the right nodes (see :ref:`dt-alias-chosen`), and -making GPIO/PinMux assignments. +making GPIO/pinmux assignments. Currently supported boards ************************** -Device tree is currently supported on all embedded targets except posix +Devicetree is currently supported on all embedded targets except posix (boards/posix) and qemu_x86_64 (boards/x86_64). Adding support for a board ************************** -Adding device tree support for a given board requires adding a number of files. +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 -YAML descriptions that define the contents of a given Device Tree peripheral -node, and also any fixup files required to support the platform. +bindings in YAML format, and any fixup files required to support the platform. -When writing Device Tree Source files, it is good to separate out common -peripheral information that could be used across multiple SoC families or -boards. DTS files are identified by their file suffix. A .dtsi suffix denotes -a DTS file that is used as an include in another DTS file. A .dts suffix -denotes the primary DTS file for a given board. +It is best practice to separate common peripheral information that could be +used across multiple cores, SoC families, or boards in :file:`.dtsi` files, +reserving the :file:`.dts` suffix for the primary DTS file for a given board. -The primary DTS file will contain at a minimum a version line, optional -includes, and the root node definition. The root node will contain a model and -compatible that denotes the unique board described by the .dts file. +Devicetree Source File Template +=============================== -Device Tree Source File Template -================================ +A board's :file:`.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. .. code-block:: none - /dts-v1/; + /dts-v1/; - / { - model = "Model name for your board"; - compatible = "compatible for your board"; - /* rest of file */ - }; + #include + / { + model = "Human readable board name"; + compatible = "vendor,soc-on-your-board's-mcu"; + /* rest of file */ + }; -One suggestion for starting from scratch on a platform/board is to examine other -boards and their device tree source files. +You can use other board :file:`.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 device tree files for base SoC. These should be - .dtsi files to be included in the board-specific device tree files. + 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. @@ -284,7 +432,7 @@ The following is a more precise list of required files: * Overlay Files (optional) * Overlay files contain tweaks or changes to the SoC and Board support files - described above. They can be used to modify Device Tree configurations + described above. They can be used to modify devicetree configurations without having to change the SoC and Board files. See :ref:`application_dt` for more information on overlay files and the Zephyr build system. @@ -295,7 +443,7 @@ The following is a more precise list of required files: ================================ Using an alias with a common name for a particular node makes it easier for you -to write board-independent source code. Device Tree ``aliases`` nodes are used +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: @@ -311,7 +459,7 @@ hardware resources: 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 Device Tree ``chosen`` nodes very +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: @@ -351,10 +499,10 @@ The full set of Zephyr-specific ``chosen`` nodes follows: - ``DT_UART_MCUMGR_ON_DEV_NAME`` -Adding support for device tree in drivers -***************************************** +Adding support for devicetree in drivers +**************************************** -As drivers and other source code is converted over to make use of device tree +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. @@ -362,9 +510,9 @@ generated information, these drivers may require changes to match the generated Source Tree Hierarchy ********************* -The device tree files are located in a couple of different directories. The +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 device tree and YAML binding files are +directory where architecture agnostic devicetree and YAML binding files are located. Assuming the current working directory is the ZEPHYR_BASE, the directory @@ -375,7 +523,7 @@ hierarchy looks like the following:: dts/bindings/ boards/// -The common directory contains a ``skeleton.dtsi`` which provides device tree root +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. @@ -392,8 +540,8 @@ Example: Subset of DTS/YAML files for NXP FRDM K64F (Subject to Change):: .. _bindings: -Bindings -******** +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 @@ -530,7 +678,7 @@ Include files generation ************************ At build time, after a board's ``.dts`` file has been processed by the DTC -(Device Tree Compiler), a corresponding ``.dts_compiled`` file is generated +(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 @@ -562,6 +710,6 @@ 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 device tree information. +files, giving Zephyr C source files access to the board's devicetree information. .. include:: flash_partitions.inc diff --git a/doc/guides/dts/zephyr_dt_build_flow.png b/doc/guides/dts/zephyr_dt_build_flow.png new file mode 100644 index 0000000000000000000000000000000000000000..a6d840b1f5234053833232c1ff574b218efa82e0 GIT binary patch literal 17450 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 XRl@@N2qz4R{sA7SB8Eo literal 0 HcmV?d00001 diff --git a/doc/guides/dts/zephyr_dt_build_flow.svg b/doc/guides/dts/zephyr_dt_build_flow.svg new file mode 100644 index 00000000000..1c707cae0b5 --- /dev/null +++ b/doc/guides/dts/zephyr_dt_build_flow.svg @@ -0,0 +1,357 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + Devicetree source + + + Devicetree source + + + + + + + + + + Build system + + + Build system + + + + + + + + + + + + + + Generated C header + + + Generated C header + + + + + + + + + + Zephyr and application source code files + + + + Zephyr and application + source code files + + + + + + + + + + + + Devicetree bindings + + + Devicetree bindings + + + + + diff --git a/doc/guides/dts/zephyr_dt_i2c_example.png b/doc/guides/dts/zephyr_dt_i2c_example.png new file mode 100644 index 0000000000000000000000000000000000000000..9bed4b09b00250168126fda050d55ab590841676 GIT binary patch literal 47078 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 zΒNXp%qRK$MNC@j*m$j76j3M^u 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 FvM4sA+jxbUjPW+baJl< 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 + + + + + image/svg+xml + + + + + + + + + + + + + + + + + / + + + / + + + + + + + + + + + + + + + + + i2c@40003000 + + + i2c@40003000 + + + + + + + compatible = "nordic,nrf-twim" + + + compatible = "nordic,nrf-twim" + + + + + + + + label = "I2C_0" + + + + + label = "I2C_0" + + + + + + + + reg = <0x4003000 0x1000> + + + + reg = <0x40003000 0x1000> + + + + + + + + + + + + + + soc + + + soc + + + + + + + + + + + + + mma8652fc@1d + + + mma8652fc@1d + + + + + + + compatible = "nxp,fxos8700", "nxp,mma8652fc" + + + compatible = "nxp,fxos8700", "nxp,mma8652fc" + + + + + + + label = "MMA8652FC" + + + label = "MMA8652FC" + + + + + + + reg = <0x1d> + + + reg = <0x1d> + + + + + + + + + + + + ti_hdc@43 + + + ti_hdc@43 + + + + + + + compatible = "ti,hdc", "ti,hdc1010" + + + compatible = "ti,hdc", "ti,hdc1010" + + + + + + + label = "HDC1010" + + + label = "HDC1010" + + + + + + + reg = <0x43> + + + reg = <0x43> + + + + + + + + + + + + + apds9960@39 + + + apds9960@39 + + + + + + + + compatible = "avago,apds9960" + + + compatible = "avago,apds9960" + + + + + + + label = "APDS9960" + + + label = "APDS9960" + + + + + + + reg = <0x39> + + + reg = <0x39> + + + + + diff --git a/doc/guides/dts/zephyr_dt_i2c_high_level.png b/doc/guides/dts/zephyr_dt_i2c_high_level.png new file mode 100644 index 0000000000000000000000000000000000000000..b34f222d742d8343794c36ac8192ac0b1a641950 GIT binary patch literal 9700 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 literal 0 HcmV?d00001 diff --git a/doc/guides/dts/zephyr_dt_i2c_high_level.svg b/doc/guides/dts/zephyr_dt_i2c_high_level.svg new file mode 100644 index 00000000000..8a4ce228339 --- /dev/null +++ b/doc/guides/dts/zephyr_dt_i2c_high_level.svg @@ -0,0 +1,3 @@ + + +
/
/
I2C bus master
I2C bus master
soc
soc
I2C peripheral 3
I2C peripheral 3
I2C peripheral 2
I2C peripheral 2
I2C peripheral 1
I2C peripheral 1
\ No newline at end of file diff --git a/doc/guides/dts/zephyr_dt_inputs_outputs.png b/doc/guides/dts/zephyr_dt_inputs_outputs.png new file mode 100644 index 0000000000000000000000000000000000000000..8baddb950755e58cc73035c055a319079bd7d63b GIT binary patch literal 77043 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 literal 0 HcmV?d00001 diff --git a/doc/guides/dts/zephyr_dt_inputs_outputs.svg b/doc/guides/dts/zephyr_dt_inputs_outputs.svg new file mode 100644 index 00000000000..eb6187a3444 --- /dev/null +++ b/doc/guides/dts/zephyr_dt_inputs_outputs.svg @@ -0,0 +1,880 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + FILE1.overlay + ... + FILE_n.overlay + + + + + + FILE_1.overlay + ... + FILE_n.overlay + + + + + + + + + + + Set by DTC_OVERLAY_FILE. + Optional DTS format files + which override BOARD.dts + + + + + + Set by DTC_OVERLAY_FILE. + Optional DTS format files + which override BOARD.dts. + + + + + + + + + + + In board directory. +The "base" devicetree.Includes .dtsi files. + + + + + + In board directory. + The "base" devicetree. + Includes .dtsi files. + + + + + + + + + + + dtc + + + + Apply + overlays + + + + + + + + + + + BOARD.dts + + + BOARD.dts + + + + + + + + + + + + + BINDING_1.yaml + ... + BINDING_n.yaml + + + + + + BINDING_1.yaml + ... + BINDING_n.yaml + + + + + + + + + + + In zephyr/dts/bindings. + Extensible with DTS_ROOT. + Contain rules for DTS to C + code generation step. + + + + + + In zephyr/dts/bindings/. + Extensible with DTS_ROOT. + Contain rules for DTS to C + code generation step. + + + + + + + + + + + + zephyr DTS + scripts + + + + + + Apply bindings, + generate code + + + + + + + + + + + + BOARD.dts_compiled + + + + + + BOARD.dts_compiled + + + + + + + + + + + In build/zephyr. + DTS file, combination of BOARD.dts and overlays. + Intermediate output. + + + + + + + + + + + + + + + + + Final outputs. + + In build/zephyr/include/generated. + + + + Include C headers via + <generated_dts_board.h> + + + + + + Final outputs, in + build/zephyr/include/generated/. + + + + + + + + + + + + + + generated_dts_board.conf, + generated C headers. + + + + + + Generated C code + (generated_dts_board_<foo>.h) + Include via <generated_dts_board.h> + only, as _<foo> names may change. + + + + + + + + + + In zephyr/dts/bindings. + Extensible with DTS_ROOT. + Contain rules for DTS to C + code generation step. + + + + + + DTS file in build/zephyr/. + Intermediate output, + combination of base + devicetree and any + overlays. + + + +