doc: update devicetree sections

Reflect the removal of BOARD.dts.pre.tmp in favor of zephyr.dts.pre in
SVG diagrams. Clean up adjacent text.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/guides/build/build-config-phase.svg

@@ -61,8 +61,8 @@ phase (driven by CMake) and a build phase (driven by Make or Ninja).
 Configuration Phase
 -------------------
 
-The configuration phase begins when the user invokes *CMake*,
-specifying a source application directory and a board target.
+The configuration phase begins when the user invokes *CMake* to generate a
+build system, specifying a source application directory and a board target.
 
 .. figure:: build-config-phase.svg
     :align: center
@@ -75,7 +75,10 @@ directory, which refers to the :file:`CMakeLists.txt` file in the Zephyr
 top-level directory, which in turn refers to :file:`CMakeLists.txt` files
 throughout the build tree (directly and indirectly). Its primary output is a
 set of Makefiles or Ninja files to drive the build process, but the CMake
-scripts also do some processing of their own:
+scripts also do some processing of their own, which is explained here.
+
+Note that paths beginning with :file:`build/` below refer to the build
+directory you create when running CMake.
 
 Devicetree
    :file:`*.dts` (*devicetree source*) and :file:`*.dtsi` (*devicetree source
@@ -86,32 +89,35 @@ Devicetree
    preprocessor (often abbreviated *cpp*, which should not be confused with
    C++). The C preprocessor is also used to merge in any devicetree
    :file:`*.overlay` files, and to expand macros in :file:`*.dts`,
-   :file:`*.dtsi`, and :file:`*.overlay` files.
+   :file:`*.dtsi`, and :file:`*.overlay` files. The preprocessor output is
+   placed in :file:`build/zephyr/zephyr.dts.pre`.
+
+   The preprocessed devicetree sources are parsed by
+   :zephyr_file:`gen_defines.py <scripts/dts/gen_defines.py>` to generate a
+   :file:`build/zephyr/include/generated/devicetree_unfixed.h` header with
+   preprocessor macros.
 
-   The preprocessed devicetree sources (stored in :file:`*.dts.pre.tmp`) are
-   parsed by :zephyr_file:`gen_defines.py <scripts/dts/gen_defines.py>` to
-   generate a :file:`devicetree_unfixed.h` header with preprocessor macros.
+   Source code should access preprocessor macros generated from devicetree by
+   including the :zephyr_file:`devicetree.h <include/devicetree.h>` header,
+   which includes :file:`devicetree_unfixed.h`.
 
-   As a debugging aid, :file:`gen_defines.py` writes the final devicetree to
-   :file:`zephyr.dts`. This file is just for reference. It is not used
-   anywhere.
+   :file:`gen_defines.py` also writes the final devicetree to
+   :file:`build/zephyr/zephyr.dts` in the build directory. This file's contents
+   may be useful for debugging.
 
-   The ``dtc`` devicetree compiler also gets run on the preprocessed devicetree
-   sources to catch any extra warnings and errors generated by it. The output
-   from ``dtc`` is unused otherwise.
+   If the devicetree compiler ``dtc`` is installed, it is run on
+   :file:`build/zephyr/zephyr.dts` to catch any extra warnings and errors
+   generated by this tool. The output from ``dtc`` is unused otherwise, and
+   this step is skipped if ``dtc`` is not installed.
 
    The above is just a brief overview. For more information on devicetree, see
    :ref:`dt-guide`.
 
 Devicetree fixups
    Files named :file:`dts_fixup.h` from the target’s architecture, SoC, board,
    and application directories are concatenated into a single
-   :file:`devicetree_fixups.h` file. :file:`dts_fixup.h` files are used to
-   rename generated macros to names expected by the source code.
-
-   Source code accesses preprocessor macros generated from devicetree by
-   including the :zephyr_file:`devicetree.h <include/devicetree.h>` header,
-   which includes :file:`devicetree_unfixed.h` and :file:`devicetree_fixups.h`.
+   :file:`devicetree_fixups.h` file. :file:`dts_fixup.h` files are a legacy
+   feature which should not be used in new code.
 
 Kconfig
    :file:`Kconfig` files define available configuration options for for the

doc/guides/build/index.rst

@@ -630,6 +630,11 @@ These are created in your application's build directory.
    Don't include the header files directly. :ref:`dt-from-c` explains
    what to do instead.
 
+:file:`<build>/zephyr/zephyr.dts.pre`
+   The preprocessed DTS source. This is an intermediate output file, which is
+   input to :file:`gen_defines.py` and used to create :file:`zephyr.dts` and
+   :file:`devicetree_unfixed.h`.
+
 :file:`<build>/zephyr/include/generated/devicetree_unfixed.h`
    The generated macros and additional comments describing the devicetree.
    Included by ``devicetree.h``.
@@ -639,10 +644,7 @@ These are created in your application's build directory.
    Included by ``devicetree.h``.
 
 :file:`<build>/zephyr/zephyr.dts`
-   The final merged devicetree. This file is output by :file:`gen_defines.py`
-   as a debugging aid, and is unused otherwise.
-
-:file:`<build>/zephyr/<BOARD>.dts.pre.tmp`
-   The preprocessed and concatenated DTS sources and overlays. This is an
-   intermediate output file, which is used to create :file:`zephyr.dts`
-   and :file:`devicetree_unfixed.h`.
+   The final merged devicetree. This file is output by :file:`gen_defines.py`.
+   It is useful for debugging any issues. If the devicetree compiler ``dtc`` is
+   installed, it is also run on this file, to catch any additional warnings or
+   errors.