Describe the tradeoffs of scratch size
JIRA: MCUB-74
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/docs/design.md b/docs/design.md
index 7c5b9ca..24f988a 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -138,7 +138,45 @@
strategies.
In addition to the two image slots, the boot loader requires a scratch area to
-allow for reliable image swapping.
+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:
+
+* the ratio of image size / scratch size
+* the number of erase cycles supported by the flash hardware
+
+The image size is used (instead of slot size) because only the slot's sectors
+that are actually used for storing the image are copied. The image/scratch ratio
+is the number of times the scratch will be erased on every upgrade. The number
+of erase cycles divided by the image/scratch ratio will give you the number of
+times an upgrade can be performed before the device goes out of spec.
+
+```
+num_upgrades = number_of_erase_cycles / (image_size / scratch_size)
+```
+
+Let's assume, for example, a device with 10000 erase cycles, an image size of
+150K and a scratch of 4K (usual minimum size of 4K sector devices). This would
+result in a total of:
+
+`10000 / (150 / 4) ~ 267`
+
+Increasing the scratch to 16K would give us:
+
+`10000 / (150 / 16) ~ 1067`
+
+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.
The overwrite upgrade strategy is substantially simpler to implement than the
image swapping strategy, especially since the bootloader must work properly