Boot: Extend flash layout for multiple images
This patch introduces the BOOT_IMAGE_NUMBER macro and current_image
variable to support multiple updatable images and the associated
extended flash layout.
The FLASH_AREA_IMAGE_* object-like macros are replaced with
function-like ones and therefore some functions have been updated,
because the labels of a switch statement and the initialization
values of objects with static storage duration have to be constant
expressions.
Change-Id: Ib7b26ec3c94233e52db4f97825ddb6a3e55bb1d3
Signed-off-by: David Vincze <david.vincze@arm.com>
diff --git a/docs/PORTING.md b/docs/PORTING.md
index 2a63d50..ad2b885 100644
--- a/docs/PORTING.md
+++ b/docs/PORTING.md
@@ -86,9 +86,19 @@
`fa_id` is can be one of the following options:
```c
-#define FLASH_AREA_IMAGE_PRIMARY 1
-#define FLASH_AREA_IMAGE_SECONDARY 2
-#define FLASH_AREA_IMAGE_SCRATCH 3
+/* Independent from multiple image boot */
+#define FLASH_AREA_BOOTLOADER 0
+#define FLASH_AREA_IMAGE_SCRATCH 3
+```
+```c
+/* Flash area IDs of the first image in case of multiple images */
+#define FLASH_AREA_IMAGE_PRIMARY 1
+#define FLASH_AREA_IMAGE_SECONDARY 2
+```
+```c
+/* Flash area IDs of the second image in case of multiple images */
+#define FLASH_AREA_IMAGE_PRIMARY 5
+#define FLASH_AREA_IMAGE_SECONDARY 6
```
The functions that must be defined for working with the `flash_area`s are:
diff --git a/docs/design.md b/docs/design.md
index d86d89d..edb98c6 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -116,33 +116,44 @@
2. A write to one area does not restrict writes to other areas.
The boot loader uses the following flash area IDs:
-
-``` c
+```c
+/* Independent from multiple image boot */
#define FLASH_AREA_BOOTLOADER 0
+#define FLASH_AREA_IMAGE_SCRATCH 3
+```
+```c
+/* If the boot loader is working with the first image */
#define FLASH_AREA_IMAGE_PRIMARY 1
#define FLASH_AREA_IMAGE_SECONDARY 2
-#define FLASH_AREA_IMAGE_SCRATCH 3
+```
+```c
+/* If the boot loader is working with the second image */
+#define FLASH_AREA_IMAGE_PRIMARY 5
+#define FLASH_AREA_IMAGE_SECONDARY 6
```
The bootloader area contains the bootloader image itself. The other areas are
-described in subsequent sections.
+described in subsequent sections. The flash could contain multiple executable
+images therefore the flash area IDs of primary and secondary areas are mapped
+based on the number of the active image (on which the bootloader is currently
+working).
## Image Slots
-A portion of the flash memory is partitioned into two image slots: a primary
-slot (0) and a secondary slot (1). The boot loader will only run an image from
-the primary slot, so images must be built such that they can run from that
-fixed location in flash. If the boot loader needs to run the image resident in
-the secondary slot, it must copy its contents into the primary slot before doing
-so, either by swapping the two images or by overwriting the contents of the
-primary slot. The bootloader supports either swap- or overwrite-based image
-upgrades, but must be configured at build time to choose one of these two
-strategies.
+A portion of the flash memory can be partitioned into multiple image areas, each
+contains two image slots: a primary slot and a secondary slot.
+The boot loader will only run an image from the primary slot, so images must be
+built such that they can run from that fixed location in flash. If the boot
+loader needs to run the image resident in the secondary slot, it must copy its
+contents into the primary slot before doing so, either by swapping the two
+images or by overwriting the contents of the primary slot. The bootloader
+supports either swap- or overwrite-based image upgrades, but must be configured
+at build time to choose one of these two strategies.
-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
+In addition to the slots of image areas, 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