Use better naming for swap copy/erase functions
Since a copy/erase during a swap can result in some number of sectors
erased and copied, which is not necessarily equal to 1, update design
document and bootloader function naming to reflect this fact, by using
the postfix "_region" instead of "_sector" in those cases.
This fixes #541
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/boot/bootutil/src/loader.c b/boot/bootutil/src/loader.c
index 4da6e8e..c646efb 100644
--- a/boot/bootutil/src/loader.c
+++ b/boot/bootutil/src/loader.c
@@ -1022,7 +1022,7 @@
* @return 0 on success; nonzero on failure.
*/
static inline int
-boot_erase_sector(const struct flash_area *fap, uint32_t off, uint32_t sz)
+boot_erase_region(const struct flash_area *fap, uint32_t off, uint32_t sz)
{
return flash_area_erase(fap, off, sz);
}
@@ -1042,7 +1042,7 @@
* @return 0 on success; nonzero on failure.
*/
static int
-boot_copy_sector(struct boot_loader_state *state,
+boot_copy_region(struct boot_loader_state *state,
const struct flash_area *fap_src,
const struct flash_area *fap_dst,
uint32_t off_src, uint32_t off_dst, uint32_t sz)
@@ -1221,7 +1221,7 @@
do {
sz = boot_img_sector_size(state, slot, sector);
off = boot_img_sector_off(state, slot, sector);
- rc = boot_erase_sector(fap, off, sz);
+ rc = boot_erase_region(fap, off, sz);
assert(rc == 0);
sector--;
@@ -1299,7 +1299,7 @@
if (bs->state == BOOT_STATUS_STATE_0) {
BOOT_LOG_DBG("erasing scratch area");
- rc = boot_erase_sector(fap_scratch, 0, fap_scratch->fa_size);
+ rc = boot_erase_region(fap_scratch, 0, fap_scratch->fa_size);
assert(rc == 0);
if (bs->idx == BOOT_STATUS_IDX_0) {
@@ -1322,12 +1322,12 @@
assert(rc == 0);
/* Erase the temporary trailer from the scratch area. */
- rc = boot_erase_sector(fap_scratch, 0, fap_scratch->fa_size);
+ rc = boot_erase_region(fap_scratch, 0, fap_scratch->fa_size);
assert(rc == 0);
}
}
- rc = boot_copy_sector(state, fap_secondary_slot, fap_scratch,
+ rc = boot_copy_region(state, fap_secondary_slot, fap_scratch,
img_off, 0, copy_sz);
assert(rc == 0);
@@ -1337,10 +1337,10 @@
}
if (bs->state == BOOT_STATUS_STATE_1) {
- rc = boot_erase_sector(fap_secondary_slot, img_off, sz);
+ rc = boot_erase_region(fap_secondary_slot, img_off, sz);
assert(rc == 0);
- rc = boot_copy_sector(state, fap_primary_slot, fap_secondary_slot,
+ rc = boot_copy_region(state, fap_primary_slot, fap_secondary_slot,
img_off, img_off, copy_sz);
assert(rc == 0);
@@ -1358,13 +1358,13 @@
}
if (bs->state == BOOT_STATUS_STATE_2) {
- rc = boot_erase_sector(fap_primary_slot, img_off, sz);
+ rc = boot_erase_region(fap_primary_slot, img_off, sz);
assert(rc == 0);
/* NOTE: If this is the final sector, we exclude the image trailer from
* this copy (copy_sz was truncated earlier).
*/
- rc = boot_copy_sector(state, fap_scratch, fap_primary_slot,
+ rc = boot_copy_region(state, fap_scratch, fap_primary_slot,
0, img_off, copy_sz);
assert(rc == 0);
@@ -1372,7 +1372,7 @@
scratch_trailer_off = boot_status_off(fap_scratch);
/* copy current status that is being maintained in scratch */
- rc = boot_copy_sector(state, fap_scratch, fap_primary_slot,
+ rc = boot_copy_region(state, fap_scratch, fap_primary_slot,
scratch_trailer_off, img_off + copy_sz,
(BOOT_STATUS_STATE_COUNT - 1) * BOOT_WRITE_SZ(state));
BOOT_STATUS_ASSERT(rc == 0);
@@ -1420,7 +1420,7 @@
BOOT_STATUS_ASSERT(rc == 0);
if (erase_scratch) {
- rc = boot_erase_sector(fap_scratch, 0, sz);
+ rc = boot_erase_region(fap_scratch, 0, sz);
assert(rc == 0);
}
}
@@ -1482,7 +1482,7 @@
sect_count = boot_img_num_sectors(state, BOOT_PRIMARY_SLOT);
for (sect = 0, size = 0; sect < sect_count; sect++) {
this_size = boot_img_sector_size(state, BOOT_PRIMARY_SLOT, sect);
- rc = boot_erase_sector(fap_primary_slot, size, this_size);
+ rc = boot_erase_region(fap_primary_slot, size, this_size);
assert(rc == 0);
size += this_size;
@@ -1511,7 +1511,7 @@
BOOT_LOG_INF("Copying the secondary slot to the primary slot: 0x%zx bytes",
size);
- rc = boot_copy_sector(state, fap_secondary_slot, fap_primary_slot, 0, 0, size);
+ rc = boot_copy_region(state, fap_secondary_slot, fap_primary_slot, 0, 0, size);
/*
* Erases header and trailer. The trailer is erased because when a new
@@ -1519,13 +1519,13 @@
* trailer that was left might trigger a new upgrade.
*/
BOOT_LOG_DBG("erasing secondary header");
- rc = boot_erase_sector(fap_secondary_slot,
+ rc = boot_erase_region(fap_secondary_slot,
boot_img_sector_off(state, BOOT_SECONDARY_SLOT, 0),
boot_img_sector_size(state, BOOT_SECONDARY_SLOT, 0));
assert(rc == 0);
last_sector = boot_img_num_sectors(state, BOOT_SECONDARY_SLOT) - 1;
BOOT_LOG_DBG("erasing secondary trailer");
- rc = boot_erase_sector(fap_secondary_slot,
+ rc = boot_erase_region(fap_secondary_slot,
boot_img_sector_off(state, BOOT_SECONDARY_SLOT,
last_sector),
boot_img_sector_size(state, BOOT_SECONDARY_SLOT,
diff --git a/docs/design.md b/docs/design.md
index 1a4fc5c..1791e56 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -616,30 +616,33 @@
To be compatible, both have to have only sectors that can fit into the
scratch area and if one of them has larger sectors than the other, it must
be able to entirely fit some rounded number of sectors from the other slot.
-2. Iterate the list of sector indices in descending order (i.e., starting
- with the greatest index); only sectors that are predetermined to be part of
+ In the next steps we'll use the terminology "region" for the total amount of
+ data copied/erased because this can be any amount of sectors depending on
+ how many the scratch is able to fit for some swap operation.
+2. Iterate the list of region indices in descending order (i.e., starting
+ with the greatest index); only regions that are predetermined to be part of
the image are copied; current element = "index".
+ a. Erase scratch area.
+ b. Copy secondary_slot[index] to scratch area.
- - If this is the last sector in the slot, scratch area has a temporary
+ - If this is the last region in the slot, scratch area has a temporary
status area initialized to store the initial state, because the
- primary slot's last sector will have to be erased. In this case,
+ primary slot's last region will have to be erased. In this case,
only the data that was calculated to amount to the image is copied.
- - Else if this is the first swapped sector but not the last sector in
+ - Else if this is the first swapped region but not the last region in
the slot, initialize the status area in primary slot and copy the
- full sector contents.
- - Else, copy entire sector contents.
+ full region contents.
+ - Else, copy entire region contents.
+ c. Write updated swap status (i).
+ d. Erase secondary_slot[index]
+ e. Copy primary_slot[index] to secondary_slot[index] according to amount
previosly copied at step b.
- - If this is not the last sector in the slot, erase the trailer in the
+ - If this is not the last region in the slot, erase the trailer in the
secondary slot, to always use the one in the primary slot.
+ f. Write updated swap status (ii).
+ g. Erase primary_slot[index].
+ h. Copy scratch area to primary_slot[index] according to amount
previously copied at step b.
- - If this is the last sector in the slot, the status is read from
+ - If this is the last region in the slot, the status is read from
scratch (where it was stored temporarily) and written anew in the
primary slot.
+ i. Write updated swap status (iii).
@@ -650,7 +653,7 @@
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
+Note1: If the region being copied contains the last sector, then swap status is
temporarily maintained on scratch for the duration of this operation, always
using the primary slot's area otherwise.