Skip to content

doc: Add sysbuild migration guide #15845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Jun 25, 2024
Merged

doc: Add sysbuild migration guide #15845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
9913339
doc: nrf: migration: Add sysbuild migration guide
nordicjm Jun 10, 2024
2289dd6
doc: nrf: build: Add sysbuild image guide
nordicjm Jun 12, 2024
c290e2b
doc: nrf: build: Add zephyr samples sysbuild page
nordicjm Jun 13, 2024
7042872
doc: nrf: build: Deprecate multi image
nordicjm Jun 17, 2024
7f57f73
doc: nrf: build: bootloaders: Add sysbuild documentation
nordicjm Jun 17, 2024
799a5e1
doc: nrf: guides: nrf70: Update for sysbuild
nordicjm Jun 17, 2024
65f2623
snippets: nrf70-fw-patch-ext-flash: Fix alignment
nordicjm Jun 17, 2024
aa2a1d8
doc: nrf: libraries: dfu: Improve multi image documentation
nordicjm Jun 17, 2024
aa6571a
doc: nrf: guides: Update guides for sysbuild
nordicjm Jun 17, 2024
b224fb8
doc: nrf: protocols: bt: bt_mesh: Update guides for sysbuild
nordicjm Jun 17, 2024
733c7ad
doc: nrf: zigbee: fota: Update Kconfig for sysbuild
nordicjm Jun 19, 2024
238590f
doc: nrf: bluetooth_services: fast_pair: Update Kconfig for sysbuild
nordicjm Jun 19, 2024
83fae2e
doc: nrf: config: bootloaders: downgrade: Update Kconfig for sysbuild
nordicjm Jun 19, 2024
39b43ab
doc: nrf: build: app: output_build_files Update for sysbuild
nordicjm Jun 19, 2024
99d6419
doc: nrf: config: bootloader: downgrade: Fix build number comment
nordicjm Jun 20, 2024
47ef7ee
doc: nrf: config: Add sysbuild forced options page
nordicjm Jun 19, 2024
6853c9d
sysbuild: Rearrange options
nordicjm Jun 20, 2024
900b252
doc: nrf: build: bootloaders: Add firmware loader documentation
nordicjm Jun 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions doc/nrf/config_and_build/bootloaders/bootloader_adding.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
.. _ug_bootloader_adding:

Adding a bootloader chain
#########################
Adding a bootloader chain using child and parent images
#######################################################

.. note::
This feature is now deprecated.
See :ref:`ug_bootloader_adding_sysbuild`.

.. contents::
:local:
Expand Down
449 changes: 449 additions & 0 deletions doc/nrf/config_and_build/bootloaders/bootloader_adding_sysbuild.rst
View file
Open in desktop

Large diffs are not rendered by default.

30 changes: 13 additions & 17 deletions doc/nrf/config_and_build/bootloaders/bootloader_downgrade_protection.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,10 @@ Software-based downgrade protection
The |NCS| supports MCUboot's software-based downgrade prevention for application images, using semantic versioning.
This feature offers protection against any outdated firmware that is uploaded to a device.

To enable this feature, set the MCUboot-specific configuration options ``CONFIG_MCUBOOT_DOWNGRADE_PREVENTION`` and ``CONFIG_BOOT_UPGRADE_ONLY`` for the MCUboot image.
To enable this feature, set the configuration option :kconfig:option:`CONFIG_MCUBOOT_DOWNGRADE_PREVENTION` for the MCUboot image and :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` for sysbuild.

.. caution::
Enabling ``CONFIG_BOOT_UPGRADE_ONLY`` prevents the fallback recovery of application images.
Enabling :kconfig:option:`SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY` prevents the fallback recovery of application images.
Copy link
Contributor

@RobertGalatNordic RobertGalatNordic Jun 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like for nrf53 this is only sensible mode for mcuboot, as default will only apply for app core and not net core
and result in version mismatch - application could roll back to previous working version, but netcore will be ignored (am I right?) maybe we should also add note here about this here

Copy link
Contributor

@sigvartmh sigvartmh Jun 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However sometimes you want to have this enabled for other reasons.

It is correct in NCS context this is the only use-case where this is required is when having multi-image updates to ensure that you don't get version mismatch.

Copy link
Contributor

@RobertGalatNordic RobertGalatNordic Jun 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, so I think that this config may be a little hard to understand on its own for nrf53 devices (especially that in some cases this may work as expected, if net core is still compatible with previous version it may be unnoticed for a long time and result in hard to debug issues), and IMHO it would be nice to see some clarification either here, or maybe there is better place for such note. I just feel like this information is an inside knowledge, and it could be misunderstood or unnoticed by the users of nrf53.

Consult its Kconfig description and the :doc:`MCUboot Design documentation <mcuboot:design>` for more information on how to use it.

You can compile your application with this feature as follows:
Expand All @@ -41,19 +41,20 @@ You can compile your application with this feature as follows:
:class: highlight

west build -b *board_target* *application* -- \\
-DCONFIG_BOOTLOADER_MCUBOOT=y \\
-DSB_CONFIG_BOOTLOADER_MCUBOOT=y \\
-DSB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y \\
-DCONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION=\\"0.1.2\\+3\\" \\
-Dmcuboot_CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y \\
-Dmcuboot_CONFIG_BOOT_UPGRADE_ONLY=y
-Dmcuboot_CONFIG_MCUBOOT_DOWNGRADE_PREVENTION=y

|how_to_configure|

After you upload a new image and reset the development kit, MCUboot attempts to boot the secondary image.
If this image has, in order of precedence, a *major*, *minor*, or *revision* value that is lower than the primary application image, it is considered invalid and the existing primary application boots instead.

.. note::
The optional label or build number specified after the ``+`` character is ignored when evaluating the version.
By default, the optional label or build number specified after the ``+`` character is ignored when evaluating the version.
For example, an existing application image with version ``0.1.2+3`` can be overwritten by an uploaded image with ``0.1.2+2``, but not by one with ``0.1.1+2``.
Checking against this field can be performed by enabling :kconfig:option:`CONFIG_BOOT_VERSION_CMP_USE_BUILD_NUMBER` in the MCUboot image

.. _ug_fw_update_downgrade_protection_hw:
.. _bootloader_monotonic_counter:
Expand Down Expand Up @@ -82,27 +83,22 @@ Downgrade protection using |NSIB|

.. bootloader_monotonic_counter_nsib_start

To enable anti-rollback protection with monotonic counter for |NSIB|, set the following configurations in the application (parent image):

* :kconfig:option:`CONFIG_SB_MONOTONIC_COUNTER`
* :kconfig:option:`CONFIG_SB_NUM_VER_COUNTER_SLOTS`
To enable anti-rollback protection with monotonic counter for |NSIB|, set the following configurations in the ``b0`` image: :kconfig:option:`CONFIG_SB_MONOTONIC_COUNTER` and :kconfig:option:`CONFIG_SB_NUM_VER_COUNTER_SLOTS`

Special handling is needed when updating the S1 variant of an image when :ref:`ug_bootloader_adding_upgradable`.
See :ref:`ug_bootloader_adding_presigned_variants` for details.

.. bootloader_monotonic_counter_nsib_end

To set options for child images, see the :ref:`ug_multi_image_variables` section.
To set options for other images, see :ref:`zephyr:sysbuild_kconfig_namespacing`.

.. _ug_fw_update_hw_downgrade_mcuboot:

Downgrade protection using MCUboot
==================================

To enable anti-rollback protection with monotonic counter for MCUboot, set the following configurations in the application (parent image):

* :kconfig:option:`CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`
* :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS`
* :kconfig:option:`CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE`
To enable anti-rollback protection with monotonic counter for MCUboot, set the following configurations using sysbuild:

To set options for child images, see the :ref:`ug_multi_image_variables` section.
* :kconfig:option:`SB_CONFIG_MCUBOOT_HARDWARE_DOWNGRADE_PREVENTION`
* :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_SLOTS`
* :kconfig:option:`SB_CONFIG_MCUBOOT_HW_DOWNGRADE_PREVENTION_COUNTER_VALUE`
1 change: 1 addition & 0 deletions doc/nrf/config_and_build/bootloaders/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ See the following user guides to learn more:

bootloader
bootloader_adding
bootloader_adding_sysbuild
bootloader_testing
bootloader_external_flash
bootloader_config
Expand Down
3 changes: 3 additions & 0 deletions doc/nrf/config_and_build/configuring_app/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,5 +76,8 @@ Just as for creating the application, you can build the application using either
kconfig/index
advanced_building
output_build_files
sysbuild_images
zephyr_samples_sysbuild
sysbuild_forced_options

.. |output_files_note| replace:: For more information about files generated as output of the build process, see :ref:`app_build_output_files`.
Loading