diff options
Diffstat (limited to 'docs/pages/bootloader.adoc')
| -rw-r--r-- | docs/pages/bootloader.adoc | 12 |
1 files changed, 10 insertions, 2 deletions
diff --git a/docs/pages/bootloader.adoc b/docs/pages/bootloader.adoc index 3b0cdb182..b0f0331aa 100644 --- a/docs/pages/bootloader.adoc +++ b/docs/pages/bootloader.adoc | |||
| @@ -2,6 +2,13 @@ | |||
| 2 | 2 | ||
| 3 | `embassy-boot` a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks. | 3 | `embassy-boot` a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks. |
| 4 | 4 | ||
| 5 | The update method used is referred to as an A/B partition update scheme. | ||
| 6 | |||
| 7 | With a general-purpose OS, A/B partition update is accomplished by directly booting either the A or B partition depending on the update state. | ||
| 8 | To accomplish the same goal in a way that is portable across all microcontrollers, `embassy-boot` swaps data page by page (in both directions) between the DFU and the Active partition when a firmware update is triggered. + | ||
| 9 | Because the original Active application is moved into the DFU partition during this update, the operation can be reversed if the update is interrupted or the new firmware does not flag that it booted successfully. + | ||
| 10 | See the design section for more details on how this is implemented. | ||
| 11 | |||
| 5 | The bootloader can be used either as a library or be flashed directly if you are happy with the default configuration and capabilities. | 12 | The bootloader can be used either as a library or be flashed directly if you are happy with the default configuration and capabilities. |
| 6 | 13 | ||
| 7 | By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself. | 14 | By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself. |
| @@ -19,6 +26,8 @@ The bootloader supports | |||
| 19 | 26 | ||
| 20 | In general, the bootloader works on any platform that implements the `embedded-storage` traits for its internal flash, but may require custom initialization code to work. | 27 | In general, the bootloader works on any platform that implements the `embedded-storage` traits for its internal flash, but may require custom initialization code to work. |
| 21 | 28 | ||
| 29 | STM32L0x1 devices require the `flash-erase-zero` feature to be enabled. | ||
| 30 | |||
| 22 | == Design | 31 | == Design |
| 23 | 32 | ||
| 24 | image::bootloader_flash.png[Bootloader flash layout] | 33 | image::bootloader_flash.png[Bootloader flash layout] |
| @@ -86,8 +95,7 @@ Then, to sign your firmware given a declaration of `FIRMWARE_DIR` and a firmware | |||
| 86 | 95 | ||
| 87 | [source, bash] | 96 | [source, bash] |
| 88 | ---- | 97 | ---- |
| 89 | shasum -a 512 -b $FIRMWARE_DIR/myfirmware > $SECRETS_DIR/message.txt | 98 | shasum -a 512 -b $FIRMWARE_DIR/myfirmware | head -c128 | xxd -p -r > $SECRETS_DIR/message.txt |
| 90 | cat $SECRETS_DIR/message.txt | dd ibs=128 count=1 | xxd -p -r > $SECRETS_DIR/message.txt | ||
| 91 | signify -S -s $SECRETS_DIR/key.sec -m $SECRETS_DIR/message.txt -x $SECRETS_DIR/message.txt.sig | 99 | signify -S -s $SECRETS_DIR/key.sec -m $SECRETS_DIR/message.txt -x $SECRETS_DIR/message.txt.sig |
| 92 | cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed | 100 | cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed |
| 93 | tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed | 101 | tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed |