Replace flash partitioning terminology
This change replaces the slot 0/1 terminology with primary/secondary
slot and replaces FLASH_AREA_IMAGE_0/1 with
FLASH_AREA_IMAGE_PRIMARY/SECONDARY. This naming convention may be more
understandable, fits better to MCUs with multiple images and it is an
architecture agnostic alternative as well.
Change-Id: I655a585f6ae023852c671ee6635399efe25209c9
Signed-off-by: David Vincze <david.vincze@arm.com>
Signed-off-by: David Brown <david.brown@linaro.org>
diff --git a/docs/PORTING.md b/docs/PORTING.md
index e2ffb8a..2a63d50 100644
--- a/docs/PORTING.md
+++ b/docs/PORTING.md
@@ -86,9 +86,9 @@
`fa_id` is can be one of the following options:
```c
-#define FLASH_AREA_IMAGE_0 1
-#define FLASH_AREA_IMAGE_1 2
-#define FLASH_AREA_IMAGE_SCRATCH 3
+#define FLASH_AREA_IMAGE_PRIMARY 1
+#define FLASH_AREA_IMAGE_SECONDARY 2
+#define FLASH_AREA_IMAGE_SCRATCH 3
```
The functions that must be defined for working with the `flash_area`s are:
@@ -109,7 +109,7 @@
uint8_t flash_area_align(const struct flash_area *);
/*< Initializes an array of flash_area elements for the slot's sectors */
int flash_area_to_sectors(int idx, int *cnt, struct flash_area *ret);
-/*< Returns the `fa_id` for slot, where slot is 0 or 1 */
+/*< Returns the `fa_id` for slot, where slot is 0 (primary) or 1 (secondary) */
int flash_area_id_from_image_slot(int slot);
/*< Returns the slot, for the `fa_id` supplied */
int flash_area_id_to_image_slot(int area_id);
diff --git a/docs/design.md b/docs/design.md
index 4da4c99..13f60b1 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -116,10 +116,10 @@
The boot loader uses the following flash area IDs:
``` c
-#define FLASH_AREA_BOOTLOADER 0
-#define FLASH_AREA_IMAGE_0 1
-#define FLASH_AREA_IMAGE_1 2
-#define FLASH_AREA_IMAGE_SCRATCH 3
+#define FLASH_AREA_BOOTLOADER 0
+#define FLASH_AREA_IMAGE_PRIMARY 1
+#define FLASH_AREA_IMAGE_SECONDARY 2
+#define FLASH_AREA_IMAGE_SCRATCH 3
```
The bootloader area contains the bootloader image itself. The other areas are
@@ -140,14 +140,14 @@
In addition to the two image slots, the boot loader requires a scratch area to
allow for reliable image swapping. The scratch area must have a size that is
enough to store at least the largest sector that is going to be swapped. Many
-devices have small equally sized flash sectors, eg 4K, while others have variable
-sized sectors where the largest sectors might be 128K or 256K, so the scratch
-must be big enough to store that. The scratch is only ever used when swapping
-firmware, which means only when doing an upgrade. Given that, the main reason
-for using a larger size for the scratch is that flash wear will be more evenly
-distributed, because a single sector would be written twice the number of times
-than using two sectors, for example. To evaluate the ideal size of the scratch
-for your use case the following parameters are relevant:
+devices have small equally sized flash sectors, eg 4K, while others have
+variable sized sectors where the largest sectors might be 128K or 256K, so the
+scratch must be big enough to store that. The scratch is only ever used when
+swapping firmware, which means only when doing an upgrade. Given that, the main
+reason for using a larger size for the scratch is that flash wear will be more
+evenly distributed, because a single sector would be written twice the number of
+times than using two sectors, for example. To evaluate the ideal size of the
+scratch for your use case the following parameters are relevant:
* the ratio of image size / scratch size
* the number of erase cycles supported by the flash hardware
@@ -174,9 +174,9 @@
There is no *best* ratio, as the right size is use-case dependent. Factors to
consider include the number of times a device will be upgraded both in the field
-and during development, as well as any desired safety margin on the manufacturer's
-specified number of erase cycles. In general, using a ratio that allows hundreds
-to thousands of field upgrades in production is recommended.
+and during development, as well as any desired safety margin on the
+manufacturer's specified number of erase cycles. In general, using a ratio that
+allows hundreds to thousands of field upgrades in production is recommended.
The overwrite upgrade strategy is substantially simpler to implement than the
image swapping strategy, especially since the bootloader must work properly
@@ -187,10 +187,10 @@
## Boot Swap Types
When the device first boots under normal circumstances, there is an up-to-date
-firmware image in slot 0, which mcuboot can validate and then chain-load. In
-this case, no image swaps are necessary. During device upgrades, however, new
-candidate images are present in slot 1, which mcuboot must swap into slot 0
-before booting as discussed above.
+firmware image in the primary slot, which mcuboot can validate and then
+chain-load. In this case, no image swaps are necessary. During device upgrades,
+however, new candidate images are present in the secondary slot, which mcuboot
+must swap into the primary slot before booting as discussed above.
Upgrading an old image with a new one by swapping can be a two-step process. In
this process, mcuboot performs a "test" swap of image data in flash and boots
@@ -217,17 +217,18 @@
The possible swap types, and their meanings, are:
- `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the
- contents of slot 0.
+ contents of the primary slot.
-- `BOOT_SWAP_TYPE_TEST`: Boot the contents of slot 1 by swapping images. Unless
- the swap is made permanent, revert back on the next boot.
+- `BOOT_SWAP_TYPE_TEST`: Boot the contents of the secondary slot by swapping
+ images. Unless the swap is made permanent, revert back on the next boot.
- `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image
firmware.
-- `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent; swap back
- to the old image whose data are now in slot 1. If the old image marks itself
- "OK" when it boots, the next boot will have swap type `BOOT_SWAP_TYPE_NONE`.
+- `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent;
+ swap back to the old image whose data are now in the secondary slot. If the
+ old image marks itself "OK" when it boots, the next boot will have swap type
+ `BOOT_SWAP_TYPE_NONE`.
- `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid.
@@ -278,28 +279,30 @@
An image trailer contains the following fields:
1. Swap status: A series of records which records the progress of an image
- swap. To swap entire images, data are swapped between the two image areas one
- or more sectors at a time, like this:
+ swap. To swap entire images, data are swapped between the two image areas
+ one or more sectors at a time, like this:
- - sector data in slot 0 is copied into scratch, then erased
- - sector data in slot 1 is copied into slot 0, then erased
- - sector data in scratch is copied into slot 1
+ - sector data in the primary slot is copied into scratch, then erased
+ - sector data in the secondary slot is copied into the primary slot,
+ then erased
+ - sector data in scratch is copied into the secondary slot
As it swaps images, the bootloader updates the swap status field in a way that
allows it to compute how far this swap operation has progressed for each
sector. The swap status field can thus used to resume a swap operation if the
bootloader is halted while a swap operation is ongoing and later reset. The
-`BOOT_MAX_IMG_SECTORS` value is the configurable maximum number of sectors mcuboot
-supports for each image; its value defaults to 128, but allows for either
-decreasing this size, to limit RAM usage, or to increase it in devices that have
-massive amounts of Flash or very small sized sectors and thus require a bigger
-configuration to allow for the handling of all slot's sectors. The factor of
-min-write-sz is due to the behavior of flash hardware. The factor of 3 is
-explained below.
+`BOOT_MAX_IMG_SECTORS` value is the configurable maximum number of sectors
+mcuboot supports for each image; its value defaults to 128, but allows for
+either decreasing this size, to limit RAM usage, or to increase it in devices
+that have massive amounts of Flash or very small sized sectors and thus require
+a bigger configuration to allow for the handling of all slot's sectors.
+The factor of min-write-sz is due to the behavior of flash hardware. The factor
+of 3 is explained below.
2. Swap size: When beginning a new swap operation, the total size that needs
- to be swapped (based on the slot with largest image + tlvs) is written to this
- location for easier recovery in case of a reset while performing the swap.
+ to be swapped (based on the slot with largest image + tlvs) is written to
+ this location for easier recovery in case of a reset while performing the
+ swap.
3. Copy done: A single byte indicating whether the image in this slot is
complete (0x01=done; 0xff=not done).
@@ -324,9 +327,9 @@
image trailers. When using the term "image trailers" what is meant is the
aggregate information provided by both image slot's trailers.
-The image trailers records are structured around the limitations imposed by flash
-hardware. As a consequence, they do not have a very intuitive design, and it
-is difficult to get a sense of the state of the device just by looking at the
+The image trailers records are structured around the limitations imposed by
+flash hardware. As a consequence, they do not have a very intuitive design, and
+it is difficult to get a sense of the state of the device just by looking at the
image trailers. It is better to map all the possible trailer states to the swap
types described above via a set of tables. These tables are reproduced below.
@@ -336,36 +339,36 @@
```
State I
- | slot-0 | slot-1 |
- -----------------+--------+--------|
- magic | Any | Good |
- image-ok | Any | Unset |
- copy-done | Any | Any |
- -----------------+--------+--------'
- result: BOOT_SWAP_TYPE_TEST |
- -----------------------------------'
+ | primary slot | secondary slot |
+ -----------------+--------------+----------------|
+ magic | Any | Good |
+ image-ok | Any | Unset |
+ copy-done | Any | Any |
+ -----------------+--------------+----------------'
+ result: BOOT_SWAP_TYPE_TEST |
+ -------------------------------------------------'
State II
- | slot-0 | slot-1 |
- -----------------+--------+--------|
- magic | Any | Good |
- image-ok | Any | 0x01 |
- copy-done | Any | Any |
- -----------------+--------+--------'
- result: BOOT_SWAP_TYPE_PERM |
- -----------------------------------'
+ | primary slot | secondary slot |
+ -----------------+--------------+----------------|
+ magic | Any | Good |
+ image-ok | Any | 0x01 |
+ copy-done | Any | Any |
+ -----------------+--------------+----------------'
+ result: BOOT_SWAP_TYPE_PERM |
+ -------------------------------------------------'
State III
- | slot-0 | slot-1 |
- -----------------+--------+--------|
- magic | Good | Unset |
- image-ok | 0xff | Any |
- copy-done | 0x01 | Any |
- -----------------+--------+--------'
- result: BOOT_SWAP_TYPE_REVERT |
- -----------------------------------'
+ | primary slot | secondary slot |
+ -----------------+--------------+----------------|
+ magic | Good | Unset |
+ image-ok | 0xff | Any |
+ copy-done | 0x01 | Any |
+ -----------------+--------------+----------------'
+ result: BOOT_SWAP_TYPE_REVERT |
+ -------------------------------------------------'
```
Any of the above three states results in mcuboot attempting to swap images.
@@ -375,30 +378,30 @@
```
State IV
- | slot-0 | slot-1 |
- -----------------+--------+--------|
- magic | Any | Any |
- image-ok | Any | Any |
- copy-done | Any | Any |
- -----------------+--------+--------'
- result: BOOT_SWAP_TYPE_NONE, |
- BOOT_SWAP_TYPE_FAIL, or |
- BOOT_SWAP_TYPE_PANIC |
- -----------------------------------'
+ | primary slot | secondary slot |
+ -----------------+--------------+----------------|
+ magic | Any | Any |
+ image-ok | Any | Any |
+ copy-done | Any | Any |
+ -----------------+--------------+----------------'
+ result: BOOT_SWAP_TYPE_NONE, |
+ BOOT_SWAP_TYPE_FAIL, or |
+ BOOT_SWAP_TYPE_PANIC |
+ -------------------------------------------------'
```
In State IV, when no errors occur, mcuboot will attempt to boot the contents of
-slot 0 directly, and the result is `BOOT_SWAP_TYPE_NONE`. If the image in slot 0
-is not valid, the result is `BOOT_SWAP_TYPE_FAIL`. If a fatal error occurs during
-boot, the result is `BOOT_SWAP_TYPE_PANIC`. If the result is either
-`BOOT_SWAP_TYPE_FAIL` or `BOOT_SWAP_TYPE_PANIC`, mcuboot hangs rather than booting
-an invalid or compromised image.
+the primary slot directly, and the result is `BOOT_SWAP_TYPE_NONE`. If the image
+in the primary slot is not valid, the result is `BOOT_SWAP_TYPE_FAIL`. If a
+fatal error occurs during boot, the result is `BOOT_SWAP_TYPE_PANIC`. If the
+result is either `BOOT_SWAP_TYPE_FAIL` or `BOOT_SWAP_TYPE_PANIC`, mcuboot hangs
+rather than booting an invalid or compromised image.
Note: An important caveat to the above is the result when a swap is requested
- and the image in slot 1 fails to validate, due to a hashing or signing
- error. This state behaves as State IV with the extra action of marking
- the image in slot 0 as "OK", to prevent further attempts to swap.
-
+ and the image in the secondary slot fails to validate, due to a hashing or
+ signing error. This state behaves as State IV with the extra action of
+ marking the image in the primary slot as "OK", to prevent further attempts
+ to swap.
## High-Level Operation
@@ -414,27 +417,27 @@
2. Inspect image trailers; is a swap requested?
Yes.
- 1. Is the requested image valid (integrity and security check)?
- Yes.
- a. Perform swap operation.
- b. Persist completion of swap procedure to image trailers.
- c. Proceed to step 3.
- No.
- a. Erase invalid image.
- b. Persist failure of swap procedure to image trailers.
- c. Proceed to step 3.
+ 1. Is the requested image valid (integrity and security check)?
+ Yes.
+ a. Perform swap operation.
+ b. Persist completion of swap procedure to image trailers.
+ c. Proceed to step 3.
+ No.
+ a. Erase invalid image.
+ b. Persist failure of swap procedure to image trailers.
+ c. Proceed to step 3.
No: Proceed to step 3.
-3. Boot into image in slot 0.
+3. Boot into image in primary slot.
## Image Swapping
The boot loader swaps the contents of the two image slots for two reasons:
- * User has issued a "set pending" operation; the image in slot-1 should be
- run once (state II) or repeatedly (state III), depending on whether a
- permanent swap was specified.
- * Test image rebooted without being confirmed; the boot loader should
- revert to the original image currently in slot-1 (state IV).
+ * User has issued a "set pending" operation; the image in the secondary slot
+ should be run once (state II) or repeatedly (state III), depending on
+ whether a permanent swap was specified.
+ * Test image rebooted without being confirmed; the boot loader should
+ revert to the original image currently in the secondary slot (state IV).
If the image trailers indicates that the image in the secondary slot should be
run, the boot loader needs to copy it to the primary slot. The image currently
@@ -445,73 +448,70 @@
<!-- Markdown doesn't do nested numbered lists. It will do nested
bulletted lists, so maybe that is better. -->
- 1. Determine how many flash sectors each image slot consists of. This
- number must be the same for both slots.
- 2. Iterate the list of sector indices in descending order (i.e., starting
- with the greatest index); current element = "index".
- b. Erase scratch area.
- c. Copy slot1[index] to scratch area.
- - If these are the last sectors (i.e., first swap being perfomed),
- copy the full sector *except* the image trailer.
- - Else, copy entire sector contents.
- d. Write updated swap status (i).
+ 1. Determine how many flash sectors each image slot consists of. This
+ number must be the same for both slots.
+ 2. Iterate the list of sector indices in descending order (i.e., starting
+ with the greatest index); current element = "index".
+ b. Erase scratch area.
+ c. Copy secondary_slot[index] to scratch area.
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ d. Write updated swap status (i).
+ e. Erase secondary_slot[index]
+ f. Copy primary_slot[index] to secondary_slot[index]
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ g. Write updated swap status (ii).
+ h. Erase primary_slot[index].
+ i. Copy scratch area to primary_slot[index].
+ - If these are the last sectors (i.e., first swap being perfomed),
+ copy the full sector *except* the image trailer.
+ - Else, copy entire sector contents.
+ j. Write updated swap status (iii).
+ 3. Persist completion of swap procedure to the primary slot image trailer.
- e. Erase slot1[index]
- f. Copy slot0[index] to slot1[index]
- - If these are the last sectors (i.e., first swap being perfomed),
- copy the full sector *except* the image trailer.
- - Else, copy entire sector contents.
- g. Write updated swap status (ii).
-
- h. Erase slot0[index].
- i. Copy scratch area to slot0[index].
- - If these are the last sectors (i.e., first swap being perfomed),
- copy the full sector *except* the image trailer.
- - Else, copy entire sector contents.
- j. Write updated swap status (iii).
-
- 3. Persist completion of swap procedure to slot 0 image trailer.
-
-The additional caveats in step 2f are necessary so that the slot 1 image
+The additional caveats in step 2f are necessary so that the secondary slot image
trailer can be written by the user at a later time. With the image trailer
-unwritten, the user can test the image in slot 1 (i.e., transition to state
-II).
+unwritten, the user can test the image in the secondary slot
+(i.e., transition to state II).
Note1: If the sector being copied is the last sector, then swap status is
temporarily maintained on scratch for the duration of this operation, always
-using slot0's area otherwise.
+using the primary slot's area otherwise.
Note2: The bootloader tries to copy only used sectors (based on largest image
installed on any of the slots), minimizing the amount of sectors copied and
reducing the amount of time required for a swap operation.
The particulars of step 3 vary depending on whether an image is being tested,
-permanently used, reverted or a validation failure of slot 1 happened when a
-swap was requested:
+permanently used, reverted or a validation failure of the secondary slot
+happened when a swap was requested:
* test:
- o Write slot0.copy_done = 1
+ o Write primary_slot.copy_done = 1
(swap caused the following values to be written:
- slot0.magic = BOOT_MAGIC
- slot0.image_ok = Unset)
+ primary_slot.magic = BOOT_MAGIC
+ primary_slot.image_ok = Unset)
* permanent:
- o Write slot0.copy_done = 1
+ o Write primary_slot.copy_done = 1
(swap caused the following values to be written:
- slot0.magic = BOOT_MAGIC
- slot0.image_ok = 0x01)
+ primary_slot.magic = BOOT_MAGIC
+ primary_slot.image_ok = 0x01)
* revert:
- o Write slot0.copy_done = 1
- o Write slot0.image_ok = 1
+ o Write primary_slot.copy_done = 1
+ o Write primary_slot.image_ok = 1
(swap caused the following values to be written:
- slot0.magic = BOOT_MAGIC)
+ primary_slot.magic = BOOT_MAGIC)
- * failure to validate slot 1:
- o Write slot0.image_ok = 1
+ * failure to validate the secondary slot:
+ o Write primary_slot.image_ok = 1
-After completing the operations as described above the image in slot 0 should
-be booted.
+After completing the operations as described above the image in the primary slot
+should be booted.
## Swap Status
@@ -547,17 +547,18 @@
enumerate the sectors in a single slot, starting at 0, we would have a list of
sector indices. Since there are two image slots, each sector index would
correspond to a pair of sectors. For example, sector index 0 corresponds to
-the first sector in slot 0 and the first sector in slot 1. Finally, reverse
-the list of indices such that the list starts with index `BOOT_MAX_IMG_SECTORS - 1`
-and ends with 0. The swap status region is a representation of this reversed list.
+the first sector in the primary slot and the first sector in the secondary slot.
+Finally, reverse the list of indices such that the list starts with index
+`BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is a
+representation of this reversed list.
During a swap operation, each sector index transitions through four separate
states:
```
- 0. slot 0: image 0, slot 1: image 1, scratch: N/A
- 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1->s, erase 1)
- 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0->1, erase 0)
- 3. slot 0: image 1, slot 1: image 0, scratch: N/A (s->0)
+0. primary slot: image 0, secondary slot: image 1, scratch: N/A
+1. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1)
+2. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0)
+3. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0)
```
Each time a sector index transitions to a new state, the boot loader writes a
@@ -580,14 +581,15 @@
```
The swap status region can accommodate `BOOT_MAX_IMG_SECTORS` sector indices.
-Hence, the size of the region, in bytes, is `BOOT_MAX_IMG_SECTORS * min-write-size * 3`.
-The only requirement for the index count is that it is great enough to account for a
-maximum-sized image (i.e., at least as great as the total sector count in an
-image slot). If a device's image slots have been configured with
-`BOOT_MAX_IMG_SECTORS: 128` and use less than 128 sectors, the first
-record that gets written will be somewhere in the middle of the region. For
-example, if a slot uses 64 sectors, the first sector index that gets swapped is
-63, which corresponds to the exact halfway point within the region.
+Hence, the size of the region, in bytes, is
+`BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index
+count is that it is great enough to account for a maximum-sized image
+(i.e., at least as great as the total sector count in an image slot). If a
+device's image slots have been configured with `BOOT_MAX_IMG_SECTORS: 128` and
+use less than 128 sectors, the first record that gets written will be somewhere
+in the middle of the region. For example, if a slot uses 64 sectors, the first
+sector index that gets swapped is 63, which corresponds to the exact halfway
+point within the region.
Note: since the scratch area only ever needs to record swapping of the last
sector, it uses at most min-write-size * 3 bytes for its own status area.
@@ -605,53 +607,53 @@
indicates where the swap status region is located.
```
- | slot-0 | scratch |
- ----------+------------+------------|
- magic | Good | Any |
- copy-done | 0x01 | N/A |
- ----------+------------+------------'
- source: none |
- ------------------------------------'
+ | primary slot | scratch |
+ ----------+--------------+--------------|
+ magic | Good | Any |
+ copy-done | 0x01 | N/A |
+ ----------+--------------+--------------'
+ source: none |
+ ----------------------------------------'
- | slot-0 | scratch |
- ----------+------------+------------|
- magic | Good | Any |
- copy-done | 0xff | N/A |
- ----------+------------+------------'
- source: slot 0 |
- ------------------------------------'
+ | primary slot | scratch |
+ ----------+--------------+--------------|
+ magic | Good | Any |
+ copy-done | 0xff | N/A |
+ ----------+--------------+--------------'
+ source: primary slot |
+ ----------------------------------------'
- | slot-0 | scratch |
- ----------+------------+------------|
- magic | Any | Good |
- copy-done | Any | N/A |
- ----------+------------+------------'
- source: scratch |
- ------------------------------------'
+ | primary slot | scratch |
+ ----------+--------------+--------------|
+ magic | Any | Good |
+ copy-done | Any | N/A |
+ ----------+--------------+--------------'
+ source: scratch |
+ ----------------------------------------'
- | slot-0 | scratch |
- ----------+------------+------------|
- magic | Unset | Any |
- copy-done | 0xff | N/A |
- ----------+------------+------------|
- source: slot 0 |
- ------------------------------------+------------------------------+
- This represents one of two cases: |
- o No swaps ever (no status to read, so no harm in checking). |
- o Mid-revert; status in slot 0. |
- For this reason we assume slot 0 as source, to trigger a check |
- of the status area and find out if there was swapping under way. |
- -------------------------------------------------------------------'
+ | primary slot | scratch |
+ ----------+--------------+--------------|
+ magic | Unset | Any |
+ copy-done | 0xff | N/A |
+ ----------+--------------+--------------|
+ source: primary slot |
+ ----------------------------------------+------------------------------+
+ This represents one of two cases: |
+ o No swaps ever (no status to read, so no harm in checking). |
+ o Mid-revert; status in the primary slot. |
+ For this reason we assume the primary slot as source, to trigger a |
+ check of the status area and find out if there was swapping under way. |
+ -----------------------------------------------------------------------'
```
If the swap status region indicates that the images are not contiguous,
bootutil completes the swap operation that was in progress when the system was
reset. In other words, it applies the procedure defined in the previous
-section, moving image 1 into slot 0 and image 0 into slot 1. If the boot
-status file indicates that an image part is present in the scratch area, this
-part is copied into the correct location by starting at step e or step h in the
-area-swap procedure, depending on whether the part belongs to image 0 or image
-1.
+section, moving image 1 into the primary slot and image 0 into the secondary
+slot. If the boot status file indicates that an image part is present in the
+scratch area, this part is copied into the correct location by starting at step
+e or step h in the area-swap procedure, depending on whether the part belongs to
+image 0 or image 1.
After the swap operation has been completed, the boot loader proceeds as though
it had just been started.
@@ -660,20 +662,21 @@
An image is checked for integrity immediately before it gets copied into the
primary slot. If the boot loader doesn't perform an image swap, then it can
-perform an optional integrity check of the image in slot0 if
-`MCUBOOT_VALIDATE_SLOT0` is set, otherwise it doesn't perform an integrity check.
+perform an optional integrity check of the image in the primary slot if
+`MCUBOOT_VALIDATE_PRIMARY_SLOT` is set, otherwise it doesn't perform an
+integrity check.
During the integrity check, the boot loader verifies the following aspects of
an image:
- * 32-bit magic number must be correct (0x96f3b83d).
- * Image must contain an `image_tlv_info` struct, identified by its magic
- (0x6907) exactly following the firmware (hdr_size + img_size).
- * Image must contain a SHA256 TLV.
- * Calculated SHA256 must match SHA256 TLV contents.
- * Image *may* contain a signature TLV. If it does, it must also have a
- KEYHASH TLV with the hash of the key that was used to sign. The list of
- keys will then be iterated over looking for the matching key, which then
- will then be used to verify the image contents.
+ * 32-bit magic number must be correct (0x96f3b83d).
+ * Image must contain an `image_tlv_info` struct, identified by its magic
+ (0x6907) exactly following the firmware (hdr_size + img_size).
+ * Image must contain a SHA256 TLV.
+ * Calculated SHA256 must match SHA256 TLV contents.
+ * Image *may* contain a signature TLV. If it does, it must also have a
+ KEYHASH TLV with the hash of the key that was used to sign. The list of
+ keys will then be iterated over looking for the matching key, which then
+ will then be used to verify the image contents.
## Security
diff --git a/docs/encrypted_images.md b/docs/encrypted_images.md
index 82700e3..bc38ae7 100644
--- a/docs/encrypted_images.md
+++ b/docs/encrypted_images.md
@@ -27,16 +27,16 @@
The image header needs to flag this image as `ENCRYPTED` (0x04) and
a TLV with the key must be present in the image. When upgrading the
-image from `slot1` to `slot0` it is automatically decrypted (after
-validation). If swap upgrades are enabled, the image located in `slot0`,
-also having the `ENCRYPTED` flag set and the TLV present, is
-re-encrypted while swapping to `slot1`.
+image from the `secondary slot` to the `primary slot` it is automatically
+decrypted (after validation). If swap upgrades are enabled, the image
+located in the `primary slot`, also having the `ENCRYPTED` flag set and the
+TLV present, is re-encrypted while swapping to the `secondary slot`.
## Threat model
The encrypted image support is supposed to allow for confidentiality
if the image is not residing on the device or is written to external
-storage, eg a SPI flash being used for slot1.
+storage, eg a SPI flash being used for the secondary slot.
It does not protect against the possibility of attaching a JTAG and
reading the internal flash memory, or using some attack vector that
@@ -79,24 +79,25 @@
## Upgrade process
-When starting a new upgrade process, `MCUBoot` checks that the image in
-`slot1` has the `ENCRYPTED` flag set and has the required TLV with the
+When starting a new upgrade process, `MCUBoot` checks that the image in the
+`secondary slot` has the `ENCRYPTED` flag set and has the required TLV with the
encrypted key. It then uses its internal private/secret key to decrypt
the TLV containing the key. Given that no errors are found, it will then
start the validation process, decrypting the blocks before check. A good
image being determined, the upgrade consists in reading the blocks from
-`slot1`, decrypting and writing to `slot0`.
+the `secondary slot`, decrypting and writing to the `primary slot`.
If swap is used for the upgrade process, the encryption happens when
-copying the sectors of `slot1` to the scratch area.
+copying the sectors of the `secondary slot` to the scratch area.
The `scratch` area is not encrypted, so it must reside in the internal
flash of the MCU to avoid attacks that could interrupt the upgrade and
dump the data.
-Also when swap is used, the image in `slot0` is checked for presence of
-the `ENCRYPTED` flag and the key TLV. If those are present the sectors
-are re-encrypted when copying from `slot0` to `slot1`.
+Also when swap is used, the image in the `primary slot` is checked for
+presence of the `ENCRYPTED` flag and the key TLV. If those are present the
+sectors are re-encrypted when copying from the `primary slot` to
+the `secondary slot`.
PS: Each encrypted image must have its own key TLV that should be unique
and used only for this particular image.
diff --git a/docs/imgtool.md b/docs/imgtool.md
index 1d5a7d7..baace5f 100644
--- a/docs/imgtool.md
+++ b/docs/imgtool.md
@@ -47,8 +47,8 @@
## Signing images
-Image signing takes an image in binary or Intel Hex format intended for Slot 0
-and adds a header and trailer that the bootloader is expecting:
+Image signing takes an image in binary or Intel Hex format intended for the
+primary slot and adds a header and trailer that the bootloader is expecting:
Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE
@@ -61,8 +61,8 @@
-H, --header-size INTEGER [required]
--pad-header Add --header-size zeroed bytes at the beginning
of the image
- -S, --slot-size INTEGER Size of the slot where the image will be written
- [required]
+ -S, --slot-size INTEGER Size of the slot where the image will be
+ written [required]
--pad Pad image to --slot-size bytes, adding trailer
magic
-M, --max-sectors INTEGER When padding allow for this amount of sectors
@@ -93,5 +93,5 @@
status area size when calculating overflow.
The optional `--pad` argument will place a trailer on the image that
-indicates that the image should be considered an upgrade. Writing
-this image in slot 1 will then cause the bootloader to upgrade to it.
+indicates that the image should be considered an upgrade. Writing this image
+in the secondary slot will then cause the bootloader to upgrade to it.
diff --git a/docs/readme-zephyr.md b/docs/readme-zephyr.md
index fd07244..ac183c5 100644
--- a/docs/readme-zephyr.md
+++ b/docs/readme-zephyr.md
@@ -13,8 +13,8 @@
partitions defined in its device tree. These partitions are:
- `boot_partition`: for MCUboot itself
-- `slot0_partition`: the primary image slot
-- `slot1_partition`: the secondary image slot
+- `primary_slot_partition`: the primary image slot
+- `secondary_slot_partition`: the secondary image slot
- `scratch_partition`: the scratch slot
Currently, the two image slots must be contiguous. If you are running
@@ -43,7 +43,7 @@
be made before building it. Most of this can be done as documented in
the `CMakeLists.txt` file in boot/zephyr. There are comments there for
guidance. It is important to select a signature algorithm, and decide
-if slot0 should be validated on every boot.
+if the primary slot should be validated on every boot.
To build MCUboot, create a build directory in boot/zephyr, and build
it as usual:
@@ -96,7 +96,7 @@
### Signing the application
In order to upgrade to an image (or even boot it, if
-`MCUBOOT_VALIDATE_SLOT0` is enabled), the images must be signed.
+`MCUBOOT_VALIDATE_PRIMARY_SLOT` is enabled), the images must be signed.
To make development easier, MCUboot is distributed with some example
keys. It is important to stress that these should never be used for
production, since the private key is publicly available in this
@@ -108,17 +108,17 @@
### Flashing the application
The application itself can flashed with regular flash tools, but will
-need to be programmed at the offset of slot-0 for this particular target.
-Depending on the platform and flash tool you might need to manually specify a
-flash offset corresponding to the slot-0 starting address. This is usually
-not relevant for flash tools that use Intel Hex images (.hex) instead of raw
-binary images (.bin) since the former include destination address information.
-Additionally you will need to make sure that the flash tool does not perform
-a mass erase (erasing the whole of the flash) or else you would be deleting
-MCUboot.
-These images can also be marked for upgrade, and loaded into slot-1,
+need to be programmed at the offset of the primary slot for this particular
+target. Depending on the platform and flash tool you might need to manually
+specify a flash offset corresponding to the primary slot starting address. This
+is usually not relevant for flash tools that use Intel Hex images (.hex) instead
+of raw binary images (.bin) since the former include destination address
+information. Additionally you will need to make sure that the flash tool does
+not perform a mass erase (erasing the whole of the flash) or else you would be
+deleting MCUboot.
+These images can also be marked for upgrade, and loaded into the secondary slot,
at which point the bootloader should perform an upgrade. It is up to
-the image to mark slot-0 as "image ok" before the next reboot,
+the image to mark the primary slot as "image ok" before the next reboot,
otherwise the bootloader will revert the application.
## Managing signing keys