doc: suit: Push scenario and DFU caches documentation #17519
+236
−28
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
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: 4eb9032f6d6d0b1946dc88614a8a2714b57c831c more detailssdk-nrf:
Github labels
List of changed files detected by CI (4)Outputs:ToolchainVersion: Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped;
|
ahasztag
force-pushed
the
NCSDK-28882_doc_push_caches
branch
2 times, most recently
from
3f48612
to
17f8727
Compare
greg-fer
reviewed
Sep 27, 2024
There was a problem hiding this comment.
Placement of the new file is OK for me. Title probably needs adjustment -- we don't name pages with "How to" usually. Detailed review will be done by the SUIT and nRF54H20 doc owner @FrancescoSer .
ahasztag
force-pushed
the
NCSDK-28882_doc_push_caches
branch
2 times, most recently
from
be58f5c
to
33e69d5
Compare
|
You can find the documentation preview for this PR at this link. It will be updated about 10 minutes after the documentation build succeeds. Note: This comment is automatically posted by the Documentation Publishing GitHub Action. |
Added documentation for SUIT DFU cache partitions and how to use them to push detached payloads for DFU to the device. Signed-off-by: Artur Hadasz <artur.hadasz@nordicsemi.no>
ahasztag
force-pushed
the
NCSDK-28882_doc_push_caches
branch
from
33e69d5
to
4eb9032
Compare
richabp
requested changes
Sep 27, 2024
| @@ -12,8 +12,8 @@ However, the application domain can implement an IPC service, which allows the S | |||
| This guide explains how to prepare the application domain firmware and the SUIT envelope to perform SUIT firmware upgrade using external memory. | |||
|
|
|||
| .. note:: | |||
| The prerequisite to this guide is the :ref:`ug_nrf54h20_suit_fetch` user guide, as this guide assumes that the application uses the fetch model to obtain the candidate images. | |||
| See the :ref:`ug_nrf54h20_suit_fetch` for more details on how to migrate from push to fetch model. | |||
| To use external memory with SUIT, the you can either use the push model-based or the fetch model-based firmware upgrade. | |||
There was a problem hiding this comment.
Suggested change
| To use external memory with SUIT, the you can either use the push model-based or the fetch model-based firmware upgrade. | |
| To use external memory with SUIT, you can either use the push model-based or the fetch model-based firmware upgrade. |
| The prerequisite to this guide is the :ref:`ug_nrf54h20_suit_fetch` user guide, as this guide assumes that the application uses the fetch model to obtain the candidate images. | ||
| See the :ref:`ug_nrf54h20_suit_fetch` for more details on how to migrate from push to fetch model. | ||
| To use external memory with SUIT, the you can either use the push model-based or the fetch model-based firmware upgrade. | ||
| See :ref:`ug_nrf54h20_suit_push` for details about the push model and :ref:`ug_nrf54h20_suit_fetch` for details on how to migrate from push to fetch model. |
There was a problem hiding this comment.
Suggested change
| See :ref:`ug_nrf54h20_suit_push` for details about the push model and :ref:`ug_nrf54h20_suit_fetch` for details on how to migrate from push to fetch model. | |
| See :ref:`ug_nrf54h20_suit_push` for details about the push model and :ref:`ug_nrf54h20_suit_fetch` for details on how to migrate from the push to fetch model. |
| The SUIT envelope must always be stored in the non-volatile memory in the MCU. | ||
| The SUIT manifests stored in the envelope contain instructions that the device must perform to fetch other required payloads. | ||
| To store payloads in the external memory, a Device Firmware Update (DFU) cache partition must be defined in the external memory's devicetree node. | ||
| In the SUIT manifest, you can define a component representing the cache partition in the external memory. | ||
| Within the ``suit-payload-fetch`` sequence, you can then store fetched payload(s) into a ``CACHE_POOL`` component. | ||
| The push model-based and the fetch model-based differ in the way the cache partition is filled with the images. |
There was a problem hiding this comment.
Suggested change
| The push model-based and the fetch model-based differ in the way the cache partition is filled with the images. | |
| The push model-based update and the fetch model-based update differ in the way the cache partition is filled with the images. |
| @@ -43,13 +41,53 @@ The companion image consists of two main parts: | |||
| * IPC service exposed towards the Secure Domain | |||
|
|
|||
| When the companion image is booted and a directive that accesses the data on the external memory is issued, such as the ``suit-directive-fetch`` or ``suit-directive-copy`` directives, the Secure Domain firmware uses the IPC service provided by the companion image to access the contents of the external memory. | |||
| Beyond the booting of the companion image, the update process does not differ from regular fetch model-based update. | |||
| Beyond the booting of the companion image, the update process does not differ from regular push-model based or fetch model-based updates. | |||
There was a problem hiding this comment.
Suggested change
| Beyond the booting of the companion image, the update process does not differ from regular push-model based or fetch model-based updates. | |
| Beyond the booting of the companion image, the update process does not differ from regular push model-based or fetch model-based updates. |
| ---------- | ||
|
|
||
| In the push model, the cache partition contents are created on the building machine and pushed to the device without modifications. | ||
| The images are extracted to the cache partition files using the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE` |
There was a problem hiding this comment.
Suggested change
| The images are extracted to the cache partition files using the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE` | |
| The images are extracted to the cache partition files using the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE` Kconfig option. |
|
|
||
| #. Ensure that the uri used by ``suit-payload-fetch`` sequence to fetch a given image matches the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI`. | ||
| Note this is done by default if using the provided Nordic manifest templates. | ||
| For the application image URI this can be done by (assuming the target name "application" for the image): |
There was a problem hiding this comment.
Suggested change
| For the application image URI this can be done by (assuming the target name "application" for the image): | |
| For the application image URI, this can be done by (assuming the target name ``application`` for the image): |
| * (Optionally) modify the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI` to modify the URI used as key for the given image in the DFU cache. | ||
|
|
||
| #. Ensure that the uri used by ``suit-payload-fetch`` sequence to fetch a given image matches the :kconfig:option:`CONFIG_SUIT_DFU_CACHE_EXTRACT_IMAGE_URI`. | ||
| Note this is done by default if using the provided Nordic manifest templates. |
There was a problem hiding this comment.
Suggested change
| Note this is done by default if using the provided Nordic manifest templates. | |
| This is done by default if using the manifest templates provided by Nordic Semiconductor. |
| - suit-directive-fetch: | ||
| - suit-send-record-failure | ||
|
|
||
| #. Ensure that the envelope does not integrate the given image inside the envelope integrated payloads section |
There was a problem hiding this comment.
Suggested change
| #. Ensure that the envelope does not integrate the given image inside the envelope integrated payloads section | |
| #. Ensure that the envelope does not integrate the given image inside the envelope integrated payloads section. |
| - suit-send-record-failure | ||
|
|
||
| #. Ensure that the envelope does not integrate the given image inside the envelope integrated payloads section | ||
| This will be ensured by default if using the provided default SUIT envelope templates. |
There was a problem hiding this comment.
Suggested change
| This will be ensured by default if using the provided default SUIT envelope templates. | |
| This is ensured by default if using the provided default SUIT envelope templates. |
| Pushing the images to device | ||
| **************************** | ||
|
|
||
| For an example how to push an image to a device see the :ref:`SUIT SMP Sample documentation <nrf54h_suit_sample>`. |
There was a problem hiding this comment.
Suggested change
| For an example how to push an image to a device see the :ref:`SUIT SMP Sample documentation <nrf54h_suit_sample>`. | |
| See the :ref:`SUIT SMP Sample documentation <nrf54h_suit_sample>` for an example of how to push an image to a device. |
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.
Added documentation for SUIT DFU cache partitions
and how to use them to push detached payloads for DFU to the device.