Update design doc with BOOT_MAX_IMG_SECTORS config
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/docs/design.md b/docs/design.md
index 3b6e335..5bd0b6a 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -252,7 +252,7 @@
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
- ~ Swap status (128 * min-write-size * 3) ~
+ ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Swap size |
@@ -289,9 +289,13 @@
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
-factor of 128 is the maximum number of sectors mcuboot supports for each image;
-its value is a bootloader design decision. 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
@@ -543,11 +547,9 @@
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. Furthermore, we
-impose a limit of 128 indices. If an image slot consists of more than 128
-sectors, the flash layout is not compatible with this boot loader. Finally,
-reverse the list of indices such that the list starts with index 127 and ends
-with 0. The swap status region is a representation of this reversed list.
+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.
During a swap operation, each sector index transitions through four separate
states:
@@ -577,12 +579,12 @@
state 3 | 0x01 | 0x02 | 0x03
```
-The swap status region can accommodate 128 sector indices. Hence, the size of
-the region, in bytes, is `128 * min-write-size * 3`. The number 128 is chosen
-somewhat arbitrarily and will likely be made configurable. The only
-requirement for the index count is that is is great enough to account for a
+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 use less than 128 sectors, the first
+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.