doc: build: Add details on SoC overlays

Adds details about Kconfig fragments and devicetree overlay files that will be included in a build if they are found in the ``socs`` folder Signed-off-by: Jamie McCrae <[email protected]>
nordicjm · Apr 29, 2024 · af46765 · af46765
1 parent da3007e
commit af46765
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 5 deletions.
diff --git a/doc/build/dts/howtos.rst b/doc/build/dts/howtos.rst
@@ -237,11 +237,10 @@ If you don't set :makevar:`DTC_OVERLAY_FILE`, the build system will follow
 these steps, looking for files in your application configuration directory to
 use as devicetree overlays:
 
-#. If the file :file:`boards/<BOARD>.overlay` exists, it will be used.
+#. If the file :file:`socs/<SOC>_<BOARD_QUALIFIERS>.overlay` exists, it will be used.
+#. If the file :file:`boards/<BOARD>.overlay` exists, it will be used in addition to the above.
 #. If the current board has :ref:`multiple revisions <porting_board_revisions>`
-   and :file:`boards/<BOARD>_<revision>.overlay` exists, it will be used.
-   This file will be used in addition to :file:`boards/<BOARD>.overlay`
-   if both exist.
+   and :file:`boards/<BOARD>_<revision>.overlay` exists, it will be used in addition to the above.
 #. If one or more files have been found in the previous steps, the build system
    stops looking and just uses those files.
 #. Otherwise, if :file:`<BOARD>.overlay` exists, it will be used, and the build

diff --git a/doc/build/kconfig/setting.rst b/doc/build/kconfig/setting.rst
@@ -153,7 +153,8 @@ used.
    form :file:`prj_<build>.conf` and if file
    :file:`boards/<BOARD>_<build>.conf` exists in same folder as file
    :file:`prj_<build>.conf`, the result of merging :file:`prj_<build>.conf` and
-   :file:`boards/<BOARD>_<build>.conf` is used.
+   :file:`boards/<BOARD>_<build>.conf` is used - note that this feature is
+   deprecated, :ref:`application-file-suffixes` should be used instead.
 
 #. Otherwise, if :file:`boards/<BOARD>.conf` exists in the application
    configuration directory, the result of merging it with :file:`prj.conf` is
@@ -167,6 +168,11 @@ used.
 #. Otherwise, :file:`prj.conf` is used from the application configuration
    directory. If it does not exist then a fatal error will be emitted.
 
+Furthermore, applications can have SoC overlay configuration that is applied to
+it, the file :file:`socs/<SOC>_<BOARD_QUALIFIERS>.conf` will be applied if it exists,
+after the main project configuration has been applied and before any board overlay
+configuration files have been applied.
+
 All configuration files will be taken from the application's configuration
 directory except for files with an absolute path that are given with the
 ``CONF_FILE``, ``EXTRA_CONF_FILE``, ``DTC_OVERLAY_FILE``, and