new devicetree.h API

CODEOWNERS

@@ -119,7 +119,9 @@
 /doc/CMakeLists.txt                       @carlescufi
 /doc/scripts/                             @carlescufi
 /doc/guides/bluetooth/                    @joerchan @jhedberg @Vudentz
+/doc/guides/dts/                          @galak @mbolivar-nordic
 /doc/reference/bluetooth/                 @joerchan @jhedberg @Vudentz
+/doc/reference/devicetree/                @galak @mbolivar-nordic
 /doc/reference/kernel/other/resource_mgmt.rst @pabigot
 /doc/reference/networking/can*            @alexanderwachter
 /drivers/debug/                           @nashif
@@ -310,6 +312,7 @@
 /include/tracing/                         @wentongwu @nashif
 /include/debug/                           @nashif
 /include/device.h                         @wentongwu @nashif
+/include/devicetree.h                     @galak
 /include/display/                         @vanwinkeljan
 /include/dt-bindings/clock/kinetis_mcg.h  @henrikbrixandersen
 /include/dt-bindings/clock/kinetis_scg.h  @henrikbrixandersen

boards/arm/nucleo_f429zi/doc/index.rst

@@ -186,7 +186,7 @@ Flash partitions for MCUBoot bootloader
 ***************************************
 
 The on-board STM32F429ZI MCU has 2MBs of internal flash memory. To use `MCUboot`_,
-define a :ref:`Zephyr partition table <flash_partitions>` for the flash memory in
+define a :ref:`Zephyr partition table <legacy_flash_partitions>` for the flash memory in
 its devicetree file ``nucleo_f429zi.dts``. As a reference, a partition table for
 MCUBoot is already defined in the devicetree file, with these settings:
 

cmake/dts.cmake

@@ -4,16 +4,22 @@ file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/include/generated)
 
 # Zephyr code can configure itself based on a KConfig'uration with the
 # header file autoconf.h. There exists an analogous file devicetree_unfixed.h
-# that allows configuration based on information encoded in DTS.
+# that allows configuration based on information encoded in DTS, and a similar
+# file with legacy contents called devicetree_unfixed_legacy.h.
 #
-# Here we call on dtc, the gcc preprocessor, and
-# scripts/dts/gen_defines.py to generate this header file at
-# CMake configure-time.
+# Here we call on dtc, the gcc preprocessor,
+# scripts/dts/gen_defines.py, and scripts/dts/gen_legacy_defines.py to
+# generate various DT-related files at CMake configure-time.
 #
-# See ~/zephyr/doc/dts
-set(DEVICETREE_UNFIXED_H ${PROJECT_BINARY_DIR}/include/generated/devicetree_unfixed.h)
-set(DEVICETREE_CONF      ${PROJECT_BINARY_DIR}/include/generated/devicetree.conf)
-set(DTS_POST_CPP         ${PROJECT_BINARY_DIR}/${BOARD}.dts.pre.tmp)
+# The devicetree.conf file is still needed by some deprecated
+# functions in kconfigfunctions.py.
+#
+# See the Devicetree user guide in the Zephyr documentation for details.
+set(ZEPHYR_DTS                  ${PROJECT_BINARY_DIR}/zephyr.dts)
+set(DEVICETREE_UNFIXED_H        ${PROJECT_BINARY_DIR}/include/generated/devicetree_unfixed.h)
+set(DEVICETREE_UNFIXED_LEGACY_H ${PROJECT_BINARY_DIR}/include/generated/devicetree_legacy_unfixed.h)
+set(DEVICETREE_CONF             ${PROJECT_BINARY_DIR}/include/generated/devicetree.conf)
+set(DTS_POST_CPP                ${PROJECT_BINARY_DIR}/${BOARD}.dts.pre.tmp)
 
 set_ifndef(DTS_SOURCE ${BOARD_DIR}/${BOARD}.dts)
 
@@ -67,9 +73,9 @@ if(SUPPORTS_DTS)
          -include ${dts_file})
 
     if(i EQUAL 0)
-      message(STATUS "Loading ${dts_file} as base")
+      message(STATUS "Found BOARD.dts: ${dts_file}")
     else()
-      message(STATUS "Overlaying ${dts_file}")
+      message(STATUS "Found devicetree overlay: ${dts_file}")
     endif()
 
     math(EXPR i "${i}+1")
@@ -190,25 +196,49 @@ if(SUPPORTS_DTS)
   endif(DTC)
 
   #
-  # Run gen_defines.py to create a .conf file and a header file
+  # Run gen_defines.py to create a header file and zephyr.dts.
   #
 
-  set(CMD_NEW_EXTRACT ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/dts/gen_defines.py
+  set(CMD_EXTRACT ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/dts/gen_defines.py
   --dts ${BOARD}.dts.pre.tmp
   --dtc-flags '${EXTRA_DTC_FLAGS}'
   --bindings-dirs ${DTS_ROOT_BINDINGS}
-  --conf-out ${DEVICETREE_CONF}
   --header-out ${DEVICETREE_UNFIXED_H}
-  --dts-out ${PROJECT_BINARY_DIR}/zephyr.dts # As a debugging aid
+  --dts-out ${ZEPHYR_DTS} # As a debugging aid
+  )
+
+  #
+  # Run gen_legacy_defines.py to create a header file with legacy contents
+  # and a .conf file.
+  #
+
+  set(CMD_LEGACY_EXTRACT ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/dts/gen_legacy_defines.py
+  --dts ${BOARD}.dts.pre.tmp
+  --dtc-flags '${EXTRA_DTC_FLAGS}'
+  --bindings-dirs ${DTS_ROOT_BINDINGS}
+  --header-out ${DEVICETREE_UNFIXED_LEGACY_H}
+  --conf-out ${DEVICETREE_CONF}
   )
 
   execute_process(
-    COMMAND ${CMD_NEW_EXTRACT}
+    COMMAND ${CMD_EXTRACT}
+    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+    RESULT_VARIABLE ret
+    )
+  if(NOT "${ret}" STREQUAL "0")
+    message(FATAL_ERROR "gen_defines.py failed with return code: ${ret}")
+  else()
+    message(STATUS "Generated zephyr.dts: ${ZEPHYR_DTS}")
+    message(STATUS "Generated devicetree_unfixed.h: ${DEVICETREE_UNFIXED_H}")
+  endif()
+
+  execute_process(
+    COMMAND ${CMD_LEGACY_EXTRACT}
     WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
     RESULT_VARIABLE ret
     )
   if(NOT "${ret}" STREQUAL "0")
-    message(FATAL_ERROR "new extractor failed with return code: ${ret}")
+    message(FATAL_ERROR "gen_legacy_defines.py failed with return code: ${ret}")
   endif()
 
   # A file that used to be generated by 'dtc'. zephyr.dts is the new
@@ -218,4 +248,5 @@ if(SUPPORTS_DTS)
 
 else()
   file(WRITE ${DEVICETREE_UNFIXED_H} "/* WARNING. THIS FILE IS AUTO-GENERATED. DO NOT MODIFY! */")
+  file(WRITE ${DEVICETREE_UNFIXED_LEGACY_H} "/* WARNING. THIS FILE IS AUTO-GENERATED. DO NOT MODIFY! */")
 endif(SUPPORTS_DTS)

doc/application/index.rst

@@ -120,7 +120,7 @@ subdirectories which are not described here.
     Device driver code.
 
 :file:`dts`
-    :ref:`devicetree` source files used to describe non-discoverable
+    :ref:`devicetree <dt-guide>` source files used to describe non-discoverable
     board-specific hardware details.
 
 :file:`ext`
@@ -225,8 +225,8 @@ Follow these steps to create a new application directory. (Refer to
 
 #. Set Kconfig configuration options. See :ref:`application-kconfig`.
 
-#. Optionally, you can also configure any devicetree overlays needed by your
-   application. See :ref:`application_dt` below for details.
+#. Configure any devicetree overlays needed by your application.
+   See :ref:`set-devicetree-overlays`.
 
 .. _important-build-vars:
 
@@ -268,11 +268,10 @@ should know about.
 
   See :ref:`initial-conf` for more information.
 
-* :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more devicetree
-  overlay files. Multiple filenames can be separated with either spaces or
-  semicolons. Each file includes devicetree values that override the default
-  DT values. See :ref:`application_dt` below for details on devicetree
-  overlays, and :ref:`devicetree` for an overview on devicetree and Zephyr.
+* :makevar:`DTC_OVERLAY_FILE`: One or more devicetree overlay files to use.
+  Multiple files can be separated with spaces or semicolons.
+  See :ref:`set-devicetree-overlays` for examples and :ref:`devicetree-intro`
+  for information about devicetree and Zephyr.
 
 * :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of
   additional directories with source code, Kconfig, etc. that should be used in
@@ -721,6 +720,8 @@ Zephyr binary into your application directory.
 You can also define the ``SOC_ROOT`` variable in the application
 :file:`CMakeLists.txt` file.
 
+.. _dts_root:
+
 DeviceTree Definitions
 ======================
 
@@ -1085,11 +1086,9 @@ Make sure to follow these steps in order.
 
    See :ref:`initial-conf` for more information.
 
-#. If your application uses a devicetree overlay file or files other than
-   the usual :file:`<board>.overlay`, add lines setting the
-   :makevar:`DTC_OVERLAY_FILE` variable to these files appropriately.
-
-   More details are available below in :ref:`application_dt`.
+#. If your application uses devicetree overlays, you may need to set
+   :ref:`DTC_OVERLAY_FILE <important-build-vars>`.
+   See :ref:`set-devicetree-overlays`.
 
 #. If your application has its own kernel configuration options,
    create a :file:`Kconfig` file in the same directory as your
@@ -1205,59 +1204,10 @@ The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
 worth going through, especially if you planning to add new configuration
 options.
 
-.. _application_dt:
-
 Devicetree Overlays
 ===================
 
-As described in :ref:`devicetree`, Zephyr uses devicetree to describe the
-hardware it runs on. This section describes how you can modify an application
-build's devicetree using overlay files. For additional information regarding
-the relationship between devicetree and Kconfig see :ref:`dt_vs_kconfig`. For
-an example of how to use custom overlays with ``west build``, see
-:ref:`west-building-cmake-args`.
-
-In some cases the information contained in devicetree files is closely
-connected to the software and might need to be modified using the overlay file
-concept. This can be relevant for many of the different devicetree nodes, but
-is particularly useful for :ref:`certain types of nodes <dt-alias-chosen>`.
-
-Overlay files, which customarily have the :file:`.overlay` extension,
-contain devicetree fragments which add to or modify the devicetree
-used while building a Zephyr application. To add an overlay file or
-files to the build, set the CMake variable :makevar:`DTC_OVERLAY_FILE`
-to a whitespace-separated list of your overlay files.
-
-The Zephyr build system begins creation of a devicetree by running
-the C preprocessor on a file which includes the following:
-
-#. The board's devicetree source file, which by default is the Zephyr
-   file :file:`boards/<ARCHITECTURE>/<BOARD>/<BOARD>.dts`. (This location
-   can be overridden by setting the :makevar:`DTS_SOURCE` CMake
-   variable.)
-
-#. Any file or files given by the :makevar:`DTC_OVERLAY_FILE` CMake
-   variable.
-
-The Zephyr build system determines the ``DTC_OVERLAY_FILE`` value by
-looking at these potential definition locations, in order, until a value
-is determined, and then stops looking:
-
-1. the cmake command line (``-DDTC_OVERLAY_FILE=filename``)
-#. the cmake variable cache (from a previous cmake run)
-#. a ``CMakeLists.txt`` file in your application folder
-#. a ``DTC_OVERLAY_FILE`` environment variable (deprecated)
-#. a ``boards/<BOARD>.overlay`` file in your application folder,
-   for your specified ``<BOARD>``
-#. a ``<BOARD>.overlay`` file in your application folder, for
-   your specified ``<BOARD>``
-
-If :makevar:`DTC_OVERLAY_FILE` specifies multiple files, they are
-included in order by the C preprocessor.
-
-After running the preprocessor, the final devicetree used in the
-build is created by running the devicetree compiler, ``dtc``, on the
-preprocessor output.
+See :ref:`set-devicetree-overlays`.
 
 Application-Specific Code
 *************************

doc/getting_started/toolchain_custom_cmake.rst

@@ -14,8 +14,8 @@ Zephyr will then include the toolchain cmake files located in the
 :file:`TOOLCHAIN_ROOT` directory:
 
 - :file:`cmake/toolchain/generic.cmake`: configures the toolchain for "generic"
-  use, which mostly means running the C preprocessor on the generated
-  :ref:`devicetree` file.
+  use, which mostly means running the C preprocessor on :ref:`devicetree
+  input files <dt-input-files>`.
 - :file:`cmake/toolchain/target.cmake`: configures the toolchain for "target"
   use, i.e. building Zephyr and your application's source code.
 

doc/guides/build/index.rst

@@ -51,7 +51,7 @@ Devicetree
    from ``dtc`` is unused otherwise.
 
    The above is just a brief overview. For more information on devicetree, see
-   :ref:`devicetree`.
+   :ref:`dt-guide`.
 
 Devicetree fixups
    Files named :file:`dts_fixup.h` from the target’s architecture, SoC, board,

doc/guides/device_mgmt/dfu.rst

@@ -35,7 +35,7 @@ is the boot loader used with Zephyr. The source code itself is hosted in the
 In order to use MCUboot with Zephyr you need to take the following into account:
 
 1. You will need to define the :ref:`mcuboot_partitions` required by MCUboot in
-   the :ref:`flash_partitions`.
+   the :ref:`legacy_flash_partitions`.
 2. Your application's :file:`.conf` file needs to enable the
    :option:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option in order for Zephyr to
    be built in an MCUboot-compatible manner