doc: Add Device Tree documentation

This patch adds documention for device tree development in Zephyr.  This
includes a description of device tree, how it is integrated into Zephyr,
and other related information.

Signed-off-by: Andy Gross <[email protected]>

Author: Andy Gross

doc/dts/device_tree.rst

@@ -0,0 +1,252 @@
+.. _device-tree:
+
+Device Tree in Zephyr
+########################
+
+Introduction to Device Tree
+***************************
+
+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.
+
+The device tree is a data structure for dynamically describing hardware
+using a Device Tree Source (DTS) data structure language, and compiled
+into a compact Device Tree Blob (DTB) using a Device Tree Compiler (DTC).
+Rather than hard coding every detail of a board's hardware into the
+operating system, 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.
+
+Traditional usage of device tree involves storing of the Device Tree Blob.
+The DTB is then used during runtime for configuration of device drivers.  In
+Zephyr, the DTS information will be used only during compile time.
+Information about the system is extracted from the compiled DTS and used to
+create the application image.
+
+Device tree uses a specific format to describe the device nodes in a system.
+This format is described in `EPAPR document`_.
+
+.. _EPAPR document: http://www.devicetree.org/specifications-pdf
+
+More device tree information can be found at the `device tree repository`_.
+
+.. _device tree repository: https://git.kernel.org/pub/scm/utils/dtc/dtc.git
+
+
+System build requirements
+*************************
+
+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.
+
+:ref:`installing_zephyr_win`
+
+:ref:`installation_linux`
+
+:ref:`installing_zephyr_mac`
+
+
+Zephyr and Device Tree
+**********************
+
+In Zephyr, device tree is used to not only describe hardware, but also to
+describe Zephyr-specific configuration information.  The Zephyr-specific
+information is intended to augment the device tree descriptions.  The main
+reason for this is to leverage existing device tree files that a SoC vendor may
+already have defined for a given platform.
+
+Today, configuration in Zephyr comes from a number of different places.  It can
+come from Kconfig files, CMSIS header files, vendor header files, prj.conf
+files, and other miscellaneous sources.  The intent of using device tree is to
+replace or curtail the use of Kconfig files throughout the system, and instead
+use device tree files to describe the configuration of device nodes.  CMSIS and
+vendor header files can be used in conjunction with the device tree to fully
+describe hardware.  Device tree is not intended to replace CMSIS or vendor
+include files.
+
+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.
+
+After compilation, a python script extracts information from the compiled device
+tree file using a set of rules specified in YAML files.  The extracted
+information is placed in a header file that is used by the rest of the code as
+the project is compiled.
+
+A temporary fixup file is required for device tree support on most devices.
+This .fixup file resides in the dts architecture directory and has the same
+name as the master .dts file.  The only difference is the suffix is .fixup.
+This fixup file maps the generated include information to the current
+driver/source usage.
+
+Device tree file formats
+************************
+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.
+
+-----------------------------------------
+Example: FRDM K64F Board and Hexiwear K64
+-----------------------------------------
+Both of these boards are based on the same NXP Kinetis SoC family, the K6X.  The
+following shows the include hierarchy for both boards.
+
+dts/arm/frdm_k64.dts includes the following two files::
+
+  dts/arm/nxp/nxp_k6x.dtsi
+  dts/arm/armv7-m.dtsi
+
+dts/arm/hexiwear_k64.dts includes the same two files::
+
+  dts/arm/nxp/nxp_k6x.dtsi
+  dts/arm/armv7-m.dtsi
+
+The board-specific .dts files enable nodes, define the Zephyr-specific items,
+and also adds board-specific changes like gpio/pinmux assignments.  These types
+of things will vary based on the board layout and application use.
+
+Currently supported boards
+**************************
+
+Device tree is currently supported on all ARM targets.  Support for all other
+architectures is to be completed by release 1.9.
+
+Adding support for a board
+**************************
+
+Adding device tree 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.
+
+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.
+
+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.
+
+--------------------------------
+Device Tree Source File Template
+--------------------------------
+
+.. code::
+
+  /dts-v1/
+  / {
+          model = "Model name for your board";
+          compatible = "compatible for your board";
+          /* rest of file */
+  };
+
+
+One suggestion for starting from scratch on a platform/board is to examine other
+boards and their device tree source files.
+
+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 to dts/<ARCH>/Makefile or create Makefile if not present
+  * Add target specific device tree files for base SoC.  These should be
+    .dtsi files to be included in the board-specific device tree files.
+  * Add target specific YAML files in the dts/<ARCH>/yaml 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 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.
+  * Add board-specific YAML 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.
+
+Adding support for device tree in drivers
+*****************************************
+
+As drivers and other source code is converted over to make use of device tree
+generated information, these drivers may require changes to match the generated
+#define information.
+
+
+Source Tree Hierarchy
+*********************
+
+The device tree 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 files are located.
+
+Assuming the current working directory is the ZEPHYR_BASE, the directory
+hierarchy looks like the following::
+
+  dts/common/
+  dts/common/yaml
+  dts/<ARCH>/
+  dts/<ARCH>/yaml
+
+The common directories contain a skeleton.dtsi include file that defines the
+address and size cells.  The yaml subdirectory contains common yaml files for
+Zephyr-specific nodes/properties and generic device properties common across
+architectures.
+
+Example: DTS/YAML files for NXP FRDM K64F::
+
+  dts/arm/armv7-m.dtsi
+  dts/arm/k6x/nxp_k6x.dtsi
+  dts/arm/frdm_k64f.dts
+  dts/arm/yaml/arm,v7m-nvic.yaml
+  dts/arm/yaml/k64gpio.yaml
+  dts/arm/yaml/k64pinmux.yaml
+  dts/arm/yaml/k64uart.yaml
+
+YAML definitions for device nodes
+*********************************
+
+Device tree can describe hardware and configuration, but it doesn't tell the
+system which pieces of information are useful, or how to generate configuration
+data from the device tree nodes.  For this, we rely on YAML files to describe
+the contents or definition of a device tree node.
+
+A YAML description must be provided for every device node that is to be a source
+of information for the system.  This YAML description can be used for more than
+one purpose.  It can be used in conjunction with the device tree to generate
+include information.  It can also be used to validate the device tree files
+themselves.  A device tree file can successfully compile and still not contain
+the necessary pieces required to build the rest of the software.  YAML provides
+a means to detect that issue.
+
+YAML files reside in a subdirectory inside the common and architecture-specific
+device tree directories.  A YAML template file is provided to show the required
+format.  This file is located at:
+
+  dts/common/yaml/device_node.yaml.template
+
+YAML files must end in a .yaml suffix.  YAML files are scanned during the
+information extraction phase and are matched to device tree nodes via the
+compatible property.

doc/getting_started/installation_linux.rst

@@ -55,7 +55,7 @@ Install the required packages in a Ubuntu host system with:
 .. code-block:: console
 
    $ sudo apt-get install git make gcc g++ python3-ply ncurses-dev \
-	 python3-yaml dfu-util dtc
+	 python3-yaml dfu-util device-tree-compiler
 
 Install the required packages in a Fedora host system with:
 

doc/index.rst

@@ -35,6 +35,7 @@ Sections
    application/application.rst
    porting/porting.rst
    drivers/drivers.rst
+   dts/device_tree.rst
    subsystems/subsystems.rst
    api/api.rst
    samples/samples.rst