Update design doc for compliance with implementation
Fixes: MCUB-67
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/doc/design.txt b/doc/design.txt
index e7d5195..e0b6067 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -200,11 +200,12 @@
Revert to image 1 on next reboot |
---------------------------------'
-*** BOOT VECTOR
+*** IMAGE TRAILER
-At startup, the boot loader determines which of the above three states the
-device is in by inspecting the boot vector. The boot vector consists of two
-records (called "image trailers"), one written at the end of each image slot.
+For the bootloader to be able to determine the current state and what actions
+should be taken during the current boot operation, it uses metadata existing
+on both slots, and while doing a swap operation it can be located in scratch.
+This metadata is located at the end of the slot and is called image trailer.
An image trailer has the following structure:
0 1 2 3
@@ -252,32 +253,29 @@
0x8079b62c,
};
-The boot vector records are structured around the limitations imposed by flash
+*** IMAGE TRAILERS
+
+At startup, the boot loader determines which of the above four states the
+device is in by inspecting the 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
-boot vector. It is better to map all the possible vector states to the three
+image trailers. It is better to map all the possible trailer states to the four
states described above via a set of tables. These tables are reproduced below.
In these tables, the "pending" and "confirmed" flags are shown for illustrative
-purposes; they are not actually present in the boot vector.
+purposes; they are not actually present in the image trailers.
+
+Note: An important caveat about the tables described below is that they must
+be evaluated in the order presented here. Lower state numbers must have a
+higher priority when testing the image trailers.
State I
| slot-0 | slot-1 |
-----------------+--------+--------|
- magic | Unset | Unset |
- image-ok | Any | Any |
- copy-done | Any | Any |
- -----------------+--------+--------'
- pending | | |
- confirmed | X | |
- -----------------+--------+--------'
- swap: none |
- -----------------------------------'
-
-
- State II
- | slot-0 | slot-1 |
- -----------------+--------+--------|
magic | Any | Good |
image-ok | Any | Unset |
copy-done | Any | Any |
@@ -289,7 +287,7 @@
-----------------------------------'
- State III
+ State II
| slot-0 | slot-1 |
-----------------+--------+--------|
magic | Any | Good |
@@ -303,7 +301,7 @@
-----------------------------------'
- State IV
+ State III
| slot-0 | slot-1 |
-----------------+--------+--------|
magic | Good | Unset |
@@ -316,23 +314,40 @@
swap: revert (test image running) |
-----------------------------------'
-Note: copy-done is only used to determine if the current image was the result
-of a swap operation or if it was written by the provided imgtool, in which case
-no revert is performed. All other states don't need it.
- State V
+Those three states described above are explicity tested for and result in a
+swap decision by the bootloader. If the existing values in the the image trailers
+are not one of those previously described the bootloader will assume no swap
+operation is to be performed which is illustrated by state IV.
+
+
+ State IV
| slot-0 | slot-1 |
-----------------+--------+--------|
- magic | Good | Unset |
- image-ok | 0x01 | Any |
+ magic | Any | Any |
+ image-ok | Any | Any |
copy-done | Any | Any |
-----------------+--------+--------'
pending | | |
confirmed | X | |
-----------------+--------+--------'
- swap: none (confirmed test image) |
+ swap: none |
-----------------------------------'
+
+Note: An important caveat to be mentioned here is, that due to the physical
+limitations of the storage and another possible failure, two extra "states"
+were added specifically to signal a failure in the boot process.
+
+1. One of them is a result of any device read/write error, called panic and
+ will result in the bootloader hanging without booting the image in slot 0.
+
+2. Another state was added specifically to handle the situation in which a swap
+ was requested and the image in slot 1 fails to validate, due to hashing
+ or signing error. This state behaves as state IV with the extra action of
+ marking the image in slot 0 as confirmed.
+
+
*** HIGH-LEVEL OPERATION
With the terms defined, we can now explore the boot loader's operation. First,
@@ -341,27 +356,25 @@
Procedure:
-A. Inspect swap status region; is an interrupted swap is being resumed?
+A. Inspect swap status region; is an interrupted swap being resumed?
Yes: Complete the partial swap operation; skip to step C.
No: Proceed to step B.
-B. Insect boot vector; is a swap requested?
+B. 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 boot vector.
+ b. Persist completion of swap procedure to image trailers.
c. Proceed to step C.
No.
a. Erase invalid image.
- b. Persist failure of swap procedure to boot vector.
+ b. Persist failure of swap procedure to image trailers.
c. Proceed to step C.
No: Proceed to step C.
C. Boot into image in slot 0.
-
-
*** IMAGE SWAPPING
The boot loader swaps the contents of the two image slots for two reasons:
@@ -371,7 +384,7 @@
* Test image rebooted without being confirmed; the boot loader should
revert to the original image currently in slot-1 (state IV).
-If the boot vector indicates that the image in the secondary slot should be
+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
in the primary slot also needs to be retained in flash so that it can be used
later. Furthermore, both images need to be recoverable if the boot loader
@@ -419,26 +432,32 @@
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, or reverted:
+permanently used, reverted or a validation failure of slot 1 happened when a
+swap was requested:
+
* test:
o Write slot0.copy_done = 1
(swap caused the following values to be written:
slot0.magic = BOOT_MAGIC
slot0.image_ok = Unset)
- (should now be in state IV)
* permanent:
o Write slot0.copy_done = 1
(swap caused the following values to be written:
slot0.magic = BOOT_MAGIC
slot0.image_ok = 0x01)
- (should now be in state V)
* revert:
- o Write slot0.magic = BOOT_MAGIC
o Write slot0.copy_done = 1
o Write slot0.image_ok = 1
- (should now be in state V)
+ (swap caused the following values to be written:
+ slot0.magic = BOOT_MAGIC)
+
+ * failure to validate slot 1:
+ o Write slot0.image_ok = 1
+
+After completing the operations as described above the image in slot 0 should
+be booted.
*** SWAP STATUS
@@ -515,16 +534,15 @@
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.
-
*** RESET RECOVERY
If the boot loader resets in the middle of a swap operation, the two images may
be discontiguous in flash. Bootutil recovers from this condition by using the
-boot vector to determine how the image parts are distributed in flash.
+image trailers to determine how the image parts are distributed in flash.
The first step is determine where the relevant swap status region is located.
Because this region is embedded within the image slots, its location in flash
-changes during a swap operation. The below set of tables map boot vector
+changes during a swap operation. The below set of tables map image trailers
contents to swap status location. In these tables, the "source" field
indicates where the swap status region is located.
@@ -557,11 +575,13 @@
magic | Unset | Any |
copy-done | 0xff | N/A |
----------+------------+------------|
- source: varies |
+ 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. |
-------------------------------------------------------------------'
@@ -588,7 +608,7 @@
an image:
* 32-bit magic number must be correct (0x96f3b83c).
* Image must contain a SHA256 TLV.
- * Calculated SHA256 must matche SHA256 TLV contents.
+ * Calculated SHA256 must match SHA256 TLV contents.
* Image *may* contain a signature TLV. If it does, its contents must be
verifiable using a key embedded in the boot loader.