doc: sysbuild and 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. Signed-off-by: Grzegorz Ferenc <[email protected]>
nrfconnect · Jun 7, 2024 · 9b4da2a · 9b4da2a
1 parent 323d0ef
commit 9b4da2a
Show file tree

Hide file tree

Showing 16 changed files with 66 additions and 56 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
 *************
@@ -72,12 +69,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`.
 
-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`
@@ -96,10 +93,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/config_and_build_system.rst b/doc/nrf/config_and_build/config_and_build_system.rst
@@ -224,6 +224,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:
@@ -252,6 +255,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 :guilablel:`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`` 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/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
@@ -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,5 @@ 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|.
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/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
@@ -553,8 +553,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
 

diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_2.7.rst
@@ -113,10 +113,10 @@ Samples and applications
 
 * For applications using child images:
 
-  * With the inheritance of Zephyr's :ref:`zephyr:sysbuild` in the |NCS|, the :ref:`ug_multi_image` are deprecated.
+  * With the inheritance of Zephyr's :ref:`Sysbuild in the |NCS| <configuration_system_overview_sysbuild>`, the :ref:`ug_multi_image` are deprecated.
 
-    If your application uses parent and child images, it is recommended to migrate your application to :ref:`zephyr:sysbuild` before the multi-image builds are removed in one of the upcoming |NCS| releases.
-    See the documentation in Zephyr for more information.
+    If your application uses parent and child images, it is recommended to migrate your application to Sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases.
+    See the :ref:`documentation in Zephyr <zephyr:sysbuild>` for more information.
 
 Matter
 ------

diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -130,7 +130,7 @@ Matter
 
 * Increased the number of available packet buffers in the Matter stack to avoid packet allocation issues.
 * Removed the :file:`Kconfig.mcuboot.defaults`, :file:`Kconfig.hci_ipc.defaults` and :file:`Kconfig.multiprotocol_rpmsg.defaults` Kconfig files that stored a default configuration for the child images.
-  This was done because of the sysbuild integration and the child images deprecation.
+  This was done because of the :ref:`configuration_system_overview_sysbuild` integration and the child images deprecation.
   The configurations are now applied using the configuration files located in the sample's or application's directory.
 
   To see how to migrate an application from the previous to the current approach, see the :ref:`migration guide <migration_2.7>`.
@@ -274,7 +274,7 @@ nRF Machine Learning (Edge Impulse)
 * Added:
 
   * Support for the :ref:`zephyr:nrf54h20dk_nrf54h20` boards.
-  * Support for the :ref:`zephyr:sysbuild`.
+  * Support for :ref:`configuration_system_overview_sysbuild`.
 
 nRF Desktop
 -----------
@@ -375,7 +375,7 @@ Bluetooth samples that used the :ref:`zephyr:bluetooth-hci-ipc-sample` radio cor
   * Added:
 
     * Support for the :ref:`zephyr:nrf54h20dk_nrf54h20` and :ref:`nRF54L15 PDK <ug_nrf54l15_gs>` boards.
-    * Support for the :ref:`zephyr:sysbuild`.
+    * Support for :ref:`configuration_system_overview_sysbuild`.
 
 * :ref:`peripheral_uart` sample:
 

diff --git a/samples/benchmarks/coremark/README.rst b/samples/benchmarks/coremark/README.rst
@@ -140,7 +140,7 @@ SB_CONFIG_APP_CPUPPR_RUN - Enable execution for the PPR core
 
    .. code-block:: console
 
-      west build -b nrf54h20dk/nrf54h20/cpuapp --sysbuild -- -DSB_CONFIG_APP_CPUNET_RUN=n -DSB_CONFIG_APP_CPUPPR_RUN=y -Dcoremark_SNIPPET=nordic-ppr-xip
+      west build -b nrf54h20dk/nrf54h20/cpuapp -- -DSB_CONFIG_APP_CPUNET_RUN=n -DSB_CONFIG_APP_CPUPPR_RUN=y -Dcoremark_SNIPPET=nordic-ppr-xip
 
 Building and running
 ********************
@@ -149,7 +149,7 @@ When running the benchmark, an extra build flag (:kconfig:option:`CONFIG_COMPILE
 
 .. |sample path| replace:: :file:`samples/benchmarks/coremark`
 
-.. include:: /includes/build_and_run_sb.txt
+.. include:: /includes/build_and_run.txt
 
 After flashing, messages describing the benchmark state will appear in the console.