michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: dts: clear up DTC_OVERLAY_FILE

Browse source 
Make it clearer that you can set it explicitly or the build system
will try to set it for you, and try to make it clearer what the build
system is doing when it tries to set it on your behalf.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2021-11-12 14:59:12 -08:00 • committed by Christopher Friedt
commit 46de74b8de
1 changed files with 21 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/guides/dts/howtos.rst
View file

@ -201,26 +201,30 @@ Set devicetree overlays
Devicetree overlays are explained in :ref:`devicetree-intro`. The CMake Devicetree overlays are explained in :ref:`devicetree-intro`. The CMake
variable :makevar:`DTC_OVERLAY_FILE` contains a space- or semicolon-separated variable :makevar:`DTC_OVERLAY_FILE` contains a space- or semicolon-separated
list of overlays. If :makevar:`DTC_OVERLAY_FILE` specifies multiple files, they list of overlay files to use. If :makevar:`DTC_OVERLAY_FILE` specifies multiple
are included in that order by the C preprocessor. files, they are included in that order by the C preprocessor.
Here are some ways to set it: You can set :makevar:`DTC_OVERLAY_FILE` to contain exactly the files you want
to use. Here is an example :ref:`using west build
<west-building-dtc-overlay-file>`.
1. on the cmake build command line If you don't set :makevar:`DTC_OVERLAY_FILE`, the build system will follow
(``-DDTC_OVERLAY_FILE="file1.overlay;file2.overlay"``) these steps, looking for files in your application source directory to use
#. with the CMake ``set()`` command in the application ``CMakeLists.txt``, as devicetree overlays:
before including zephyr's :file:`boilerplate.cmake` file
#. create a ``boards/<BOARD>_<revision>.overlay`` file in the application #. If the file :file:`boards/<BOARD>.overlay` exists, it will be used.
folder for the current board revision. This requires that the board supports #. If the current board has :ref:`multiple revisions <porting_board_revisions>`
multiple revisions, see :ref:`porting_board_revisions`. and :file:`boards/<BOARD>_<revision>.overlay` exists, it will be used.
The ``boards/<BOARD>_<revision>.overlay`` file will be merged with This file will be used in addition to :file:`boards/<BOARD>.overlay`
``boards/<BOARD>.overlay`` if this file also exists. if both exist.
#. create a ``boards/<BOARD>.overlay`` file in the application #. If one or more files have been found in the previous steps, the build system
folder, for the current board stops looking and just uses those files.
#. create a ``<BOARD>.overlay`` file in the application folder #. Otherwise, if :file:`<BOARD>.overlay` exists, it will be used, and the build
#. create an ``app.overlay`` file in the application folder system will stop looking for more files.
#. Otherwise, if :file:`app.overlay` exists, it will be used.
Using :ref:`shields` will also add devicetree overlay files.
Here is an example :ref:`using west build <west-building-dtc-overlay-file>`.
However you set the value, it is saved in the CMake cache between builds. However you set the value, it is saved in the CMake cache between builds.
The :ref:`build system <build_overview>` prints all the devicetree overlays it The :ref:`build system <build_overview>` prints all the devicetree overlays it