Skip to content
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

NCSDK-32185: Add suit A/B sample documentation #21213

Merged
merged 2 commits into from
Apr 3, 2025
Merged

NCSDK-32185: Add suit A/B sample documentation #21213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28c2612
suit: Add AB update sample docs
tomchy Mar 27, 2025
1bcb8d4
suit: Update changelog
tomchy Mar 28, 2025
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
44 changes: 43 additions & 1 deletion doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -744,7 +744,17 @@ Sensor samples
SUIT samples
------------

|no_changes_yet_note|
* Added the :ref:`nrf54h_suit_ab_sample` sample that demonstrates how to perform A/B updates using SUIT manifests.

* :ref:`nrf54h_suit_sample` sample:

* Updated:

* The memory maps to cover the entire available MRAM memory.
* The memory maps to place recovery firmware on lower addresses than the main firmware.
* By enabling secure entropy source in all main Bluetooth-enabled sample variants (except recovery firmware).
* By extending the manifests to process the ``suit-payload-fetch`` sequence of the Nordic top update candidate.
* By extending the manifests with build-time checks for consistency between MPI and envelope signing configuration.

Trusted Firmware-M (TF-M) samples
---------------------------------
Expand Down Expand Up @@ -827,6 +837,11 @@ Wi-Fi drivers

|no_changes_yet_note|

Flash drivers
-------------

* Added a ``flash_ipuc`` driver that allows to manage SUIT IPUC memory through the Zephyr flash API.

Libraries
=========

Expand Down Expand Up @@ -912,6 +927,33 @@ DFU libraries

* Regenerated the zcbor-generated code files using v0.9.0.

SUIT libraries
--------------

* Added:

* Support for manifest-controlled variables, that allow to control manifest logic based on previous evaluations as well as store integer values inside the SUIT non-volatile memory region.
* Support for in-place updateable components (IPUC) that allows to cross memory permission boundaries to update inactive memory regions from the main application.
* Support for IPUC in SUIT manifests:

* It is possible to fetch payloads directly into an IPUC.
* It is possible to declare an IPUC as DFU cache area.
* It is possible to trigger Nordic firmware updates from an IPUC-based DFU cache area.

* Support for IPUC in DFU protocols:

* It is possible to write into IPUC using SMP image command group.
* It is possible to write into IPUC using SUIT SMP cache raw upload commands.
* It is possible to write into IPUC using SUIT :ref:`dfu_target<lib_dfu_target_suit_style_update>` library.

* A possibility to copy binaries into radio local RAM memory from SUIT radio manifests.
* A possibility to specify the minimal Nordic top manifest version in the :file:`VERSION` file.
* A possibility to block independent updates of Nordic manifests using the :kconfig:option:`CONFIG_SUIT_NORDIC_TOP_INDEPENDENT_UPDATE_FORBIDDEN` Kconfig option.

* Updated:

* By moving the MPI configuration from local Kconfigs to sysbuild.

Gazell libraries
----------------

Expand Down
1 change: 1 addition & 0 deletions doc/nrf/samples/suit.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ This section lists available |NCS| samples for :ref:`Device Firmware Update usin
../../../samples/suit/smp_transfer/README
../../../samples/suit/flash_companion/README
../../../samples/suit/recovery/README
../../../samples/suit/ab/README
1,257 changes: 1,257 additions & 0 deletions samples/suit/ab/README.rst
View file
Open in desktop

Large diffs are not rendered by default.

268 changes: 268 additions & 0 deletions samples/suit/ab/img/IPUC_AB.drawio
View file
Open in desktop

Large diffs are not rendered by default.

Binary file added samples/suit/ab/img/IPUC_AB.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
142 changes: 142 additions & 0 deletions samples/suit/ab/img/Nordic_IPUC.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:136.0) Gecko/20100101 Firefox/136.0" version="26.1.1">
<diagram name="Page-1" id="fG1Dt5wzgLy2BK9qvU7i">
<mxGraphModel dx="989" dy="595" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="j9PA9f9_Thtx9o9hWDL8-1" value="Nordic&lt;br&gt;Reserved&lt;br&gt;76 kB" style="rounded=0;whiteSpace=wrap;html=1;imageVerticalAlign=top;verticalAlign=top;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
<mxGeometry x="330" y="300" width="140" height="130" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-2" value="SUIT storage&lt;br&gt;20 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;gradientDirection=east;strokeColor=#6c8ebf;" parent="1" vertex="1">
<mxGeometry x="340" y="360" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-3" value="Application&lt;br&gt;NV storage&lt;br&gt;32 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
<mxGeometry x="330" y="430" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-4" value="DFU &lt;br&gt;partition&lt;br&gt;20 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
<mxGeometry x="330" y="490" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-5" value="Nordic&lt;br&gt;Reserved&lt;br&gt;336 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
<mxGeometry x="330" y="790" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-6" value="DFU cache 1&lt;br&gt;592 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;gradientColor=#D5E8D4;gradientDirection=east;" parent="1" vertex="1">
<mxGeometry x="330" y="550" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-7" value="Application A&lt;br&gt;592 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" parent="1" vertex="1">
<mxGeometry x="330" y="610" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-8" value="Radio B&lt;br&gt;200 kB" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="330" y="670" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-9" value="Radio A&lt;br&gt;200 kB" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" parent="1" vertex="1">
<mxGeometry x="330" y="730" width="140" height="60" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-10" value="0x0E00 0000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="250" y="840" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-11" value="0x0E20 0000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="250" y="290" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-12" value="0x0E1E D000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="250" y="420" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-13" value="0x0E00 5400" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="250" y="780" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-14" value="0x0E1E 0000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="470" y="540" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-15" value="0x0E14 C000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="470" y="600" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-16" value="0x0E0B 8000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="470" y="660" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-17" value="0x0E08 6000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="470" y="720" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-20" value="0x0E1E 5000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="470" y="480" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-21" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="280" y="300" as="sourcePoint" />
<mxPoint x="330" y="300" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-22" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="280" y="850" as="sourcePoint" />
<mxPoint x="330" y="850" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-23" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="280" y="639.71" as="sourcePoint" />
<mxPoint x="330" y="639.71" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-24" value="0x0E10 0000" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" parent="1" vertex="1">
<mxGeometry x="250" y="630" width="80" height="10" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-26" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="300" y="430" as="sourcePoint" />
<mxPoint x="330" y="430" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-27" value="" style="endArrow=none;html=1;rounded=0;entryX=0;entryY=0;entryDx=0;entryDy=0;" parent="1" target="j9PA9f9_Thtx9o9hWDL8-5" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="290" y="790" as="sourcePoint" />
<mxPoint x="340" y="790" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-28" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="470" y="490" as="sourcePoint" />
<mxPoint x="520" y="490" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-29" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="470" y="550" as="sourcePoint" />
<mxPoint x="520" y="550" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-30" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="470" y="610" as="sourcePoint" />
<mxPoint x="520" y="610" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-31" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="470" y="670" as="sourcePoint" />
<mxPoint x="520" y="670" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-32" value="" style="endArrow=none;html=1;rounded=0;" parent="1" edge="1">
<mxGeometry width="50" height="50" relative="1" as="geometry">
<mxPoint x="470" y="730" as="sourcePoint" />
<mxPoint x="520" y="730" as="targetPoint" />
</mxGeometry>
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-33" value="Application&lt;br&gt;RW-S" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" parent="1" vertex="1">
<mxGeometry x="600" y="660" width="80" height="40" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-34" value="Application&lt;br&gt;R-XS" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" parent="1" vertex="1">
<mxGeometry x="600" y="710" width="80" height="40" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-35" value="Radio&lt;br&gt;R-XS" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" parent="1" vertex="1">
<mxGeometry x="600" y="760" width="80" height="40" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-36" value="Reserved&lt;br&gt;----" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" parent="1" vertex="1">
<mxGeometry x="600" y="810" width="80" height="40" as="geometry" />
</mxCell>
<mxCell id="j9PA9f9_Thtx9o9hWDL8-37" value="Application&lt;br&gt;IPUC&lt;br&gt;RW-S" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;gradientColor=#D5E8D4;gradientDirection=east;" parent="1" vertex="1">
<mxGeometry x="600" y="610" width="80" height="40" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
Binary file added samples/suit/ab/img/Nordic_IPUC.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added samples/suit/ab/img/ab_root_candidate_verification.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 54 additions & 0 deletions samples/suit/ab/img/ab_root_candidate_verification.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
@startuml
start

: SET_TO_UPDATE_MIRROR := SET_TO_UPDATE ;

if (Uri('#top') present and valid) then (yes)

if (SET_TO_UPDATE_MIRROR == SET_B) then (yes)
if (Version(Application A) >= MIN_COMPATIBLE_APP_VERSION_FOR_NORDIC_TOP) then (yes)
if (Version(Radio A) >= MIN_COMPATIBLE_RAD_VERSION_FOR_NORDIC_TOP) then (yes)
: fetch('#top') ;
: check_integrity('#top') ;
: process('#top') ;
stop

endif
endif
endif
: abort() ;
stop

else (no)
if (Version(Intalled Nordic Top) >= MIN_NORDIC_TOP_VERSION) then (yes)
if (SET_TO_UPDATE_MIRROR == SET_A) then (yes)
: fetch('#radio') ;
: check_integrity('#radio') ;
: process('#radio') ;

: fetch('#application') ;
: check_integrity('#application') ;
: process('#application') ;
stop
elseif (SET_TO_UPDATE_MIRROR == SET_B) then (yes)
: fetch('#radio_b') ;
: check_integrity('#radio_b') ;
: process('#radio_b') ;

: fetch('#application_b') ;
: check_integrity('#application_b') ;
: process('#application_b') ;
stop
else (no)
: abort() ;
stop
endif

else (no)
: abort() ;
stop
endif

endif

@enduml
Binary file added samples/suit/ab/img/ab_root_install.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
58 changes: 58 additions & 0 deletions samples/suit/ab/img/ab_root_install.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
@startuml
start

: SET_TO_UPDATE_MIRROR := SET_TO_UPDATE ;

if (Uri('#top') present and valid) then (yes)

if (SET_TO_UPDATE_MIRROR == SET_B) then (yes)
if (Version(Application A) >= MIN_COMPATIBLE_APP_VERSION_FOR_NORDIC_TOP) then (yes)
if (Version(Radio A) >= MIN_COMPATIBLE_RAD_VERSION_FOR_NORDIC_TOP) then (yes)
: fetch('#top') ;
: check_integrity('#top') ;
: process('#top') ;
stop

endif
endif
endif
: abort() ;
stop

else (no)
if (Version(Intalled Nordic Top) >= MIN_NORDIC_TOP_VERSION) then (yes)
if (SET_TO_UPDATE_MIRROR == SET_A) then (yes)
: CONFIRM_SET_A := JUST_INSTALLED ;
: fetch('#radio') ;
: check_integrity('#radio') ;
: process('#radio') ;

: fetch('#application') ;
: check_integrity('#application') ;
: process('#application') ;
: BOOT_PREFERENCE := SET_A ;
stop
elseif (SET_TO_UPDATE_MIRROR == SET_B) then (yes)
: CONFIRM_SET_B := JUST_INSTALLED ;
: fetch('#radio_b') ;
: check_integrity('#radio_b') ;
: process('#radio_b') ;

: fetch('#application_b') ;
: check_integrity('#application_b') ;
: process('#application_b') ;
: BOOT_PREFERENCE := SET_B ;
stop
else (no)
: abort() ;
stop
endif

else (no)
: abort() ;
stop
endif

endif

@enduml
Binary file added samples/suit/ab/img/ab_root_invoke.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
29 changes: 29 additions & 0 deletions samples/suit/ab/img/ab_root_invoke.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
@startuml
start

if (BOOT_STATUS == BOOT_A)then (yes)
if (CONFIRM_SET_A == JUST_INSTALLED) then (yes)
: CONFIRM_SET_A := NOT_CONFIRMED;
endif
: Start Application A;
: Start Radio A;
elseif (BOOT_STATUS == BOOT_B) then (yes)
if (CONFIRM_SET_B == JUST_INSTALLED) then (yes)
: CONFIRM_SET_B := NOT_CONFIRMED;
endif
: Start Application B;
: Start Radio B;
elseif (BOOT_STATUS == BOOT_A_DEGRADED) then (yes)
: Start Application A;
: Start Radio A;
elseif (BOOT_STATUS == BOOT_B_DEGRADED) then (yes)
: Start Application B;
: Start Radio B;
elseif (BOOT_STATUS == BOOT_A_NO_RADIO) then (yes)
: Start Application A;
elseif (BOOT_STATUS == BOOT_B_NO_RADIO) then (yes)
: Start Application B;
endif

stop
@enduml
Binary file added samples/suit/ab/img/ab_root_payload_fetch.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading