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 00000000000..a6d840b1f52 Binary files /dev/null and b/doc/guides/dts/zephyr_dt_build_flow.png differ 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 00000000000..9bed4b09b00 Binary files /dev/null and b/doc/guides/dts/zephyr_dt_i2c_example.png differ diff --git a/doc/guides/dts/zephyr_dt_i2c_example.svg b/doc/guides/dts/zephyr_dt_i2c_example.svg new file mode 100644 index 00000000000..2365d8f171a --- /dev/null +++ b/doc/guides/dts/zephyr_dt_i2c_example.svg @@ -0,0 +1,741 @@ + + + + + + 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 00000000000..b34f222d742 Binary files /dev/null and b/doc/guides/dts/zephyr_dt_i2c_high_level.png differ 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 00000000000..8baddb95075 Binary files /dev/null and b/doc/guides/dts/zephyr_dt_inputs_outputs.png differ 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. + + + +