David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 1 | <!-- |
| 2 | Licensed to the Apache Software Foundation (ASF) under one |
| 3 | or more contributor license agreements. See the NOTICE file |
| 4 | distributed with this work for additional information |
| 5 | regarding copyright ownership. The ASF licenses this file |
| 6 | to you under the Apache License, Version 2.0 (the |
| 7 | "License"); you may not use this file except in compliance |
| 8 | with the License. You may obtain a copy of the License at |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 9 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 10 | http://www.apache.org/licenses/LICENSE-2.0 |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 11 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 12 | Unless required by applicable law or agreed to in writing, |
| 13 | software distributed under the License is distributed on an |
| 14 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | KIND, either express or implied. See the License for the |
| 16 | specific language governing permissions and limitations |
| 17 | under the License. |
| 18 | --> |
| 19 | |
| 20 | # Boot Loader |
| 21 | |
| 22 | ## Summary |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 23 | |
Fabio Utzig | ac83496 | 2017-07-20 13:20:48 -0300 | [diff] [blame] | 24 | mcuboot comprises two packages: |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 25 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 26 | * The bootutil library (boot/bootutil) |
| 27 | * The boot application (each port has its own at boot/<port>) |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 28 | |
| 29 | The bootutil library performs most of the functions of a boot loader. In |
| 30 | particular, the piece that is missing is the final step of actually jumping to |
| 31 | the main image. This last step is instead implemented by the boot application. |
| 32 | Boot loader functionality is separated in this manner to enable unit testing of |
| 33 | the boot loader. A library can be unit tested, but an application can't. |
| 34 | Therefore, functionality is delegated to the bootutil library when possible. |
| 35 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 36 | ## Limitations |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 37 | |
| 38 | The boot loader currently only supports images with the following |
| 39 | characteristics: |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 40 | * Built to run from flash. |
| 41 | * Built to run from a fixed location (i.e., not position-independent). |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 42 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 43 | ## Image Format |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 44 | |
| 45 | The following definitions describe the image format. |
| 46 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 47 | ``` c |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 48 | #define IMAGE_MAGIC 0x96f3b83d |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 49 | |
| 50 | #define IMAGE_HEADER_SIZE 32 |
| 51 | |
| 52 | struct image_version { |
| 53 | uint8_t iv_major; |
| 54 | uint8_t iv_minor; |
| 55 | uint16_t iv_revision; |
| 56 | uint32_t iv_build_num; |
| 57 | }; |
| 58 | |
| 59 | /** Image header. All fields are in little endian byte order. */ |
| 60 | struct image_header { |
| 61 | uint32_t ih_magic; |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 62 | uint32_t ih_load_addr; |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 63 | uint16_t ih_hdr_size; /* Size of image header (bytes). */ |
| 64 | uint16_t _pad2; |
| 65 | uint32_t ih_img_size; /* Does not include header. */ |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 66 | uint32_t ih_flags; /* IMAGE_F_[...]. */ |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 67 | struct image_version ih_ver; |
| 68 | uint32_t _pad3; |
| 69 | }; |
| 70 | |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 71 | /** Image TLV header. All fields in little endian. */ |
| 72 | struct image_tlv_info { |
| 73 | uint16_t it_magic; |
| 74 | uint16_t it_tlv_tot; /* size of TLV area (including tlv_info header) */ |
| 75 | }; |
| 76 | |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 77 | /** Image trailer TLV format. All fields in little endian. */ |
| 78 | struct image_tlv { |
| 79 | uint8_t it_type; /* IMAGE_TLV_[...]. */ |
| 80 | uint8_t _pad; |
Marti Bolivar | 49b2917 | 2017-08-04 14:50:51 -0400 | [diff] [blame] | 81 | uint16_t it_len; /* Data length (not including TLV header). */ |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 82 | }; |
| 83 | |
| 84 | /* |
| 85 | * Image header flags. |
| 86 | */ |
Marti Bolivar | 7c057e9 | 2017-08-04 14:46:39 -0400 | [diff] [blame] | 87 | #define IMAGE_F_PIC 0x00000001 /* Not supported. */ |
Marti Bolivar | 7c057e9 | 2017-08-04 14:46:39 -0400 | [diff] [blame] | 88 | #define IMAGE_F_NON_BOOTABLE 0x00000010 /* Split image app. */ |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 89 | #define IMAGE_F_RAM_LOAD 0x00000020 |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 90 | |
| 91 | /* |
| 92 | * Image trailer TLV types. |
| 93 | */ |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 94 | #define IMAGE_TLV_KEYHASH 0x01 /* hash of the public key */ |
David Brown | 27648b8 | 2017-08-31 10:40:29 -0600 | [diff] [blame] | 95 | #define IMAGE_TLV_SHA256 0x10 /* SHA256 of image hdr and body */ |
Marko Kiiskila | 8dd56f3 | 2017-08-22 21:40:49 -0700 | [diff] [blame] | 96 | #define IMAGE_TLV_RSA2048_PSS 0x20 /* RSA2048 of hash output */ |
David Brown | 27648b8 | 2017-08-31 10:40:29 -0600 | [diff] [blame] | 97 | #define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output */ |
| 98 | #define IMAGE_TLV_ECDSA256 0x22 /* ECDSA of hash output */ |
Fabio Utzig | 3501c01 | 2019-05-13 15:07:25 -0700 | [diff] [blame] | 99 | #define IMAGE_TLV_RSA3072_PSS 0x23 /* RSA3072 of hash output */ |
Fabio Utzig | 195411f | 2019-06-28 07:48:21 -0300 | [diff] [blame] | 100 | #define IMAGE_TLV_ED25519 0x24 /* ED25519 of hash output */ |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 101 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 102 | |
| 103 | Optional type-length-value records (TLVs) containing image metadata are placed |
| 104 | after the end of the image. |
| 105 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 106 | The `ih_hdr_size` field indicates the length of the header, and therefore the |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 107 | offset of the image itself. This field provides for backwards compatibility in |
| 108 | case of changes to the format of the image header. |
| 109 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 110 | ## Flash Map |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 111 | |
Fabio Utzig | ac83496 | 2017-07-20 13:20:48 -0300 | [diff] [blame] | 112 | A device's flash is partitioned according to its _flash map_. At a high |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 113 | level, the flash map maps numeric IDs to _flash areas_. A flash area is a |
| 114 | region of disk with the following properties: |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 115 | 1. An area can be fully erased without affecting any other areas. |
| 116 | 2. A write to one area does not restrict writes to other areas. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 117 | |
Marti Bolivar | 4e64d56 | 2017-08-04 14:53:33 -0400 | [diff] [blame] | 118 | The boot loader uses the following flash area IDs: |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 119 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 120 | ``` c |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 121 | #define FLASH_AREA_BOOTLOADER 0 |
| 122 | #define FLASH_AREA_IMAGE_PRIMARY 1 |
| 123 | #define FLASH_AREA_IMAGE_SECONDARY 2 |
| 124 | #define FLASH_AREA_IMAGE_SCRATCH 3 |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 125 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 126 | |
Marti Bolivar | 4e64d56 | 2017-08-04 14:53:33 -0400 | [diff] [blame] | 127 | The bootloader area contains the bootloader image itself. The other areas are |
| 128 | described in subsequent sections. |
| 129 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 130 | ## Image Slots |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 131 | |
| 132 | A portion of the flash memory is partitioned into two image slots: a primary |
| 133 | slot (0) and a secondary slot (1). The boot loader will only run an image from |
| 134 | the primary slot, so images must be built such that they can run from that |
| 135 | fixed location in flash. If the boot loader needs to run the image resident in |
Marti Bolivar | a91674f | 2017-08-04 14:56:08 -0400 | [diff] [blame] | 136 | the secondary slot, it must copy its contents into the primary slot before doing |
| 137 | so, either by swapping the two images or by overwriting the contents of the |
| 138 | primary slot. The bootloader supports either swap- or overwrite-based image |
| 139 | upgrades, but must be configured at build time to choose one of these two |
| 140 | strategies. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 141 | |
| 142 | In addition to the two image slots, the boot loader requires a scratch area to |
Fabio Utzig | a722f5a | 2017-12-12 14:04:53 -0200 | [diff] [blame] | 143 | allow for reliable image swapping. The scratch area must have a size that is |
| 144 | enough to store at least the largest sector that is going to be swapped. Many |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 145 | devices have small equally sized flash sectors, eg 4K, while others have |
| 146 | variable sized sectors where the largest sectors might be 128K or 256K, so the |
| 147 | scratch must be big enough to store that. The scratch is only ever used when |
| 148 | swapping firmware, which means only when doing an upgrade. Given that, the main |
| 149 | reason for using a larger size for the scratch is that flash wear will be more |
| 150 | evenly distributed, because a single sector would be written twice the number of |
| 151 | times than using two sectors, for example. To evaluate the ideal size of the |
| 152 | scratch for your use case the following parameters are relevant: |
Fabio Utzig | a722f5a | 2017-12-12 14:04:53 -0200 | [diff] [blame] | 153 | |
| 154 | * the ratio of image size / scratch size |
| 155 | * the number of erase cycles supported by the flash hardware |
| 156 | |
| 157 | The image size is used (instead of slot size) because only the slot's sectors |
| 158 | that are actually used for storing the image are copied. The image/scratch ratio |
| 159 | is the number of times the scratch will be erased on every upgrade. The number |
| 160 | of erase cycles divided by the image/scratch ratio will give you the number of |
| 161 | times an upgrade can be performed before the device goes out of spec. |
| 162 | |
| 163 | ``` |
| 164 | num_upgrades = number_of_erase_cycles / (image_size / scratch_size) |
| 165 | ``` |
| 166 | |
| 167 | Let's assume, for example, a device with 10000 erase cycles, an image size of |
| 168 | 150K and a scratch of 4K (usual minimum size of 4K sector devices). This would |
| 169 | result in a total of: |
| 170 | |
| 171 | `10000 / (150 / 4) ~ 267` |
| 172 | |
| 173 | Increasing the scratch to 16K would give us: |
| 174 | |
| 175 | `10000 / (150 / 16) ~ 1067` |
| 176 | |
| 177 | There is no *best* ratio, as the right size is use-case dependent. Factors to |
| 178 | consider include the number of times a device will be upgraded both in the field |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 179 | and during development, as well as any desired safety margin on the |
| 180 | manufacturer's specified number of erase cycles. In general, using a ratio that |
| 181 | allows hundreds to thousands of field upgrades in production is recommended. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 182 | |
Marti Bolivar | a91674f | 2017-08-04 14:56:08 -0400 | [diff] [blame] | 183 | The overwrite upgrade strategy is substantially simpler to implement than the |
| 184 | image swapping strategy, especially since the bootloader must work properly |
| 185 | even when it is reset during the middle of an image swap. For this reason, the |
| 186 | rest of the document describes its behavior when configured to swap images |
| 187 | during an upgrade. |
| 188 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 189 | ## Boot Swap Types |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 190 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 191 | When the device first boots under normal circumstances, there is an up-to-date |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 192 | firmware image in the primary slot, which mcuboot can validate and then |
| 193 | chain-load. In this case, no image swaps are necessary. During device upgrades, |
| 194 | however, new candidate images are present in the secondary slot, which mcuboot |
| 195 | must swap into the primary slot before booting as discussed above. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 196 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 197 | Upgrading an old image with a new one by swapping can be a two-step process. In |
| 198 | this process, mcuboot performs a "test" swap of image data in flash and boots |
| 199 | the new image. The new image can then update the contents of flash at runtime |
| 200 | to mark itself "OK", and mcuboot will then still choose to run it during the |
| 201 | next boot. When this happens, the swap is made "permanent". If this doesn't |
| 202 | happen, mcuboot will perform a "revert" swap during the next boot by swapping |
| 203 | the images back into their original locations, and attempting to boot the old |
| 204 | image. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 205 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 206 | Depending on the use case, the first swap can also be made permanent directly. |
| 207 | In this case, mcuboot will never attempt to revert the images on the next reset. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 208 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 209 | Test swaps are supported to provide a rollback mechanism to prevent devices |
| 210 | from becoming "bricked" by bad firmware. If the device crashes immediately |
| 211 | upon booting a new (bad) image, mcuboot will revert to the old (working) image |
| 212 | at the next device reset, rather than booting the bad image again. This allows |
| 213 | device firmware to make test swaps permanent only after performing a self-test |
| 214 | routine. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 215 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 216 | On startup, mcuboot inspects the contents of flash to decide which of these |
| 217 | "swap types" to perform; this decision determines how it proceeds. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 218 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 219 | The possible swap types, and their meanings, are: |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 220 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 221 | - `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 222 | contents of the primary slot. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 223 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 224 | - `BOOT_SWAP_TYPE_TEST`: Boot the contents of the secondary slot by swapping |
| 225 | images. Unless the swap is made permanent, revert back on the next boot. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 226 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 227 | - `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 228 | firmware. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 229 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 230 | - `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent; |
| 231 | swap back to the old image whose data are now in the secondary slot. If the |
| 232 | old image marks itself "OK" when it boots, the next boot will have swap type |
| 233 | `BOOT_SWAP_TYPE_NONE`. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 234 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 235 | - `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid. |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 236 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 237 | - `BOOT_SWAP_TYPE_PANIC`: Swapping encountered an unrecoverable error. |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 238 | |
| 239 | The "swap type" is a high-level representation of the outcome of the |
| 240 | boot. Subsequent sections describe how mcuboot determines the swap type from |
| 241 | the bit-level contents of flash. |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 242 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 243 | ## Image Trailer |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 244 | |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 245 | For the bootloader to be able to determine the current state and what actions |
Marti Bolivar | 4281803 | 2017-08-04 15:45:01 -0400 | [diff] [blame] | 246 | should be taken during the current boot operation, it uses metadata stored in |
| 247 | the image flash areas. While swapping, some of this metadata is temporarily |
| 248 | copied into and out of the scratch area. |
| 249 | |
| 250 | This metadata is located at the end of the image flash areas, and is called an |
| 251 | image trailer. An image trailer has the following structure: |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 252 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 253 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 254 | 0 1 2 3 |
| 255 | 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 |
| 256 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 257 | ~ ~ |
Fabio Utzig | 2c05f1b | 2018-04-04 10:35:17 -0300 | [diff] [blame] | 258 | ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~ |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 259 | ~ ~ |
| 260 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 261 | | Encryption key 0 (16 octets) [*] | |
| 262 | | | |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 263 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 264 | | Encryption key 1 (16 octets) [*] | |
| 265 | | | |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 266 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 267 | | Swap size (4 octets) | |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 268 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 269 | | Swap type | 0xff padding (7 octets) | |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 270 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 271 | | Copy done | 0xff padding (7 octets) | |
| 272 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 273 | | Image OK | 0xff padding (7 octets) | |
| 274 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 275 | | MAGIC (16 octets) | |
| 276 | | | |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 277 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 278 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 279 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 280 | [*]: Only present if the encryption option is enabled (`MCUBOOT_ENC_IMAGES`). |
| 281 | |
Marti Bolivar | 4281803 | 2017-08-04 15:45:01 -0400 | [diff] [blame] | 282 | The offset immediately following such a record represents the start of the next |
| 283 | flash area. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 284 | |
| 285 | Note: "min-write-size" is a property of the flash hardware. If the hardware |
| 286 | allows individual bytes to be written at arbitrary addresses, then |
| 287 | min-write-size is 1. If the hardware only allows writes at even addresses, |
| 288 | then min-write-size is 2, and so on. |
| 289 | |
Marti Bolivar | 1dcb685 | 2017-08-04 15:59:32 -0400 | [diff] [blame] | 290 | An image trailer contains the following fields: |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 291 | |
Marti Bolivar | 1dcb685 | 2017-08-04 15:59:32 -0400 | [diff] [blame] | 292 | 1. Swap status: A series of records which records the progress of an image |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 293 | swap. To swap entire images, data are swapped between the two image areas |
| 294 | one or more sectors at a time, like this: |
Marti Bolivar | 1dcb685 | 2017-08-04 15:59:32 -0400 | [diff] [blame] | 295 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 296 | - sector data in the primary slot is copied into scratch, then erased |
| 297 | - sector data in the secondary slot is copied into the primary slot, |
| 298 | then erased |
| 299 | - sector data in scratch is copied into the secondary slot |
Marti Bolivar | 1dcb685 | 2017-08-04 15:59:32 -0400 | [diff] [blame] | 300 | |
| 301 | As it swaps images, the bootloader updates the swap status field in a way that |
| 302 | allows it to compute how far this swap operation has progressed for each |
| 303 | sector. The swap status field can thus used to resume a swap operation if the |
| 304 | bootloader is halted while a swap operation is ongoing and later reset. The |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 305 | `BOOT_MAX_IMG_SECTORS` value is the configurable maximum number of sectors |
| 306 | mcuboot supports for each image; its value defaults to 128, but allows for |
| 307 | either decreasing this size, to limit RAM usage, or to increase it in devices |
| 308 | that have massive amounts of Flash or very small sized sectors and thus require |
| 309 | a bigger configuration to allow for the handling of all slot's sectors. |
| 310 | The factor of min-write-sz is due to the behavior of flash hardware. The factor |
| 311 | of 3 is explained below. |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 312 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 313 | 2. Encryption keys: key-encrypting keys (KEKs). These keys are needed for |
| 314 | image encryption and decryption. See the |
| 315 | [encrypted images](encrypted_images.md) document for more information. |
| 316 | |
| 317 | 3. Swap size: When beginning a new swap operation, the total size that needs |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 318 | to be swapped (based on the slot with largest image + tlvs) is written to |
| 319 | this location for easier recovery in case of a reset while performing the |
| 320 | swap. |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 321 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 322 | 4. Swap type: A single byte indicating the type of swap operation in progress. |
| 323 | When mcuboot resumes an interrupted swap, it uses this field to determine |
| 324 | the type of operation to perform. This field contains one of the following |
| 325 | values: |
| 326 | |
| 327 | | Name | Value | |
| 328 | | ------------------------- | ----- | |
| 329 | | `BOOT_SWAP_TYPE_TEST` | 2 | |
| 330 | | `BOOT_SWAP_TYPE_PERM` | 3 | |
| 331 | | `BOOT_SWAP_TYPE_REVERT` | 4 | |
| 332 | |
| 333 | |
| 334 | 5. Copy done: A single byte indicating whether the image in this slot is |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 335 | complete (0x01=done; 0xff=not done). |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 336 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 337 | 6. Image OK: A single byte indicating whether the image in this slot has been |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 338 | confirmed as good by the user (0x01=confirmed; 0xff=not confirmed). |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 339 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 340 | 7. MAGIC: The following 16 bytes, written in host-byte-order: |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 341 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 342 | ``` c |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 343 | const uint32_t boot_img_magic[4] = { |
| 344 | 0xf395c277, |
| 345 | 0x7fefd260, |
| 346 | 0x0f505235, |
| 347 | 0x8079b62c, |
| 348 | }; |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 349 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 350 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 351 | ## IMAGE TRAILERS |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 352 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 353 | At startup, the boot loader determines the boot swap type by inspecting the |
| 354 | image trailers. When using the term "image trailers" what is meant is the |
| 355 | aggregate information provided by both image slot's trailers. |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 356 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 357 | ### New swaps (non-resumes) |
| 358 | |
| 359 | For new swaps, mcuboot must inspect a collection of fields to determine which |
| 360 | swap operation to perform. |
| 361 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 362 | The image trailers records are structured around the limitations imposed by |
| 363 | flash hardware. As a consequence, they do not have a very intuitive design, and |
| 364 | it is difficult to get a sense of the state of the device just by looking at the |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 365 | image trailers. It is better to map all the possible trailer states to the swap |
| 366 | types described above via a set of tables. These tables are reproduced below. |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 367 | |
| 368 | Note: An important caveat about the tables described below is that they must |
| 369 | be evaluated in the order presented here. Lower state numbers must have a |
| 370 | higher priority when testing the image trailers. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 371 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 372 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 373 | State I |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 374 | | primary slot | secondary slot | |
| 375 | -----------------+--------------+----------------| |
| 376 | magic | Any | Good | |
| 377 | image-ok | Any | Unset | |
| 378 | copy-done | Any | Any | |
| 379 | -----------------+--------------+----------------' |
| 380 | result: BOOT_SWAP_TYPE_TEST | |
| 381 | -------------------------------------------------' |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 382 | |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 383 | |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 384 | State II |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 385 | | primary slot | secondary slot | |
| 386 | -----------------+--------------+----------------| |
| 387 | magic | Any | Good | |
| 388 | image-ok | Any | 0x01 | |
| 389 | copy-done | Any | Any | |
| 390 | -----------------+--------------+----------------' |
| 391 | result: BOOT_SWAP_TYPE_PERM | |
| 392 | -------------------------------------------------' |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 393 | |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 394 | |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 395 | State III |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 396 | | primary slot | secondary slot | |
| 397 | -----------------+--------------+----------------| |
| 398 | magic | Good | Unset | |
| 399 | image-ok | 0xff | Any | |
| 400 | copy-done | 0x01 | Any | |
| 401 | -----------------+--------------+----------------' |
| 402 | result: BOOT_SWAP_TYPE_REVERT | |
| 403 | -------------------------------------------------' |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 404 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 405 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 406 | Any of the above three states results in mcuboot attempting to swap images. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 407 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 408 | Otherwise, mcuboot does not attempt to swap images, resulting in one of the |
| 409 | other three swap types, as illustrated by State IV. |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 410 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 411 | ``` |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 412 | State IV |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 413 | | primary slot | secondary slot | |
| 414 | -----------------+--------------+----------------| |
| 415 | magic | Any | Any | |
| 416 | image-ok | Any | Any | |
| 417 | copy-done | Any | Any | |
| 418 | -----------------+--------------+----------------' |
| 419 | result: BOOT_SWAP_TYPE_NONE, | |
| 420 | BOOT_SWAP_TYPE_FAIL, or | |
| 421 | BOOT_SWAP_TYPE_PANIC | |
| 422 | -------------------------------------------------' |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 423 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 424 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 425 | In State IV, when no errors occur, mcuboot will attempt to boot the contents of |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 426 | the primary slot directly, and the result is `BOOT_SWAP_TYPE_NONE`. If the image |
| 427 | in the primary slot is not valid, the result is `BOOT_SWAP_TYPE_FAIL`. If a |
| 428 | fatal error occurs during boot, the result is `BOOT_SWAP_TYPE_PANIC`. If the |
| 429 | result is either `BOOT_SWAP_TYPE_FAIL` or `BOOT_SWAP_TYPE_PANIC`, mcuboot hangs |
| 430 | rather than booting an invalid or compromised image. |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 431 | |
Marti Bolivar | 048d8d8 | 2017-08-04 17:14:24 -0400 | [diff] [blame] | 432 | Note: An important caveat to the above is the result when a swap is requested |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 433 | and the image in the secondary slot fails to validate, due to a hashing or |
| 434 | signing error. This state behaves as State IV with the extra action of |
| 435 | marking the image in the primary slot as "OK", to prevent further attempts |
| 436 | to swap. |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 437 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 438 | ### Resumed swaps |
| 439 | |
| 440 | If mcuboot determines that it is resuming an interrupted swap (i.e., a reset |
| 441 | occurred mid-swap), it fully determines the operation to resume by reading the |
| 442 | `swap type` field from the active trailer. The set of tables in the previous |
| 443 | section are not necessary in the resume case. |
| 444 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 445 | ## High-Level Operation |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 446 | |
| 447 | With the terms defined, we can now explore the boot loader's operation. First, |
| 448 | a high-level overview of the boot process is presented. Then, the following |
| 449 | sections describe each step of the process in more detail. |
| 450 | |
| 451 | Procedure: |
| 452 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 453 | 1. Inspect swap status region; is an interrupted swap being resumed? |
| 454 | Yes: Complete the partial swap operation; skip to step 3. |
| 455 | No: Proceed to step 2. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 456 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 457 | 2. Inspect image trailers; is a swap requested? |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 458 | Yes. |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 459 | 1. Is the requested image valid (integrity and security check)? |
| 460 | Yes. |
| 461 | a. Perform swap operation. |
| 462 | b. Persist completion of swap procedure to image trailers. |
| 463 | c. Proceed to step 3. |
| 464 | No. |
| 465 | a. Erase invalid image. |
| 466 | b. Persist failure of swap procedure to image trailers. |
| 467 | c. Proceed to step 3. |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 468 | No: Proceed to step 3. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 469 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 470 | 3. Boot into image in primary slot. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 471 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 472 | ## Image Swapping |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 473 | |
| 474 | The boot loader swaps the contents of the two image slots for two reasons: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 475 | * User has issued a "set pending" operation; the image in the secondary slot |
| 476 | should be run once (state II) or repeatedly (state III), depending on |
| 477 | whether a permanent swap was specified. |
| 478 | * Test image rebooted without being confirmed; the boot loader should |
| 479 | revert to the original image currently in the secondary slot (state IV). |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 480 | |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 481 | If the image trailers indicates that the image in the secondary slot should be |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 482 | run, the boot loader needs to copy it to the primary slot. The image currently |
| 483 | in the primary slot also needs to be retained in flash so that it can be used |
| 484 | later. Furthermore, both images need to be recoverable if the boot loader |
| 485 | resets in the middle of the swap operation. The two images are swapped |
| 486 | according to the following procedure: |
| 487 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 488 | <!-- Markdown doesn't do nested numbered lists. It will do nested |
| 489 | bulletted lists, so maybe that is better. --> |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 490 | 1. Determine how many flash sectors each image slot consists of. This |
| 491 | number must be the same for both slots. |
| 492 | 2. Iterate the list of sector indices in descending order (i.e., starting |
| 493 | with the greatest index); current element = "index". |
| 494 | b. Erase scratch area. |
| 495 | c. Copy secondary_slot[index] to scratch area. |
| 496 | - If these are the last sectors (i.e., first swap being perfomed), |
| 497 | copy the full sector *except* the image trailer. |
| 498 | - Else, copy entire sector contents. |
| 499 | d. Write updated swap status (i). |
| 500 | e. Erase secondary_slot[index] |
| 501 | f. Copy primary_slot[index] to secondary_slot[index] |
| 502 | - If these are the last sectors (i.e., first swap being perfomed), |
| 503 | copy the full sector *except* the image trailer. |
| 504 | - Else, copy entire sector contents. |
| 505 | g. Write updated swap status (ii). |
| 506 | h. Erase primary_slot[index]. |
| 507 | i. Copy scratch area to primary_slot[index]. |
| 508 | - If these are the last sectors (i.e., first swap being perfomed), |
| 509 | copy the full sector *except* the image trailer. |
| 510 | - Else, copy entire sector contents. |
| 511 | j. Write updated swap status (iii). |
| 512 | 3. Persist completion of swap procedure to the primary slot image trailer. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 513 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 514 | The additional caveats in step 2f are necessary so that the secondary slot image |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 515 | trailer can be written by the user at a later time. With the image trailer |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 516 | unwritten, the user can test the image in the secondary slot |
| 517 | (i.e., transition to state II). |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 518 | |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 519 | Note1: If the sector being copied is the last sector, then swap status is |
| 520 | temporarily maintained on scratch for the duration of this operation, always |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 521 | using the primary slot's area otherwise. |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 522 | |
| 523 | Note2: The bootloader tries to copy only used sectors (based on largest image |
| 524 | installed on any of the slots), minimizing the amount of sectors copied and |
| 525 | reducing the amount of time required for a swap operation. |
| 526 | |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 527 | The particulars of step 3 vary depending on whether an image is being tested, |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 528 | permanently used, reverted or a validation failure of the secondary slot |
| 529 | happened when a swap was requested: |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 530 | |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 531 | * test: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 532 | o Write primary_slot.copy_done = 1 |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 533 | (swap caused the following values to be written: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 534 | primary_slot.magic = BOOT_MAGIC |
| 535 | primary_slot.image_ok = Unset) |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 536 | |
| 537 | * permanent: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 538 | o Write primary_slot.copy_done = 1 |
Christopher Collins | fd7eb5c | 2016-12-21 13:46:08 -0800 | [diff] [blame] | 539 | (swap caused the following values to be written: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 540 | primary_slot.magic = BOOT_MAGIC |
| 541 | primary_slot.image_ok = 0x01) |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 542 | |
| 543 | * revert: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 544 | o Write primary_slot.copy_done = 1 |
| 545 | o Write primary_slot.image_ok = 1 |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 546 | (swap caused the following values to be written: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 547 | primary_slot.magic = BOOT_MAGIC) |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 548 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 549 | * failure to validate the secondary slot: |
| 550 | o Write primary_slot.image_ok = 1 |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 551 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 552 | After completing the operations as described above the image in the primary slot |
| 553 | should be booted. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 554 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 555 | ## Swap Status |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 556 | |
| 557 | The swap status region allows the boot loader to recover in case it restarts in |
| 558 | the middle of an image swap operation. The swap status region consists of a |
| 559 | series of single-byte records. These records are written independently, and |
| 560 | therefore must be padded according to the minimum write size imposed by the |
| 561 | flash hardware. In the below figure, a min-write-size of 1 is assumed for |
| 562 | simplicity. The structure of the swap status region is illustrated below. In |
| 563 | this figure, a min-write-size of 1 is assumed for simplicity. |
| 564 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 565 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 566 | 0 1 2 3 |
| 567 | 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 |
| 568 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 569 | |sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 | |
| 570 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 571 | |sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 | |
| 572 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 573 | |sec125,state 2 | | |
| 574 | +-+-+-+-+-+-+-+-+ + |
| 575 | ~ ~ |
| 576 | ~ [Records for indices 124 through 1 ~ |
| 577 | ~ ~ |
| 578 | ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
| 579 | ~ |sec000,state 0 |sec000,state 1 |sec000,state 2 | |
| 580 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 581 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 582 | |
| 583 | The above is probably not helpful at all; here is a description in English. |
| 584 | |
| 585 | Each image slot is partitioned into a sequence of flash sectors. If we were to |
| 586 | enumerate the sectors in a single slot, starting at 0, we would have a list of |
| 587 | sector indices. Since there are two image slots, each sector index would |
| 588 | correspond to a pair of sectors. For example, sector index 0 corresponds to |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 589 | the first sector in the primary slot and the first sector in the secondary slot. |
| 590 | Finally, reverse the list of indices such that the list starts with index |
| 591 | `BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is a |
| 592 | representation of this reversed list. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 593 | |
| 594 | During a swap operation, each sector index transitions through four separate |
| 595 | states: |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 596 | ``` |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 597 | 0. primary slot: image 0, secondary slot: image 1, scratch: N/A |
| 598 | 1. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1) |
| 599 | 2. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0) |
| 600 | 3. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0) |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 601 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 602 | |
| 603 | Each time a sector index transitions to a new state, the boot loader writes a |
| 604 | record to the swap status region. Logically, the boot loader only needs one |
| 605 | record per sector index to keep track of the current swap state. However, due |
| 606 | to limitations imposed by flash hardware, a record cannot be overwritten when |
| 607 | an index's state changes. To solve this problem, the boot loader uses three |
| 608 | records per sector index rather than just one. |
| 609 | |
| 610 | Each sector-state pair is represented as a set of three records. The record |
| 611 | values map to the above four states as follows |
| 612 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 613 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 614 | | rec0 | rec1 | rec2 |
| 615 | --------+------+------+------ |
| 616 | state 0 | 0xff | 0xff | 0xff |
| 617 | state 1 | 0x01 | 0xff | 0xff |
| 618 | state 2 | 0x01 | 0x02 | 0xff |
| 619 | state 3 | 0x01 | 0x02 | 0x03 |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 620 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 621 | |
Fabio Utzig | 2c05f1b | 2018-04-04 10:35:17 -0300 | [diff] [blame] | 622 | The swap status region can accommodate `BOOT_MAX_IMG_SECTORS` sector indices. |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 623 | Hence, the size of the region, in bytes, is |
| 624 | `BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index |
| 625 | count is that it is great enough to account for a maximum-sized image |
| 626 | (i.e., at least as great as the total sector count in an image slot). If a |
| 627 | device's image slots have been configured with `BOOT_MAX_IMG_SECTORS: 128` and |
| 628 | use less than 128 sectors, the first record that gets written will be somewhere |
| 629 | in the middle of the region. For example, if a slot uses 64 sectors, the first |
| 630 | sector index that gets swapped is 63, which corresponds to the exact halfway |
| 631 | point within the region. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 632 | |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 633 | Note: since the scratch area only ever needs to record swapping of the last |
| 634 | sector, it uses at most min-write-size * 3 bytes for its own status area. |
| 635 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 636 | ## Reset Recovery |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 637 | |
| 638 | If the boot loader resets in the middle of a swap operation, the two images may |
| 639 | be discontiguous in flash. Bootutil recovers from this condition by using the |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 640 | image trailers to determine how the image parts are distributed in flash. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 641 | |
| 642 | The first step is determine where the relevant swap status region is located. |
| 643 | Because this region is embedded within the image slots, its location in flash |
Fabio Utzig | 86fe4b2 | 2017-07-28 18:56:29 -0300 | [diff] [blame] | 644 | changes during a swap operation. The below set of tables map image trailers |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 645 | contents to swap status location. In these tables, the "source" field |
| 646 | indicates where the swap status region is located. |
| 647 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 648 | ``` |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 649 | | primary slot | scratch | |
| 650 | ----------+--------------+--------------| |
| 651 | magic | Good | Any | |
| 652 | copy-done | 0x01 | N/A | |
| 653 | ----------+--------------+--------------' |
| 654 | source: none | |
| 655 | ----------------------------------------' |
Marti Bolivar | 49b2917 | 2017-08-04 14:50:51 -0400 | [diff] [blame] | 656 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 657 | | primary slot | scratch | |
| 658 | ----------+--------------+--------------| |
| 659 | magic | Good | Any | |
| 660 | copy-done | 0xff | N/A | |
| 661 | ----------+--------------+--------------' |
| 662 | source: primary slot | |
| 663 | ----------------------------------------' |
Marti Bolivar | 49b2917 | 2017-08-04 14:50:51 -0400 | [diff] [blame] | 664 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 665 | | primary slot | scratch | |
| 666 | ----------+--------------+--------------| |
| 667 | magic | Any | Good | |
| 668 | copy-done | Any | N/A | |
| 669 | ----------+--------------+--------------' |
| 670 | source: scratch | |
| 671 | ----------------------------------------' |
Marti Bolivar | 49b2917 | 2017-08-04 14:50:51 -0400 | [diff] [blame] | 672 | |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 673 | | primary slot | scratch | |
| 674 | ----------+--------------+--------------| |
| 675 | magic | Unset | Any | |
| 676 | copy-done | 0xff | N/A | |
| 677 | ----------+--------------+--------------| |
| 678 | source: primary slot | |
| 679 | ----------------------------------------+------------------------------+ |
| 680 | This represents one of two cases: | |
| 681 | o No swaps ever (no status to read, so no harm in checking). | |
| 682 | o Mid-revert; status in the primary slot. | |
| 683 | For this reason we assume the primary slot as source, to trigger a | |
| 684 | check of the status area and find out if there was swapping under way. | |
| 685 | -----------------------------------------------------------------------' |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 686 | ``` |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 687 | |
Christopher Collins | a1c1204 | 2019-05-23 14:00:28 -0700 | [diff] [blame] | 688 | If the swap status region indicates that the images are not contiguous, mcuboot |
| 689 | determines the type of swap operation that was interrupted by reading the `swap |
| 690 | type` field in the active image trailer, and then resumes the operation. In |
| 691 | other words, it applies the procedure defined in the previous section, moving |
| 692 | image 1 into the primary slot and image 0 into the secondary slot. If the boot |
| 693 | status indicates that an image part is present in the scratch area, this part |
| 694 | is copied into the correct location by starting at step e or step h in the |
| 695 | area-swap procedure, depending on whether the part belongs to image 0 or image |
| 696 | 1. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 697 | |
| 698 | After the swap operation has been completed, the boot loader proceeds as though |
| 699 | it had just been started. |
| 700 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 701 | ## Integrity Check |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 702 | |
| 703 | An image is checked for integrity immediately before it gets copied into the |
Fabio Utzig | 5bd4e58 | 2017-07-20 08:55:38 -0300 | [diff] [blame] | 704 | primary slot. If the boot loader doesn't perform an image swap, then it can |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 705 | perform an optional integrity check of the image in the primary slot if |
| 706 | `MCUBOOT_VALIDATE_PRIMARY_SLOT` is set, otherwise it doesn't perform an |
| 707 | integrity check. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 708 | |
| 709 | During the integrity check, the boot loader verifies the following aspects of |
| 710 | an image: |
David Vincze | 2d736ad | 2019-02-18 11:50:22 +0100 | [diff] [blame] | 711 | * 32-bit magic number must be correct (0x96f3b83d). |
| 712 | * Image must contain an `image_tlv_info` struct, identified by its magic |
| 713 | (0x6907) exactly following the firmware (hdr_size + img_size). |
| 714 | * Image must contain a SHA256 TLV. |
| 715 | * Calculated SHA256 must match SHA256 TLV contents. |
| 716 | * Image *may* contain a signature TLV. If it does, it must also have a |
| 717 | KEYHASH TLV with the hash of the key that was used to sign. The list of |
| 718 | keys will then be iterated over looking for the matching key, which then |
| 719 | will then be used to verify the image contents. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 720 | |
David Brown | 17e20d1 | 2017-09-12 11:53:20 -0600 | [diff] [blame] | 721 | ## Security |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 722 | |
| 723 | As indicated above, the final step of the integrity check is signature |
| 724 | verification. The boot loader can have one or more public keys embedded in it |
| 725 | at build time. During signature verification, the boot loader verifies that an |
Fabio Utzig | ea422c2 | 2017-09-11 11:02:47 -0300 | [diff] [blame] | 726 | image was signed with a private key that corresponds to the embedded keyhash |
| 727 | TLV. |
Christopher Collins | 92ea77f | 2016-12-12 15:59:26 -0800 | [diff] [blame] | 728 | |
| 729 | For information on embedding public keys in the boot loader, as well as |
Fabio Utzig | 4dce6aa | 2018-02-12 15:31:32 -0200 | [diff] [blame] | 730 | producing signed images, see: [signed_images](signed_images.md). |
Fabio Utzig | cdfa11a | 2018-10-01 09:45:54 -0300 | [diff] [blame] | 731 | |
| 732 | If you want to enable and use encrypted images, see: |
| 733 | [encrypted_images](encrypted_images.md). |