doc: suit: Extended recovery documentation #17538
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Extended and updated documentation for SUIT recovery. Signed-off-by: Artur Hadasz <artur.hadasz@nordicsemi.no>
ahasztag
requested review from
tomchy,
SylwesterKonczyk,
jnsgsr,
maciejpietras,
robertstypa,
adsz-nordic,
kszromek-nordic and
a team
github-actions
bot
added
doc-required
CI InformationTo view the history of this post, clich the 'edited' button above Inputs:Sources:sdk-nrf: PR head: 158424be25020333fee9bb895c82ca72ca27d7f1 more detailssdk-nrf:
Github labels
List of changed files detected by CI (2)Outputs:ToolchainVersion: Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped;
|
maciejpietras
requested changes
Sep 30, 2024
| In such cases the device needs a way to recover from the failure and continue to operate. | ||
|
|
||
| In SUIT, this is solved by running a specially prepared recovery firmware. | ||
| Although the recovery firmware needs some additional space in the device, it is a highly recommended feature for all devices that use SUIT. |
There was a problem hiding this comment.
Suggested change
| Although the recovery firmware needs some additional space in the device, it is a highly recommended feature for all devices that use SUIT. | |
| Although the recovery firmware is optional and needs some additional space in the device, it is a highly recommended feature for all devices that use SUIT. |
|
|
||
| * Tampering by an attacker. | ||
| * Bitflips in the MRAM memory due to radiation or other external conditions. | ||
| * Hardware failures in advanced cases where an inplace update is performed and a firmware image is partially overwritten. |
There was a problem hiding this comment.
Suggested change
| * Hardware failures in advanced cases where an inplace update is performed and a firmware image is partially overwritten. | |
| * Hardware failures in advanced cases where an in-place update is performed and a firmware image is partially overwritten. |
| * Tampering by an attacker. | ||
| * Bitflips in the MRAM memory due to radiation or other external conditions. | ||
| * Hardware failures in advanced cases where an inplace update is performed and a firmware image is partially overwritten. | ||
| * An incorrectly constructed manifest, leading to a succesful update but failure during boot. |
There was a problem hiding this comment.
Suggested change
| * An incorrectly constructed manifest, leading to a succesful update but failure during boot. | |
| * An incorrectly constructed manifest, leading to a successful update, but to a failure during boot. |
| The recovery manifests form a separate hierarchy from the normal manifests. | ||
| In this hierarchy the application recovery (APP_RECOVERY) manifest has both the responsibility of managing the application core image as well as managing other manifests such as the radio recovery manifest. | ||
|
|
||
| If a failure during a boot process occured, the Secure Domain sets the recovery flag and reboots the device. |
There was a problem hiding this comment.
Suggested change
| If a failure during a boot process occured, the Secure Domain sets the recovery flag and reboots the device. | |
| If a failure during a boot process occurred, the Secure Domain sets the recovery flag and reboots the device. |
| The recovery flag might not be cleared after flashing the firmware, but the device should proceed as if it would boot normally. | ||
|
|
||
| The role of the recovery application is to perform an update of the main application firmware, which does not differ from the normal SUIT update process. | ||
| As soon as the update finishes succesfully, the recovery flag is cleared and the device proceeds with normal operation. |
There was a problem hiding this comment.
Suggested change
| As soon as the update finishes succesfully, the recovery flag is cleared and the device proceeds with normal operation. | |
| As soon as the update finishes successfully, the recovery flag is cleared and the device proceeds with normal operation. |
|
|
||
| This document describes scenarios in which a nRF54H20 device using SUIT can enter recovery mode and how the recovering process works. | ||
|
|
||
| When is recovery mode entered? |
There was a problem hiding this comment.
Would be good to add some diagram here.
|
|
||
| add_overlay_dts(recovery ${CMAKE_CURRENT_LIST_DIR}/boards/nrf54h20dk_nrf54h20_cpuapp.overlay) | ||
|
|
||
| This will ensure that when building from the main application directory the overlay file is attached to and not overwritten by the configuration comming from the main application. |
There was a problem hiding this comment.
Suggested change
| This will ensure that when building from the main application directory the overlay file is attached to and not overwritten by the configuration comming from the main application. | |
| This will ensure that when building from the main application directory the overlay file is attached to and not overwritten by the configuration coming from the main application. |
|
|
||
| #. Optionally - you can modify the recovery manifest templates. | ||
| The manifest template defined by the `CONFIG_SUIT_ENVELOPE_TEMPLATE_FILENAME` is first searched for in :file:`suit/<soc>` in the main application directory. | ||
| If it is not found, :file:`suit/<soc>` in the the recovery app is checked. |
There was a problem hiding this comment.
Suggested change
| If it is not found, :file:`suit/<soc>` in the the recovery app is checked. | |
| If it is not found, :file:`suit/<soc>` in the recovery app is checked. |
|
please, use forks. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Extended and updated documentation for SUIT recovery.
This PR probably requires adding some images, but I probably won't add when it comes to the text - I think it is good if you find some time to review while I am out of office