doc: sysbuild + HWMv2 + misc edits

Added a note about transition to HWMv2 under Board names. Aligned mentions of sysbuild. Added sysbuild-specific mentions to programming and building info. Removed unused include files for build_and_run. Fixed documentation formatting for SUIT recovery. Fixed a couple of outdated *board_name* to *board_target*. Signed-off-by: Grzegorz Ferenc <[email protected]>
nrfconnect · Jun 11, 2024 · f34eb7f · f34eb7f
1 parent 7421715
commit f34eb7f
Show file tree

Hide file tree

Showing 28 changed files with 143 additions and 147 deletions.
diff --git a/applications/ipc_radio/README.rst b/applications/ipc_radio/README.rst
@@ -47,10 +47,7 @@ The firmware supports the following development kits:
 
 .. table-from-sample-yaml::
 
-To automatically attach the firmware image, you need to use Zephyr's :ref:`zephyr:sysbuild`.
-
-The |nRFVSC| supports sysbuild during `build configuration setup <How to build an application_>`_.
-To learn more about sysbuild in the extension, see `sysbuild support`_ page in its documentation.
+To automatically attach the firmware image, you need to use :ref:`configuration_system_overview_sysbuild`.
 
 Configuration
 *************
@@ -76,12 +73,12 @@ The Bluetooth Low Energy and IEEE 802.15.4 functionalities can operate simultane
 .. note::
    The IEEE 802.15.4 is currently not supported on the :ref:`zephyr:nrf54h20dk_nrf54h20` board.
 
-Sysbuild
-========
+Sysbuild Kconfig options
+========================
 
-To enable the firmware, use the Sysbuild configuration of :kconfig:option:`SB_CONFIG_NRF_DEFAULT_IPC_RADIO`.
+To enable the firmware, use the sysbuild configuration of :kconfig:option:`SB_CONFIG_NRF_DEFAULT_IPC_RADIO`.
 
-You can set the supported radio configurations using the following (Sysbuild) Kconfig options:
+You can set the supported radio configurations using the following sysbuild Kconfig options:
 
 * :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_BT_HCI_IPC`
 * :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_BT_RPC`
@@ -100,10 +97,10 @@ The following files are available:
 * :file:`overlay-bt_rpc.conf` - Configuration file enabling Bluetooth Low Energy over RPC.
 
 .. note::
-   When you use sysbuild to build an application which uses the ipc_radio as network core image the preceding configuration files are added automatically to ipc_radio.
-   The selection of specific configuration files is determined by the sysbuild kconfig.
+   When you use sysbuild to build an application which uses the IPC radio firmware as the network or radio core image, the preceding configuration files are added automatically to the IPC radio firmware.
+   The selection of specific configuration files is determined by the sysbuild Kconfig.
 
-   For instance the :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_IEEE802154` kconfig enables the :file:`overlay-802154.conf` configuration file to be used with ipc_radio.
+   For instance, the :kconfig:option:`SB_CONFIG_NETCORE_IPC_RADIO_IEEE802154` Kconfig option enables the :file:`overlay-802154.conf` configuration file to be used with the IPC radio firmware.
 
 Building and running as a single image
 **************************************

diff --git a/doc/nrf/config_and_build/board_support/board_names.rst b/doc/nrf/config_and_build/board_support/board_names.rst
@@ -43,6 +43,10 @@ While the board name is always present, other elements, such as the board revisi
 
   Read more about separation of processing environments on the :ref:`app_boards_spe_nspe` page.
 
+.. important::
+    This board name scheme was introduced in the |NCS| before the v2.7.0 release following changes in Zephyr v3.6.0.
+    Read Zephyr's :ref:`zephyr:hw_model_v2` and refer to `conversion example Pull Request`_ in Zephyr upstream if you have to port a board to the new model.
+
 .. _app_boards_names_zephyr:
 
 Boards included in sdk-zephyr

diff --git a/doc/nrf/config_and_build/config_and_build_system.rst b/doc/nrf/config_and_build/config_and_build_system.rst
@@ -5,7 +5,7 @@ Build and configuration system
 
 .. contents::
    :local:
-   :depth: 2
+   :depth: 3
 
 The |NCS| build and configuration system is based on the one from Zephyr, with some additions.
 
@@ -214,7 +214,7 @@ To read about each of these stages, see :ref:`zephyr:cmake-details` in the Zephy
 Sysbuild
 ========
 
-The |NCS| supports Zephyr's System Build (Sysbuild).
+The |NCS| supports Zephyr's System Build (sysbuild).
 
 .. ncs-include:: build/sysbuild/index.rst
    :docset: zephyr
@@ -227,6 +227,9 @@ For example, sysbuild-specific Kconfig options are preceded by `SB_` before `CON
 Sysbuild is integrated with west.
 The sysbuild build configuration is generated using the sysbuild's :file:`CMakeLists.txt` file (which provides information about each underlying build system and CMake variables) and the sysbuild's Kconfig options (which are gathered in the :file:`sysbuild.conf` file).
 
+.. note::
+    In the |NCS|, building with sysbuild is :ref:`enabled by default <sysbuild_enabled_ncs>`.
+
 For more information about sysbuild, see the :ref:`documentation in Zephyr <zephyr:sysbuild>`.
 
 .. _app_build_additions:
@@ -255,6 +258,16 @@ For example, when building a sample that enables :kconfig:option:`CONFIG_BT_EXT_
 
 To disable these warnings, disable the :kconfig:option:`CONFIG_WARN_EXPERIMENTAL` Kconfig option.
 
+.. _sysbuild_enabled_ncs:
+
+Sysbuild enabled by default
+===========================
+
+In the |NCS|, building an application using the :ref:`standard building procedure <building>` automatically includes :ref:`configuration_system_overview_sysbuild` (the ``--sysbuild`` parameter).
+For this reason, unlike in Zephyr, ``--sysbuild`` does not have to be explicitly mentioned in the command prompt.
+
+You can disable building with sysbuild by using the ``--no-sysbuild`` parameter in the build command.
+
 .. _app_build_additions_build_types:
 .. _gs_modifying_build_types:
 .. _modifying_build_types:

diff --git a/doc/nrf/config_and_build/configuring_app/advanced_building.rst b/doc/nrf/config_and_build/configuring_app/advanced_building.rst
@@ -31,18 +31,24 @@ Common sample components for development
 
 To learn more about how to use the :kconfig:option:`CONFIG_NCS_SAMPLE_MCUMGR_BT_OTA_DFU` Kconfig option, see the respective device guides for :ref:`nRF52 Series <ug_nrf52_developing_ble_fota>` and the :ref:`nRF5340 DK <ug_nrf53_developing_ble_fota>`.
 
+.. _optional_build_parameters:
+
 Optional build parameters
 *************************
 
 Here are some of the possible options you can use:
 
 * You can provide :ref:`custom CMake options <cmake_options>` to the build command.
+* You can pass ``--no-sysbuild`` to ``west build`` to build without :ref:`configuration_system_overview_sysbuild`.
+  (In the |NCS|, :ref:`building with sysbuild is enabled by default <sysbuild_enabled_ncs>`.)
 * You can include the *directory_name* parameter to build from a directory other than the current directory.
 * You can specify a *destination_directory_name* parameter to choose where the build files are generated.
   If not specified, the build files are automatically generated in :file:`build/zephyr/`.
 * You can :ref:`start menuconfig with the west command <configuration_temporary_change>` to configure your application.
 * You can :ref:`reuse an existing build directory <zephyr:west-building-pristine>` for building another application for another board or board target by passing ``-p=auto`` to ``west build``.
 * You can :ref:`run unit tests with the west command <running_unit_tests>` with the ``-t run`` parameter from the unit test directory.
+* You can use the ``--domain`` parameter to :ref:`build for a single domain <zephyr:west-multi-domain-builds>`.
+  This parameter can also be used for :ref:`programming <zephyr:west-multi-domain-flashing>` and :ref:`debugging <zephyr:west-multi-domain-debugging>` multiple domains.
 
 For more information on other optional build parameters, run the ``west build -h`` help text command.
 

diff --git a/doc/nrf/config_and_build/configuring_app/index.rst b/doc/nrf/config_and_build/configuring_app/index.rst
@@ -23,6 +23,8 @@ Just as for creating the application, you can build the application using either
       By default, the extension runs both stages of the CMake build (:ref:`configuration phase and building phase <app_build_system>`).
       If you want to only set up the build configuration without building it, make sure the :guilabel:`Build after generating configuration` is not selected.
 
+      To build with :ref:`configuration_system_overview_sysbuild`, select the :guilabel:`Use sysbuild` checkbox.
+
       If you want to build with custom options or scripts, read about `Binding custom tasks to actions`_ in the extension documentation.
 
       .. note::
@@ -53,9 +55,12 @@ Just as for creating the application, you can build the application using either
          See :ref:`programming_board_names` for more information on the supported boards and board targets.
          The board targets supported for a given application are always listed in its requirements section.
 
-         After running the ``west build`` command, the build files can be found in :file:`build/zephyr`.
-         |output_files_note|
-         For more information on the contents of the build directory, see :ref:`zephyr:build-directory-contents` in the Zephyr documentation.
+         In the |NCS|, this command builds the application with :ref:`sysbuild enabled by default <sysbuild_enabled_ncs>`.
+         It can be expanded with :ref:`optional_build_parameters`, such as :ref:`custom CMake options <cmake_options>` or the ``--no-sysbuild`` parameter that disables building with sysbuild.
+
+       After running the ``west build`` command, the build files can be found in :file:`build/zephyr` by default.
+       |output_files_note|
+       For more information on the contents of the build directory, see :ref:`zephyr:build-directory-contents` in the Zephyr documentation.
 
        For more information on building using the command line, see :ref:`Building <zephyr:west-building>` in the Zephyr documentation.
 

diff --git a/doc/nrf/config_and_build/programming.rst b/doc/nrf/config_and_build/programming.rst
@@ -18,6 +18,9 @@ To program the :ref:`output build files <app_build_output_files>` to your device
 
 .. include:: ../includes/vsc_build_and_run_series.txt
 
+The flash command programs all cores by default, both in the |nRFVSC| and on the command line.
+If you want to program only one selected core, use ``west flash`` on the command line and :ref:`specify the domain <zephyr:west-multi-domain-flashing>`.
+
 .. _programming_hw:
 
 Hardware-specific programming steps
@@ -38,6 +41,8 @@ Optional programming parameters
 *******************************
 
 You can customize the basic ``west flash`` command in a variety of ways.
+The following are most common in the |NCS|.
+For more options, see Zephyr's :ref:`zephyr:west-flashing`.
 
 .. _programming_params_no_erase:
 

diff --git a/doc/nrf/device_guides/nrf91/nrf91_snippet.rst b/doc/nrf/device_guides/nrf91/nrf91_snippet.rst
@@ -58,7 +58,7 @@ To add the modem trace UART snippet when building an application with west, use
    west build --board <your_board> -- -D<image_name>_SNIPPET="nrf91-modem-trace-uart"
 
 .. note::
-   With Sysbuild, using the ``west build -S`` option applies the snippet to all images.
+   With :ref:`sysbuild <configuration_system_overview_sysbuild>`, using the ``west build -S`` option applies the snippet to all images.
    Therefore, use the CMake argument instead, specifying the application image.
 
 With CMake

diff --git a/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst b/doc/nrf/device_guides/working_with_nrf/nrf54h/ug_nrf54h20_suit_external_memory.rst
@@ -56,8 +56,8 @@ To enable the external memory, you must add the ``-DFILE_SUFFIX="extflash"`` arg
    .. note::
       This step is needed only on nRF54H20 DK. Skip this step if you are using different hardware.
 
-#. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` Sysbuild Kconfig option, which enables the build of the reference companion image.
-   See the :ref:`suit_flash_companion` user guide for instructions on how to configure the companion image using Sysbuild.
+#. Enable the :kconfig:option:`SB_CONFIG_SUIT_BUILD_FLASH_COMPANION` sysbuild Kconfig option, which enables the build of the reference companion image.
+   See the :ref:`suit_flash_companion` user guide for instructions on how to configure the companion image using sysbuild.
 
 #. Define a new DFU cache partition in the external memory in the DTS file:
 
@@ -124,10 +124,10 @@ To enable the external memory, you must add the ``-DFILE_SUFFIX="extflash"`` arg
 
    .. code-block:: console
 
-      $ west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild
+      $ west build -b nrf54h20dk/nrf54h20/cpuapp
       $ west flash
 
-   The build system will automatically generate a :file:`build/suit.zip` archive, which contains the SUIT envelope and candidate images.
+   The build system will automatically use :ref:`configuration_system_overview_sysbuild` and generate a :file:`build/suit.zip` archive, which contains the SUIT envelope and candidate images.
 
 #. Build a new version of the application with the incremented :kconfig:option:`SB_CONFIG_SUIT_ENVELOPE_SEQUENCE_NUM` value.
 

diff --git a/doc/nrf/includes/application_build_and_run.txt b/doc/nrf/includes/application_build_and_run.txt
@@ -1,4 +1,7 @@
 This application can be found under |application path| in the |NCS| folder structure.
 
-To build the application with |VSC|, follow the steps listed on the `How to build an application`_ page in the |nRFVSC| documentation.
-See :ref:`building` for other building scenarios, :ref:`programming` for programming steps, and :ref:`testing` for general information about testing and debugging in the |NCS|.
+To build the application, follow the instructions in :ref:`building` for your preferred building environment.
+See also :ref:`programming` for programming steps and :ref:`testing` for general information about testing and debugging in the |NCS|.
+
+.. note::
+    In the |NCS|, building with Sysbuild is :ref:`enabled by default <sysbuild_enabled_ncs>`.
diff --git a/doc/nrf/includes/build_and_run.txt b/doc/nrf/includes/build_and_run.txt
@@ -1,4 +1,7 @@
 This sample can be found under |sample path| in the |NCS| folder structure.
 
-To build the sample with |VSC|, follow the steps listed on the `How to build an application`_ page in the |nRFVSC| documentation.
-See :ref:`building` for other building scenarios, :ref:`programming` for programming steps, and :ref:`testing` for general information about testing and debugging in the |NCS|.
+To build the sample, follow the instructions in :ref:`building` for your preferred building environment.
+See also :ref:`programming` for programming steps and :ref:`testing` for general information about testing and debugging in the |NCS|.
+
+.. note::
+    In the |NCS|, building with Sysbuild is :ref:`enabled by default <sysbuild_enabled_ncs>`.
diff --git a/doc/nrf/includes/build_and_run_ns.txt b/doc/nrf/includes/build_and_run_ns.txt
@@ -4,5 +4,8 @@ When built as firmware image for a board target with the ``*/ns`` :ref:`variant
 Because of this, it automatically includes the :ref:`Trusted Firmware-M (TF-M) <ug_tfm>`.
 To read more about CMSE, see :ref:`app_boards_spe_nspe`.
 
-To build the sample with |VSC|, follow the steps listed on the `How to build an application`_ page in the |nRFVSC| documentation.
-See :ref:`building` for other building scenarios, :ref:`programming` for programming steps, and :ref:`testing` for general information about testing and debugging in the |NCS|.
+To build the sample, follow the instructions in :ref:`building` for your preferred building environment.
+See also :ref:`programming` for programming steps and :ref:`testing` for general information about testing and debugging in the |NCS|.
+
+.. note::
+    In the |NCS|, building with Sysbuild is :ref:`enabled by default <sysbuild_enabled_ncs>`.
diff --git a/doc/nrf/includes/build_and_run_sb.txt b/doc/nrf/includes/build_and_run_sb.txt
diff --git a/doc/nrf/includes/cmd_build_and_run.txt b/doc/nrf/includes/cmd_build_and_run.txt
diff --git a/doc/nrf/includes/config_build_and_run.txt b/doc/nrf/includes/config_build_and_run.txt
diff --git a/doc/nrf/includes/vsc_build_and_run_series.txt b/doc/nrf/includes/vsc_build_and_run_series.txt
@@ -2,9 +2,9 @@
 
    .. group-tab:: nRF Connect for VS Code
 
-      You need to set up a build configuration before you program a device in the |nRFVSC|.
+      Before you program a device in the |nRFVSC|, you need to set up a build configuration, which is part of :ref:`building`.
 
-      Complete the following steps:
+      Complete the following steps to program the application:
 
       1. Connect the development kit to your PC using a USB cable.
       #. Power on the development kit.
@@ -20,7 +20,7 @@
 
    .. group-tab:: Command line
 
-      Complete the following steps:
+      Complete the following steps to program the application:
 
       1. Connect the development kit to your PC using a USB cable.
       #. Power on the development kit.
@@ -35,6 +35,6 @@
          If the application depends on other flash memory areas (for example, if it uses the :ref:`zephyr:settings_api` partition where bonding information is stored), erasing the full kit before programming ensures that these areas are updated with the new content.
          You can also :ref:`program without erasing <programming_params_no_erase>`.
 
-         The ``west flash`` command automatically resets the kit and starts the application.
+      The ``west flash`` command automatically resets the kit and starts the application.
 
       For more information on programming using the command line, see :ref:`Flashing <zephyr:west-flashing>` in the Zephyr documentation.
diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -138,6 +138,8 @@
 
 .. _`CoreMark GitHub`: https://github.com/eembc/coremark
 
+.. _`conversion example Pull Request`: https://github.com/zephyrproject-rtos/example-application/pull/58
+
 .. ### Matter links that need updated SHA per release
 
 .. _`other controller setups`: https://github.com/nrfconnect/sdk-connectedhomeip/tree/181b0cb/src/controller
@@ -554,8 +556,6 @@
 .. _`Using the Power Profiler app`: https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/PPK_user_guide_Running_the_software.html
 .. _`nRF Connect Power Profiler`: https://docs.nordicsemi.com/bundle/nrf-connect-ppk/page/index.html
 
-.. _`sysbuild support`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/guides/build_overview.html#system-build-sysbuild
-
 .. _`Electrical specification for nRF7002`: https://docs.nordicsemi.com/bundle/ps_nrf7002/page/chapters/elspec/doc/electrical_specification.html
 
 .. _`LwM2M carrier sample for v2.5.2`: https://docs.nordicsemi.com/bundle/ncs-2.5.2/page/nrf/samples/cellular/lwm2m_carrier/README.html

diff --git a/doc/nrf/releases_and_maturity/known_issues.rst b/doc/nrf/releases_and_maturity/known_issues.rst
@@ -2218,7 +2218,7 @@ Bluetooth Mesh samples
 NCSDK-26388: Compilation of Mesh Light sample can create an image without MCUboot
   This can happen when compiled with the point-to-point DFU overlay and ``--sysbuild`` option.
 
-  **Workaround:** To get a correct image with MCUboot, do not use the ``--sysbuild`` option.
+  **Workaround:** To get a correct image with MCUboot, :ref:`build the firmware without sysbuild <optional_build_parameters>` using the ``--no-sysbuild`` option.
 
 .. rst-class:: v2-6-1 v2-6-0