doc: config_and_build: regroup pages

Created "Configuring application" section with "Configuring devicetree". Moved devicetree related information under the devicetree section. The landing page reuses contents of Changing hardware config section. Created "Board support" section. Split information on former board support page into several pages. NCSDK-22324. Signed-off-by: Grzegorz Ferenc <[email protected]>
nrfconnect · Jan 15, 2024 · 1d68539 · 1d68539
1 parent a58ff6c
commit 1d68539
Show file tree

Hide file tree

Showing 17 changed files with 158 additions and 100 deletions.
diff --git a/applications/machine_learning/README.rst b/applications/machine_learning/README.rst
@@ -493,6 +493,8 @@ To start forwarding data to Edge Impulse studio:
 
          Sampling example
 
+.. _nrf_machine_learning_app_porting_guide:
+
 Porting guide
 *************
 

diff --git a/doc/_utils/redirects.py b/doc/_utils/redirects.py
@@ -20,6 +20,9 @@
     ("introduction", "index"),
     ("app_boards", "config_and_build/board_support"),
     ("app_dev/board_support/index", "config_and_build/board_support"),
+    ("config_and_build/board_support", "config_and_build/board_support/index"),
+    ("config_and_build/pin_control", "config_and_build/configure_app/hardware/pin_control"),
+    ("config_and_build/use_gpio_pin_directly", "config_and_build/configure_app/hardware/use_gpio_pin_directly"),
     ("ug_bootloader", "config_and_build/bootloaders_and_dfu/bootloader"),
     ("app_dev/bootloaders_and_dfu/bootloader", "config_and_build/bootloaders_and_dfu/bootloader"),
     ("app_dev/bootloaders_and_dfu/bootloader", "config_and_build/bootloaders/bootloader"),

diff --git a/doc/nrf/config_and_build.rst b/doc/nrf/config_and_build.rst
@@ -31,9 +31,8 @@ Make sure to consider :ref:`app_bootloaders` and :ref:`app_dfu` already at this
    :caption: Subpages:
 
    config_and_build/config_and_build_system
-   config_and_build/board_support
-   config_and_build/pin_control
-   config_and_build/use_gpio_pin_directly
+   config_and_build/board_support/index
+   config_and_build/configuring_app/hardware/index
    config_and_build/programming
    config_and_build/output_build_files
    config_and_build/modifying

diff --git a/doc/nrf/config_and_build/board_support.rst → ...g_and_build/board_support/board_names.rst b/doc/nrf/config_and_build/board_support.rst → ...g_and_build/board_support/board_names.rst
@@ -1,21 +1,13 @@
-.. _app_boards:
+.. _app_boards_names:
+.. _programming_board_names:
 
-Board support
-#############
+Board names
+###########
 
 .. contents::
    :local:
    :depth: 2
 
-The |NCS| provides board definitions for all Nordic Semiconductor devices.
-In addition, you can define custom boards.
-
-.. _app_boards_names:
-.. _programming_board_names:
-
-Board names
-***********
-
 The following tables list all boards and build targets for Nordic Semiconductor's hardware platforms.
 
 The build target column uses several entries for multi-core hardware platforms:
@@ -32,12 +24,12 @@ The build target column uses several entries for multi-core hardware platforms:
     The application core firmware is placed in Non-Secure Processing Environment (NSPE) and uses Secure Processing Environment (SPE) for security features.
     By default, the build system automatically includes :ref:`Trusted Firmware-M (TF-M) <ug_tfm>` in SPE and merges it with NSPE.
 
-Read more about separation of processing environments in the :ref:`app_boards_spe_nspe` section.
+Read more about separation of processing environments on the :ref:`app_boards_spe_nspe` page.
 
 .. _app_boards_names_zephyr:
 
 Boards included in sdk-zephyr
-=============================
+*****************************
 
 The following boards are defined in the :file:`zephyr/boards/arm/` folder.
 Also see the :ref:`zephyr:boards` section in the Zephyr documentation.
@@ -101,7 +93,7 @@ Also see the :ref:`zephyr:boards` section in the Zephyr documentation.
 .. _app_boards_names_nrf:
 
 Boards included in sdk-nrf
-==========================
+**************************
 
 The following boards are defined in the :file:`nrf/boards/arm/` folder.
 
@@ -140,71 +132,3 @@ The following boards are defined in the :file:`nrf/boards/arm/` folder.
 +-------------------+------------+----------------------------------------------------------+---------------------------------------+
 
 The :ref:`nRF21540 EK shield <ug_radio_fem_nrf21540ek>` is defined in the :file:`nrf/boards/shields` folder.
-
-Custom boards
-*************
-
-Defining your own board is a very common step in application development, because applications are typically designed to run on boards that are not directly supported by the |NCS|, and are often custom designs not available publicly.
-To define your own board, you can use the following Zephyr guides as reference, since boards are defined in the |NCS| just as they are in Zephyr:
-
-* :ref:`custom_board_definition` is a guide to adding your own custom board to the Zephyr build system.
-* :ref:`board_porting_guide` is a complete guide to porting Zephyr to your own board.
-
-One of the |NCS| applications that lets you add custom boards is :ref:`nrf_desktop`.
-See :ref:`nrf_desktop_porting_guide` in the application documentation for details.
-
-.. _app_boards_spe_nspe:
-
-Processing environments
-***********************
-
-The build target column in the tables above separates entries according to the CPU to target (for multi-core SoCs) and whether Cortex-M Security Extensions (CMSE) are used or not (addition of ``_ns`` if they are used).
-
-When CMSE is used, the firmware is split in accordance with the security by separation architecture principle to better protect sensitive assets and code.
-With CMSE, the firmware is stored in one of two security environments (flash partitions), either Secure Processing Environment (SPE) or Non-Secure Processing Environment (NSPE).
-This isolation of firmware is only possible if the underlying hardware supports `ARM TrustZone`_.
-
-.. figure:: images/spe_nspe.svg
-   :alt: Processing environments in the |NCS|
-
-   Processing environments in the |NCS|
-
-In Zephyr and the |NCS|, SPE and NSPE are used exclusively in the context of the application core of a multi-core SoC.
-Building follows the security by separation principle and depends on the build target.
-
-.. _app_boards_spe_nspe_cpuapp:
-
-Building for ``cpuapp`` (CMSE disabled)
-=======================================
-
-When you build for ``cpuapp``, you build the firmware for the application core without CMSE.
-Because CMSE is disabled, TF-M is not used and there is no separation of firmware.
-
-.. _app_boards_spe_nspe_cpuapp_ns:
-
-Building for ``*_ns`` (CMSE enabled)
-====================================
-
-When you build for ``*_ns``, you build firmware with CMSE.
-Firmware is separated in the following way:
-
-* SPE implements security-critical functionality and data (including bootloaders) and isolates them from the application software in NSPE.
-  It also contains secure firmware running in the secure state.
-* NSPE typically implements the user application and communication firmware, among other major components.
-
-The application is built as a non-secure image and :ref:`Trusted Firmware-M (TF-M) <ug_tfm>` is built as the secure image.
-The build system merges both images to form a combined image that will be used for programming or updating the device.
-
-TF-M enables hardware-supported separation of firmware.
-It also implements `Platform Security Architecture (PSA)`_ API, which provides security features for the system, including roots of trust for protecting secrets, platform state, and cryptographic keys.
-The API coordinates the communication with the components in NSPE.
-
-More information about SPE and NSPE
------------------------------------
-
-Read the following pages for a better understanding of security by separation in the |NCS|:
-
-* :ref:`ug_tfm`
-* :ref:`debugging_spe_nspe`
-* `An Introduction to Trusted Firmware-M (TF-M)`_ on DevZone
-* `TF-M documentation`_
diff --git a/doc/nrf/config_and_build/board_support/defining_custom_board.rst b/doc/nrf/config_and_build/board_support/defining_custom_board.rst
@@ -0,0 +1,29 @@
+.. _defining_custom_board:
+
+Defining custom board
+#####################
+
+Defining your own board is a very common step in application development, because applications are typically designed to run on boards that are not directly supported by the |NCS|, and are often custom designs not available publicly.
+
+Guidelines for custom boards
+****************************
+
+To define your own board, you can use the following Zephyr guides as reference, since boards are defined in the |NCS| just as they are in Zephyr:
+
+* :ref:`custom_board_definition` is a guide to adding your own custom board to the Zephyr build system.
+* :ref:`board_porting_guide` is a complete guide to porting Zephyr to your own board.
+
+Adding a custom board in the |nRFVSC|
+*************************************
+
+The |nRFVSC| lets you add your own boards to your |NCS| project.
+Read the `How to work with boards and devices`_ page in the extension documentation for detailed steps.
+
+Application porting guides
+**************************
+
+Some :ref:`applications` in the |NCS| provide detailed guides for adapting the application to custom boards:
+
+* :ref:`nrf_desktop` - See :ref:`nrf_desktop_porting_guide` in the application documentation.
+* :ref:`nrf53_audio_app` - See :ref:`nrf53_audio_app_adapting` in the application documentation.
+* :ref:`nrf_machine_learning_app` - See :ref:`nrf_machine_learning_app_porting_guide` in the application documentation.
diff --git a/doc/nrf/config_and_build/images/spe_nspe.svg → ...d_build/board_support/images/spe_nspe.svg b/doc/nrf/config_and_build/images/spe_nspe.svg → ...d_build/board_support/images/spe_nspe.svg
diff --git a/doc/nrf/config_and_build/board_support/index.rst b/doc/nrf/config_and_build/board_support/index.rst
@@ -0,0 +1,19 @@
+.. _app_boards:
+
+Board support
+#############
+
+The |NCS| provides board definitions for all Nordic Semiconductor devices.
+These are in tables on the :ref:`app_boards_names` page, listed by :ref:`app_boards_names_zephyr`, :ref:`app_boards_names_nrf`, and :ref:`shield_names_nrf`.
+
+Some boards can support Cortex-M Security Extensions (CMSE), which results in separation of :ref:`app_boards_spe_nspe`.
+
+In addition, you can :ref:`define custom boards <defining_custom_board>`.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages:
+
+   board_names
+   processing_environments
+   defining_custom_board
diff --git a/doc/nrf/config_and_build/board_support/processing_environments.rst b/doc/nrf/config_and_build/board_support/processing_environments.rst
@@ -0,0 +1,59 @@
+.. _app_boards_spe_nspe:
+
+Processing environments
+#######################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The :ref:`boards supported by the SDK <app_boards_names>` distinguish entries according to the CPU to target (for multi-core SoCs) and whether Cortex-M Security Extensions (CMSE) are used or not (addition of ``_ns`` if they are used).
+
+When CMSE is used, the firmware is split in accordance with the security by separation architecture principle to better protect sensitive assets and code.
+With CMSE, the firmware is stored in one of two security environments (flash partitions), either Secure Processing Environment (SPE) or Non-Secure Processing Environment (NSPE).
+This isolation of firmware is only possible if the underlying hardware supports `ARM TrustZone`_.
+
+.. figure:: images/spe_nspe.svg
+   :alt: Processing environments in the |NCS|
+
+   Processing environments in the |NCS|
+
+In Zephyr and the |NCS|, SPE and NSPE are used exclusively in the context of the application core of a multi-core SoC.
+Building follows the security by separation principle and depends on the build target.
+
+.. _app_boards_spe_nspe_cpuapp:
+
+Building for ``cpuapp`` (CMSE disabled)
+***************************************
+
+When you build for ``cpuapp``, you build the firmware for the application core without CMSE.
+Because CMSE is disabled, TF-M is not used and there is no separation of firmware.
+
+.. _app_boards_spe_nspe_cpuapp_ns:
+
+Building for ``*_ns`` (CMSE enabled)
+************************************
+
+When you build for ``*_ns``, you build firmware with CMSE.
+Firmware is separated in the following way:
+
+* SPE implements security-critical functionality and data (including bootloaders) and isolates them from the application software in NSPE.
+  It also contains secure firmware running in the secure state.
+* NSPE typically implements the user application and communication firmware, among other major components.
+
+The application is built as a non-secure image and :ref:`Trusted Firmware-M (TF-M) <ug_tfm>` is built as the secure image.
+The build system merges both images to form a combined image that will be used for programming or updating the device.
+
+TF-M enables hardware-supported separation of firmware.
+It also implements `Platform Security Architecture (PSA)`_ API, which provides security features for the system, including roots of trust for protecting secrets, platform state, and cryptographic keys.
+The API coordinates the communication with the components in NSPE.
+
+More information about SPE and NSPE
+===================================
+
+Read the following pages for a better understanding of security by separation in the |NCS|:
+
+* :ref:`ug_tfm`
+* :ref:`debugging_spe_nspe`
+* `An Introduction to Trusted Firmware-M (TF-M)`_ on DevZone
+* `TF-M documentation`_
diff --git a/doc/nrf/config_and_build/config_and_build_system.rst b/doc/nrf/config_and_build/config_and_build_system.rst
@@ -94,7 +94,7 @@ The preprocessed devicetree sources are parsed by the :file:`zephyr/scripts/dts/
 The :file:`zephyr.dts` file contains the entire hardware-related configuration of the system in the devicetree format.
 The header file contains the same kind of information, but with defines usable by source code.
 
-For more information, see :ref:`configure_application` and Zephyr's :ref:`zephyr:dt-guide`.
+For more information, see :ref:`configuring_devicetree` and Zephyr's :ref:`zephyr:dt-guide`.
 In particular, :ref:`zephyr:set-devicetree-overlays` explains how to use devicetree and its overlays to customize an application's devicetree.
 
 .. _configure_application_sw:

diff --git a/doc/nrf/config_and_build/configuring_app/hardware/index.rst b/doc/nrf/config_and_build/configuring_app/hardware/index.rst
@@ -0,0 +1,21 @@
+.. _configuring_devicetree:
+
+Configuring devicetree
+######################
+
+The |nRFVSC| is the recommended tool for editing :ref:`configure_application_hw`.
+The extension offers several layers of `Devicetree integration <Devicetree support overview_>`_, ranging from summarizing devicetree settings in a menu and providing devicetree language support in the editor, to the Devicetree Visual Editor, a GUI tool for editing devicetree files.
+Follow the steps in `How to create devicetree files`_ and use one of the following options to edit the :file:`.dts`, :file:`.dtsi`, and :file:`.overlay` files:
+
+* `Devicetree Visual Editor <How to work with Devicetree Visual Editor_>`_
+* `Devicetree language support`_
+
+The following guides provide information about configuring specific aspects of hardware support related to devicetree.
+Read them together with Zephyr's :ref:`zephyr:hardware_support` and :ref:`zephyr:dt-guide` guides.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Subpages:
+
+   pin_control
+   use_gpio_pin_directly
diff --git a/doc/nrf/config_and_build/pin_control.rst → .../configuring_app/hardware/pin_control.rst b/doc/nrf/config_and_build/pin_control.rst → .../configuring_app/hardware/pin_control.rst
diff --git a/...onfig_and_build/use_gpio_pin_directly.rst → ...ng_app/hardware/use_gpio_pin_directly.rst b/...onfig_and_build/use_gpio_pin_directly.rst → ...ng_app/hardware/use_gpio_pin_directly.rst
diff --git a/doc/nrf/config_and_build/modifying.rst b/doc/nrf/config_and_build/modifying.rst
@@ -68,18 +68,7 @@ There are different ways of doing this, but not all will store your configuratio
 Changing the hardware configuration
 ===================================
 
-To correctly edit the :file:`.dts` and :file:`.overlay` files for your project, you need to be familiar with the :ref:`Devicetree language and syntax <zephyr:dt-guide>`.
-
-.. tabs::
-
-   .. group-tab:: nRF Connect for VS Code
-
-      The |nRFVSC| offers several layers of `Devicetree integration <Devicetree support overview_>`_, ranging from summarizing devicetree settings in a menu and providing devicetree language support in the editor, to the Devicetree Visual Editor, a GUI tool for editing devicetree files.
-      Follow the steps in `How to create devicetree files`_ and use one of the following options to edit the :file:`.dts` and :file:`.overlay` files:
-
-      * `Devicetree Visual Editor <How to work with Devicetree Visual Editor_>`_
-      * `Devicetree language support`_
-
+See :ref:`configuring_devicetree`.
 
 Changing the software configuration
 ===================================

diff --git a/doc/nrf/dev_model_and_contributions/adding_code.rst b/doc/nrf/dev_model_and_contributions/adding_code.rst
@@ -124,7 +124,7 @@ This repository showcases the following features of both the |NCS| and Zephyr:
 * Basic :ref:`Zephyr application <zephyr:application>` skeleton
 * :ref:`Zephyr workspace applications <zephyr:zephyr-workspace-app>`
 * :ref:`West T2 topology <zephyr:west-t2>`
-* :ref:`Custom boards <zephyr:board_porting_guide>`
+* :ref:`Custom boards <defining_custom_board>`
 * Custom :ref:`devicetree bindings <zephyr:dt-bindings>`
 * Out-of-tree :ref:`drivers <zephyr:device_model_api>`
 * Out-of-tree libraries

diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -195,6 +195,7 @@
 .. _`How to work with Devicetree Visual Editor`: https://nrfconnect.github.io/vscode-nrf-connect/guides/work_with_devicetree_editor.html
 .. _`Devicetree support overview`: https://nrfconnect.github.io/vscode-nrf-connect/guides/ncs_configure_app.html#devicetree-overview
 .. _`Devicetree language support`: https://nrfconnect.github.io/vscode-nrf-connect/guides/ncs_configure_app.html#devicetree-language-support
+.. _`How to work with boards and devices`: https://nrfconnect.github.io/vscode-nrf-connect/guides/bd_work_with_boards.html
 .. _`How to install the extension`:
 .. _`Installing on Linux`: https://nrfconnect.github.io/vscode-nrf-connect/get_started/install.html
 .. _`How to build an application`: https://nrfconnect.github.io/vscode-nrf-connect/get_started/build_app_ncs.html

diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -843,6 +843,8 @@ Documentation
 
     * :ref:`app_build_system` gathers conceptual information about the build and configuration system previously listed on several other pages.
       The :ref:`app_build_additions` section on this page now provides more information about :ref:`app_build_additions_build_types` specific to the |NCS|.
+    * :ref:`app_boards` is now a section and its contents have been moved to several subpages.
+    * New :ref:`configuring_devicetree` subsection now groups guides related to configuration of hardware using the devicetree language.
     * New reference page :ref:`app_build_output_files` gathers information previously listed on several other pages.
     * :ref:`app_dfu` and :ref:`app_bootloaders` are now separate sections, with the DFU section summarizing the available DFU methods in a table.
 

diff --git a/doc/tags.yml b/doc/tags.yml
@@ -36,6 +36,16 @@ mapping_topics:
                                   "thingy53", "nrf52840", "nrf52833", "nrf52832", "nrf52820",
                                   "nrf52811", "nrf52810", "nrf52805", "nrf21540", "npm1100",
                                   "npm1300", "npm6001"]
+  - nrf/config_and_build/configuring_app/*.html: ["applications", "samples", "development-kits",
+                                                  "evaluation-kits", "prototyping-platforms"]
+  - nrf/config_and_build/board_support/*.html: ["nrf91-series", "nrf70-series", "nrf53-series",
+                                                "nrf52-series", "nrf7002", "nrf7001", "nrf7000",
+                                                "nrf9160", "thingy91", "nrf5340", "thingy53",
+                                                "nrf52840", "nrf52833", "nrf52832", "nrf52820",
+                                                "nrf52811", "nrf52810", "nrf52805", "nrf21540",
+                                                "npm1100", "npm1300", "npm6001"]
+  - nrf/config_and_build/configuring_app/hardware/*.html: ["applications", "samples",
+                                                           "nrf-connect-vsc"]
   - nrf/config_and_build/programming.html: ["applications", "samples", "development-kits",
                                             "evaluation-kits", "prototyping-platforms"]
   - nrf/config_and_build/modifying.html: ["applications", "samples", "kconfig", "nrf-connect-vsc"]