doc: devicetree: Update outdated diagram and mention zephyr.dts

zephyr_dt_inputs_outputs.svg still shows the output from dtc being used,
but dtc is unused (except for finding warnings/errors) after the old
devicetree scripts were removed in commit c8c35f76ab ("scripts: dts:
Remove deprecated extract_dts_includes.py script").

Update zephyr_dt_inputs_outputs.svg to show how things are done now.
Also include the new zephyr.dts debugging aid in it. Tweak the
formatting a bit too.

Add zephyr.dts to the diagram in the build overview section too, and
mention zephyr.dts in the text of the devicetree and build overview
pages.

Remove zephyr_dt_inputs_outputs.png and use zephyr_dt_inputs_outputs.svg
directly. Many other places the documentation include SVGs directly, and
there haven't been any complaints, so it probably works fine. The .png
and .svg versions had also drifted out of sync.

Piggyback a link from the devicetree page to the build overview page, to
make it easier to discover.

(I used draw.io to update the diagrams.)

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
This commit is contained in:
Ulf Magnusson 2020-01-29 08:41:47 +01:00 committed by Kumar Gala
commit 6648fe428a
5 changed files with 23 additions and 8 deletions

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 45 KiB

Before After
Before After

View file

@ -41,6 +41,10 @@ Devicetree
parsed by :zephyr_file:`gen_defines.py <scripts/dts/gen_defines.py>` to
generate a :file:`devicetree_unfixed.h` header with preprocessor macros.
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.
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.

View file

@ -191,11 +191,16 @@ 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.
.. figure:: zephyr_dt_inputs_outputs.png
.. figure:: zephyr_dt_inputs_outputs.svg
:figclass: align-center
Devicetree input (green) and output (yellow) files
.. note::
For a higher-level overview over of the build, see :ref:`the build overview
<build_overview>`.
DTS files usually have a :file:`.dts`, :file:`.dtsi` (*i* for *include*), or
:file:`.overlay` extension. The C preprocessor is run on all devicetree files
to expand macro references. :file:`.dts` files usually include :file:`.dtsi`
@ -203,8 +208,8 @@ files via the C preprocessor with ``#include``.
.. note::
DTS also also has a native mechanism, ``/include/ "<filename>"``, for
including other files, though it is less commonly used.
DTS also has a native mechanism, ``/include/ "<filename>"``, for including
other files, though it is less commonly used.
Each board has a base devicetree, stored in the board's directory in
:file:`boards/` as :file:`<BOARD>.dts`. This base devicetree can be extended or
@ -228,9 +233,15 @@ from the base devicetree, if needed.
.. note::
The preprocessed and concatenated DTS sources are stored in
:file:`zephyr/<BOARD>.dts.pre.tmp` in the build directory. Looking at this
file can be handy for debugging.
These files in the build directory can be useful as a debugging aid when
working with devicetree:
zephyr/<BOARD>.dts.pre.tmp
The preprocessed and concatenated DTS sources
zephyr/zephyr.dts
The final merged devicetree. This file is specifically output as a
debugging aid, and is unused otherwise.
The merged devicetree, along with any :ref:`bindings <bindings>` referenced
from it, is used to generate C preprocessor macros. This is handled by the

Binary file not shown.

Before

Width:  |  Height:  |  Size: 70 KiB

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 23 KiB

Before After
Before After