Skip to content

Commit

Permalink
doc: update documentation for mcuboot to document ram-load with revert
Browse files Browse the repository at this point in the history
Add documentation and release notes entry for ram-load with revert
support in mcuboot.

Signed-off-by: Daniel DeGrasse <ddegrasse@tenstorrent.com>
  • Loading branch information
danieldegrasse committed Feb 28, 2025
1 parent f504034 commit ea55e12
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 14 deletions.
36 changes: 22 additions & 14 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,7 @@ image. After a successful validation of the selected image the bootloader
chain-loads it.

An additional "revert" mechanism is also supported. For more information, please
read the [corresponding section](#direct-xip-revert).
read the [corresponding section](#direct-xip-ram-load-revert).
Handling the primary and secondary slots as equals has its drawbacks. Since the
images are not moved between the slots, the on-the-fly image
encryption/decryption can't be supported (it only applies to storing the image
Expand Down Expand Up @@ -351,6 +351,11 @@ happens as described above. If the image is encrypted, it is copied in RAM at
the provided address and then decrypted. Finally, the decrypted image is
authenticated in RAM and executed.
Similar to direct-xip, ram-load mode also supports a "revert" mechanism.
This mechanism works in the same manner as the direct-xip revert mechanism does,
so please see the [corresponding section](#direct-xip-ram-load-revert) for
more details.
## [Boot swap types](#boot-swap-types)
When the device first boots under normal circumstances, there is an up-to-date
Expand Down Expand Up @@ -406,19 +411,22 @@ The "swap type" is a high-level representation of the outcome of the
boot. Subsequent sections describe how MCUboot determines the swap type from
the bit-level contents of flash.
### [Revert mechanism in direct-xip mode](#direct-xip-revert)
The direct-xip mode also supports a "revert" mechanism which is the equivalent
of the swap mode's "revert" swap. When the direct-xip mode is selected it can be
enabled with the MCUBOOT_DIRECT_XIP_REVERT config option and an image trailer
must also be added to the signed images (the "--pad" option of the `imgtool`
script must be used). For more information on this please read the
[Image Trailer](#image-trailer) section and the [imgtool](imgtool.md)
documentation. Making the images permanent (marking them as confirmed in
advance) is also supported just like in swap mode. The individual steps of the
direct-xip mode's "revert" mechanism are the following:
1. Select the slot which holds the newest potential image.
### [Revert mechanism in direct-xip and ram-load mode](#direct-xip-ram-load-revert)
The direct-xip and ram-load modes also support a "revert" mechanism which is the
equivalent of the swap mode's "revert" swap. When the direct-xip mode is
selected it can be enabled with the `MCUBOOT_DIRECT_XIP_REVERT` config option.
In ram-load mode, the feature is enabled with `MCUBOOT_RAM_LOAD_REVERT` config
option. Note that an image trailer must also be added to the signed images (the
"--pad" option of the `imgtool` script must be used). Otherwise, MCUboot will
not recognize the image as valid and will attempt to revert it. For more
information on this please read the [Image Trailer](#image-trailer) section and
the [imgtool](imgtool.md) documentation. Making the images permanent (marking
them as confirmed in advance) is also supported just like in swap mode. The
individual steps of this "revert" mechanism are the following:
1. Select the slot which holds the newest potential image, based on the
version number
2. Was the image previously selected to run (during a previous boot)?
+ Yes: Did the image mark itself "OK" (was the self-test successful)?
+ Yes.
Expand Down
2 changes: 2 additions & 0 deletions docs/release-notes.d/enable-ram-load-revert.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
- Enabled support for ram-load revert mode, which functions using the same
logic as direct-xip revert mode but loads the executable image to ram.

0 comments on commit ea55e12

Please sign in to comment.