cmake: dts: Allow multiple overlay files
This patch changes the manner in which we collect DTS overlay files so that they comply with the same approach taken for configuration fragment files (.conf). Additionally it also documents the usage of those files in the Application Developer Guide. Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
This commit is contained in:
Carles Cufi
Anas Nashif
parent
6c2085bfed
commit
1cce63ae8f
|
|
@ -210,6 +210,22 @@ the configuration settings specified in an alternate .conf file using this param
|
|||
These settings will override the settings in the application’s .config file or its default .conf file.\
|
||||
Multiple files may be listed, e.g. CONF_FILE=\"prj1.conf prj2.conf\"")
|
||||
|
||||
if(DTC_OVERLAY_FILE)
|
||||
# DTC_OVERLAY_FILE has either been specified on the cmake CLI or is already
|
||||
# in the CMakeCache.txt. This has precedence over the environment
|
||||
# variable DTC_OVERLAY_FILE
|
||||
elseif(DEFINED ENV{DTC_OVERLAY_FILE})
|
||||
set(DTC_OVERLAY_FILE $ENV{DTC_OVERLAY_FILE})
|
||||
elseif(EXISTS ${APPLICATION_SOURCE_DIR}/${BOARD}.overlay)
|
||||
set(DTC_OVERLAY_FILE ${APPLICATION_SOURCE_DIR}/${BOARD}.overlay)
|
||||
endif()
|
||||
|
||||
set(DTC_OVERLAY_FILE ${DTC_OVERLAY_FILE} CACHE STRING "If desired, you can \
|
||||
build the application using the DT configuration settings specified in an \
|
||||
alternate .overlay file using this parameter. These settings will override the \
|
||||
settings in the board's .dts file. Multiple files may be listed, e.g. \
|
||||
DTC_OVERLAY_FILE=\"dts1.overlay dts2.overlay\"")
|
||||
|
||||
# Prevent CMake from testing the toolchain
|
||||
set(CMAKE_C_COMPILER_FORCED 1)
|
||||
set(CMAKE_CXX_COMPILER_FORCED 1)
|
||||
|
|
|
|||
|
|
@ -98,8 +98,9 @@ Follow these steps to create a new application directory. (Refer to
|
|||
cd app
|
||||
mkdir src
|
||||
|
||||
#. Create a :file:`CMakeLists.txt` file in your application directory with the
|
||||
following contents:
|
||||
#. Create an empty :file:`CMakeLists.txt` file in your application directory.
|
||||
|
||||
#. Include the :file:`boilerplate.cmake` to pull in the Zephyr build system:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
|
|
@ -117,15 +118,15 @@ Follow these steps to create a new application directory. (Refer to
|
|||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
#. Create one or more files containing your application's configuration
|
||||
options. Zephyr's configuration uses the same Kconfig system used by the
|
||||
Linux kernel, but with its own configuration tree.
|
||||
|
||||
If you followed the above steps, you can now create a file named
|
||||
``prj.conf`` in your application directory. It will be used automatically by
|
||||
the Zephyr build system.
|
||||
|
||||
More information on Zephyr configuration is available below.
|
||||
#. Configure features used by your application. Zephyr's configuration uses
|
||||
the same Kconfig and Device Tree systems used by the Linux kernel, but with
|
||||
its own configuration trees. Usually, you just create a file named
|
||||
:file:`prj.conf` in your application directory, where you enable or disable
|
||||
features provided by Zephyr's Kconfig configuration system. Optionally you
|
||||
can also configure any Device Tree overlays needed by your application
|
||||
(this is usually not necessary; see :ref:`application_dt` below for more
|
||||
details). You can use existing samples to get started. For more information,
|
||||
see :ref:`application_configuration` below.
|
||||
|
||||
Applications integrate with the Zephyr build system using the boilerplate code
|
||||
shown above in :file:`CMakeLists.txt`. The following important variables
|
||||
|
|
@ -147,6 +148,11 @@ configure the Zephyr build system:
|
|||
also be defined in the environment, in your application's
|
||||
:file:`CMakeLists.txt` file, or in the ``cmake`` command line.
|
||||
|
||||
* :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more Device Tree
|
||||
overlay files. Each file includes Device Tree values that
|
||||
override the default DT values. Like :makevar:`CONF_FILE`, this
|
||||
can also be defined in the environment, in your application's
|
||||
:file:`CMakeLists.txt` file, or in the ``cmake`` command line.
|
||||
|
||||
.. _build_an_application:
|
||||
|
||||
|
|
@ -560,7 +566,13 @@ Make sure to follow these steps in order.
|
|||
``YOUR_BOARD`` is a board name), add lines setting the
|
||||
:makevar:`CONF_FILE` variable to these files appropriately.
|
||||
|
||||
More details are available below in :ref:`application_configuration`.
|
||||
More details are available below in :ref:`application_kconfig`.
|
||||
|
||||
#. If your application uses a Device Tree 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 has its own kernel configuration options, add a
|
||||
line setting the location of the Kconfig file that defines them.
|
||||
|
|
@ -620,8 +632,13 @@ Below is a simple example :file:`CMakeList.txt`:
|
|||
Application Configuration
|
||||
*************************
|
||||
|
||||
.. _application_kconfig:
|
||||
|
||||
Kconfig Configuration
|
||||
=====================
|
||||
|
||||
The application is configured using a set of options that can be customized for
|
||||
application-specific purposes. The Zephyr build system takes a configuration
|
||||
application-specific purposes. The Zephyr build system takes a configuration
|
||||
option's value from the first source in which it is specified, taken from the
|
||||
following available sources, in order:
|
||||
|
||||
|
|
@ -641,11 +658,12 @@ following available sources, in order:
|
|||
the option in one of Zephyr's :file:`Kconfig` files).
|
||||
|
||||
The Zephyr build system determines a value for :makevar:`CONF_FILE` by
|
||||
checking the following, in order:
|
||||
checking the following until one is found, in order:
|
||||
|
||||
- Any value given to :makevar:`CONF_FILE` in your application
|
||||
:file:`CMakeLists.txt`, passed to the the CMake command line, or present
|
||||
in the CMake variable cache, takes precedence.
|
||||
:file:`CMakeLists.txt` (**before including the boilerplate.cmake file**),
|
||||
passed to the the CMake command line, or present in the CMake variable cache,
|
||||
takes precedence.
|
||||
|
||||
- If a CMake command, macro, or function ``set_conf_file`` is defined, it
|
||||
will be invoked and must set :makevar:`CONF_FILE`.
|
||||
|
|
@ -664,7 +682,7 @@ inter-dependencies between options, see the :ref:`configuration`.
|
|||
.. _application_set_conf:
|
||||
|
||||
Setting Application Configuration Values
|
||||
========================================
|
||||
----------------------------------------
|
||||
|
||||
This section describes how to edit Zephyr configuration
|
||||
(:file:`.conf`) files.
|
||||
|
|
@ -711,7 +729,7 @@ The example below shows a comment line and an override setting
|
|||
.. _override_kernel_conf:
|
||||
|
||||
Overriding Default Configuration
|
||||
================================
|
||||
--------------------------------
|
||||
|
||||
Follow these steps to override an application's configuration
|
||||
temporarily, perhaps to test the effect of a change.
|
||||
|
|
@ -868,6 +886,48 @@ preferred, since it correctly handles dependencies between options.
|
|||
#. Press :kbd:`Enter` to retire the menu display and return to the console
|
||||
command line.
|
||||
|
||||
.. _application_dt:
|
||||
|
||||
Device Tree Overlays
|
||||
====================
|
||||
|
||||
Zephyr uses Device Tree to describe the hardware it runs on. Sometimes it is
|
||||
necessary to modify the definitions in the :file:`.dts` files provided in the
|
||||
board folder in order to customize settings for a particular application.
|
||||
For more information on Device Tree see :ref:`device-tree`.
|
||||
|
||||
The Zephyr build system takes a Device Tree configuration
|
||||
option's value from the first source in which it is specified, taken from the
|
||||
following available sources, in order:
|
||||
|
||||
#. An application's current DT configuration (i.e. the file
|
||||
:file:`zephyr/<board>.dts.pre.tmp` in the build directory).
|
||||
|
||||
#. The application's DT configuration file(s) given by the
|
||||
:makevar:`DTC_OVERLAY_FILE` variable, either as set explicitly by the user
|
||||
or using one of the default values detailed below.
|
||||
|
||||
#. The board's default DT configuration for the current :makevar:`BOARD`
|
||||
setting (i.e. the :file:`boards/ARCHITECTURE/BOARD/BOARD.dts`
|
||||
file in the Zephyr base directory).
|
||||
|
||||
#. The kernel's default DT configuration settings (i.e. the default value given
|
||||
to the option in one of Zephyr's :file:`dtsi` files).
|
||||
|
||||
The Zephyr build system determines a value for :makevar:`DTC_OVERLAY_FILE` by
|
||||
checking the following until one is found, in order:
|
||||
|
||||
- Any value given to :makevar:`DTC_OVERLAY_FILE` in your application
|
||||
:file:`CMakeLists.txt` (**before including the boilerplate.cmake file**),
|
||||
passed to the the CMake command line, or present in the CMake variable cache,
|
||||
takes precedence
|
||||
|
||||
- If the file :file:`<board>.overlay` exists in your application directory,
|
||||
where ``BOARD`` is the BOARD value set earlier, it will be used.
|
||||
|
||||
If :makevar:`DTC_OVERLAY_FILE` specifies multiple files, they will be merged in
|
||||
order.
|
||||
|
||||
Application-Specific Code
|
||||
*************************
|
||||
|
||||
|
|
|
|||
|
|
@ -187,6 +187,14 @@ The following is a more precise list of required files:
|
|||
underlying DTS derived configuration #defines. Fixup files are temporary
|
||||
artifacts until additional DTS changes are made to make them unnecessary.
|
||||
|
||||
* Overlay Files (optional)
|
||||
|
||||
* Overlay files contain tweaks or changes to the SoC and Board support files
|
||||
described above. They can be used to modify Device Tree configurations
|
||||
without having to change the SoC and Board files. See
|
||||
:ref:`application_dt` for more information on overlay files and the Zephyr
|
||||
build system.
|
||||
|
||||
Adding support for device tree in drivers
|
||||
*****************************************
|
||||
|
||||
|
|
|
|||
|
|
@ -16,25 +16,22 @@ message(STATUS "Generating zephyr/include/generated/generated_dts_board.h")
|
|||
|
||||
if(CONFIG_HAS_DTS)
|
||||
|
||||
set(DTC_INCLUDE_FLAG_FOR_SOURCE
|
||||
-include ${DTS_SOURCE}
|
||||
)
|
||||
|
||||
if(NOT DTC_OVERLAY_FILE)
|
||||
# overlay file is not set, so try to use overlay dir instead.
|
||||
|
||||
set_ifndef(DTC_OVERLAY_DIR ${APPLICATION_SOURCE_DIR})
|
||||
|
||||
set(DTC_OVERLAY_FILE ${DTC_OVERLAY_DIR}/${BOARD_FAMILY}.overlay)
|
||||
if(DTC_OVERLAY_FILE)
|
||||
# Convert from space-separated files into file list
|
||||
string(REPLACE " " ";" DTC_OVERLAY_FILE_AS_LIST ${DTC_OVERLAY_FILE})
|
||||
endif()
|
||||
|
||||
if(EXISTS ${DTC_OVERLAY_FILE})
|
||||
set(DTC_INCLUDE_FLAG_FOR_OVERLAY
|
||||
-include ${DTC_OVERLAY_FILE}
|
||||
)
|
||||
else()
|
||||
unset(DTC_INCLUDE_FLAG_FOR_OVERLAY)
|
||||
endif()
|
||||
set(
|
||||
dts_files
|
||||
${DTS_SOURCE}
|
||||
${DTC_OVERLAY_FILE_AS_LIST}
|
||||
)
|
||||
|
||||
unset(DTC_INCLUDE_FLAG_FOR_DTS)
|
||||
foreach(dts_file ${dts_files})
|
||||
list(APPEND DTC_INCLUDE_FLAG_FOR_DTS
|
||||
-include ${dts_file})
|
||||
endforeach()
|
||||
|
||||
# TODO: Cut down on CMake configuration time by avoiding
|
||||
# regeneration of generated_dts_board.h on every configure. How
|
||||
|
|
@ -54,8 +51,7 @@ if(CONFIG_HAS_DTS)
|
|||
-isystem ${PROJECT_SOURCE_DIR}/dts/${ARCH}
|
||||
-isystem ${PROJECT_SOURCE_DIR}/dts
|
||||
-include ${AUTOCONF_H}
|
||||
${DTC_INCLUDE_FLAG_FOR_SOURCE} # include the DTS source
|
||||
${DTC_INCLUDE_FLAG_FOR_OVERLAY} # Possibly include an overlay after the source
|
||||
${DTC_INCLUDE_FLAG_FOR_DTS} # include the DTS source and overlays
|
||||
-I${PROJECT_SOURCE_DIR}/dts/common
|
||||
-I${PROJECT_SOURCE_DIR}/drivers
|
||||
-undef -D__DTS__
|
||||
|
|
|
|||
Loading…
Reference in a new issue