blob: f469d45374802e44d666afa4f74492d606351520 [file] [log] [blame] [view]
David Brown17e20d12017-09-12 11:53:20 -06001<!--
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 Collins92ea77f2016-12-12 15:59:26 -08009
David Brown17e20d12017-09-12 11:53:20 -060010 http://www.apache.org/licenses/LICENSE-2.0
Christopher Collins92ea77f2016-12-12 15:59:26 -080011
David Brown17e20d12017-09-12 11:53:20 -060012 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 Collins92ea77f2016-12-12 15:59:26 -080023
Fabio Utzigac834962017-07-20 13:20:48 -030024mcuboot comprises two packages:
Christopher Collins92ea77f2016-12-12 15:59:26 -080025
David Brown17e20d12017-09-12 11:53:20 -060026* The bootutil library (boot/bootutil)
27* The boot application (each port has its own at boot/<port>)
Christopher Collins92ea77f2016-12-12 15:59:26 -080028
29The bootutil library performs most of the functions of a boot loader. In
30particular, the piece that is missing is the final step of actually jumping to
31the main image. This last step is instead implemented by the boot application.
32Boot loader functionality is separated in this manner to enable unit testing of
33the boot loader. A library can be unit tested, but an application can't.
34Therefore, functionality is delegated to the bootutil library when possible.
35
David Brown17e20d12017-09-12 11:53:20 -060036## Limitations
Christopher Collins92ea77f2016-12-12 15:59:26 -080037
38The boot loader currently only supports images with the following
39characteristics:
David Brown17e20d12017-09-12 11:53:20 -060040* Built to run from flash.
41* Built to run from a fixed location (i.e., not position-independent).
Christopher Collins92ea77f2016-12-12 15:59:26 -080042
David Brown17e20d12017-09-12 11:53:20 -060043## Image Format
Christopher Collins92ea77f2016-12-12 15:59:26 -080044
45The following definitions describe the image format.
46
David Brown17e20d12017-09-12 11:53:20 -060047``` c
Fabio Utzigea422c22017-09-11 11:02:47 -030048#define IMAGE_MAGIC 0x96f3b83d
Christopher Collins92ea77f2016-12-12 15:59:26 -080049
50#define IMAGE_HEADER_SIZE 32
51
52struct 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. */
60struct image_header {
61 uint32_t ih_magic;
Fabio Utzigea422c22017-09-11 11:02:47 -030062 uint32_t ih_load_addr;
Christopher Collins92ea77f2016-12-12 15:59:26 -080063 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 Utzigea422c22017-09-11 11:02:47 -030066 uint32_t ih_flags; /* IMAGE_F_[...]. */
Christopher Collins92ea77f2016-12-12 15:59:26 -080067 struct image_version ih_ver;
68 uint32_t _pad3;
69};
70
Fabio Utzigea422c22017-09-11 11:02:47 -030071/** Image TLV header. All fields in little endian. */
72struct 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 Collins92ea77f2016-12-12 15:59:26 -080077/** Image trailer TLV format. All fields in little endian. */
78struct image_tlv {
79 uint8_t it_type; /* IMAGE_TLV_[...]. */
80 uint8_t _pad;
Marti Bolivar49b29172017-08-04 14:50:51 -040081 uint16_t it_len; /* Data length (not including TLV header). */
Christopher Collins92ea77f2016-12-12 15:59:26 -080082};
83
84/*
85 * Image header flags.
86 */
Marti Bolivar7c057e92017-08-04 14:46:39 -040087#define IMAGE_F_PIC 0x00000001 /* Not supported. */
Marti Bolivar7c057e92017-08-04 14:46:39 -040088#define IMAGE_F_NON_BOOTABLE 0x00000010 /* Split image app. */
Fabio Utzigea422c22017-09-11 11:02:47 -030089#define IMAGE_F_RAM_LOAD 0x00000020
Christopher Collins92ea77f2016-12-12 15:59:26 -080090
91/*
92 * Image trailer TLV types.
93 */
Fabio Utzigea422c22017-09-11 11:02:47 -030094#define IMAGE_TLV_KEYHASH 0x01 /* hash of the public key */
David Brown27648b82017-08-31 10:40:29 -060095#define IMAGE_TLV_SHA256 0x10 /* SHA256 of image hdr and body */
Marko Kiiskila8dd56f32017-08-22 21:40:49 -070096#define IMAGE_TLV_RSA2048_PSS 0x20 /* RSA2048 of hash output */
David Brown27648b82017-08-31 10:40:29 -060097#define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output */
98#define IMAGE_TLV_ECDSA256 0x22 /* ECDSA of hash output */
Fabio Utzig3501c012019-05-13 15:07:25 -070099#define IMAGE_TLV_RSA3072_PSS 0x23 /* RSA3072 of hash output */
Fabio Utzig195411f2019-06-28 07:48:21 -0300100#define IMAGE_TLV_ED25519 0x24 /* ED25519 of hash output */
David Brown17e20d12017-09-12 11:53:20 -0600101```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800102
103Optional type-length-value records (TLVs) containing image metadata are placed
104after the end of the image.
105
David Brown17e20d12017-09-12 11:53:20 -0600106The `ih_hdr_size` field indicates the length of the header, and therefore the
Christopher Collins92ea77f2016-12-12 15:59:26 -0800107offset of the image itself. This field provides for backwards compatibility in
108case of changes to the format of the image header.
109
David Brown17e20d12017-09-12 11:53:20 -0600110## Flash Map
Christopher Collins92ea77f2016-12-12 15:59:26 -0800111
Fabio Utzigac834962017-07-20 13:20:48 -0300112A device's flash is partitioned according to its _flash map_. At a high
Christopher Collins92ea77f2016-12-12 15:59:26 -0800113level, the flash map maps numeric IDs to _flash areas_. A flash area is a
114region of disk with the following properties:
David Brown17e20d12017-09-12 11:53:20 -06001151. An area can be fully erased without affecting any other areas.
1162. A write to one area does not restrict writes to other areas.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800117
Marti Bolivar4e64d562017-08-04 14:53:33 -0400118The boot loader uses the following flash area IDs:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800119
David Brown17e20d12017-09-12 11:53:20 -0600120``` c
David Vincze2d736ad2019-02-18 11:50:22 +0100121#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 Brown17e20d12017-09-12 11:53:20 -0600125```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800126
Marti Bolivar4e64d562017-08-04 14:53:33 -0400127The bootloader area contains the bootloader image itself. The other areas are
128described in subsequent sections.
129
David Brown17e20d12017-09-12 11:53:20 -0600130## Image Slots
Christopher Collins92ea77f2016-12-12 15:59:26 -0800131
132A portion of the flash memory is partitioned into two image slots: a primary
133slot (0) and a secondary slot (1). The boot loader will only run an image from
134the primary slot, so images must be built such that they can run from that
135fixed location in flash. If the boot loader needs to run the image resident in
Marti Bolivara91674f2017-08-04 14:56:08 -0400136the secondary slot, it must copy its contents into the primary slot before doing
137so, either by swapping the two images or by overwriting the contents of the
138primary slot. The bootloader supports either swap- or overwrite-based image
139upgrades, but must be configured at build time to choose one of these two
140strategies.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800141
142In addition to the two image slots, the boot loader requires a scratch area to
Fabio Utziga722f5a2017-12-12 14:04:53 -0200143allow for reliable image swapping. The scratch area must have a size that is
144enough to store at least the largest sector that is going to be swapped. Many
David Vincze2d736ad2019-02-18 11:50:22 +0100145devices have small equally sized flash sectors, eg 4K, while others have
146variable sized sectors where the largest sectors might be 128K or 256K, so the
147scratch must be big enough to store that. The scratch is only ever used when
148swapping firmware, which means only when doing an upgrade. Given that, the main
149reason for using a larger size for the scratch is that flash wear will be more
150evenly distributed, because a single sector would be written twice the number of
151times than using two sectors, for example. To evaluate the ideal size of the
152scratch for your use case the following parameters are relevant:
Fabio Utziga722f5a2017-12-12 14:04:53 -0200153
154* the ratio of image size / scratch size
155* the number of erase cycles supported by the flash hardware
156
157The image size is used (instead of slot size) because only the slot's sectors
158that are actually used for storing the image are copied. The image/scratch ratio
159is the number of times the scratch will be erased on every upgrade. The number
160of erase cycles divided by the image/scratch ratio will give you the number of
161times an upgrade can be performed before the device goes out of spec.
162
163```
164num_upgrades = number_of_erase_cycles / (image_size / scratch_size)
165```
166
167Let's assume, for example, a device with 10000 erase cycles, an image size of
168150K and a scratch of 4K (usual minimum size of 4K sector devices). This would
169result in a total of:
170
171`10000 / (150 / 4) ~ 267`
172
173Increasing the scratch to 16K would give us:
174
175`10000 / (150 / 16) ~ 1067`
176
177There is no *best* ratio, as the right size is use-case dependent. Factors to
178consider include the number of times a device will be upgraded both in the field
David Vincze2d736ad2019-02-18 11:50:22 +0100179and during development, as well as any desired safety margin on the
180manufacturer's specified number of erase cycles. In general, using a ratio that
181allows hundreds to thousands of field upgrades in production is recommended.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800182
Marti Bolivara91674f2017-08-04 14:56:08 -0400183The overwrite upgrade strategy is substantially simpler to implement than the
184image swapping strategy, especially since the bootloader must work properly
185even when it is reset during the middle of an image swap. For this reason, the
186rest of the document describes its behavior when configured to swap images
187during an upgrade.
188
David Brown17e20d12017-09-12 11:53:20 -0600189## Boot Swap Types
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800190
Marti Bolivar048d8d82017-08-04 17:14:24 -0400191When the device first boots under normal circumstances, there is an up-to-date
David Vincze2d736ad2019-02-18 11:50:22 +0100192firmware image in the primary slot, which mcuboot can validate and then
193chain-load. In this case, no image swaps are necessary. During device upgrades,
194however, new candidate images are present in the secondary slot, which mcuboot
195must swap into the primary slot before booting as discussed above.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800196
Marti Bolivar048d8d82017-08-04 17:14:24 -0400197Upgrading an old image with a new one by swapping can be a two-step process. In
198this process, mcuboot performs a "test" swap of image data in flash and boots
199the new image. The new image can then update the contents of flash at runtime
200to mark itself "OK", and mcuboot will then still choose to run it during the
201next boot. When this happens, the swap is made "permanent". If this doesn't
202happen, mcuboot will perform a "revert" swap during the next boot by swapping
203the images back into their original locations, and attempting to boot the old
204image.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800205
Marti Bolivar048d8d82017-08-04 17:14:24 -0400206Depending on the use case, the first swap can also be made permanent directly.
207In this case, mcuboot will never attempt to revert the images on the next reset.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800208
Marti Bolivar048d8d82017-08-04 17:14:24 -0400209Test swaps are supported to provide a rollback mechanism to prevent devices
210from becoming "bricked" by bad firmware. If the device crashes immediately
211upon booting a new (bad) image, mcuboot will revert to the old (working) image
212at the next device reset, rather than booting the bad image again. This allows
213device firmware to make test swaps permanent only after performing a self-test
214routine.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800215
Marti Bolivar048d8d82017-08-04 17:14:24 -0400216On startup, mcuboot inspects the contents of flash to decide which of these
217"swap types" to perform; this decision determines how it proceeds.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800218
Marti Bolivar048d8d82017-08-04 17:14:24 -0400219The possible swap types, and their meanings, are:
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800220
David Brown17e20d12017-09-12 11:53:20 -0600221- `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the
David Vincze2d736ad2019-02-18 11:50:22 +0100222 contents of the primary slot.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800223
David Vincze2d736ad2019-02-18 11:50:22 +0100224- `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 Collinsfd7eb5c2016-12-21 13:46:08 -0800226
David Brown17e20d12017-09-12 11:53:20 -0600227- `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image
Marti Bolivar048d8d82017-08-04 17:14:24 -0400228 firmware.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800229
David Vincze2d736ad2019-02-18 11:50:22 +0100230- `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 Collinsfd7eb5c2016-12-21 13:46:08 -0800234
David Brown17e20d12017-09-12 11:53:20 -0600235- `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid.
Marti Bolivar048d8d82017-08-04 17:14:24 -0400236
David Brown17e20d12017-09-12 11:53:20 -0600237- `BOOT_SWAP_TYPE_PANIC`: Swapping encountered an unrecoverable error.
Marti Bolivar048d8d82017-08-04 17:14:24 -0400238
239The "swap type" is a high-level representation of the outcome of the
240boot. Subsequent sections describe how mcuboot determines the swap type from
241the bit-level contents of flash.
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800242
David Brown17e20d12017-09-12 11:53:20 -0600243## Image Trailer
Christopher Collins92ea77f2016-12-12 15:59:26 -0800244
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300245For the bootloader to be able to determine the current state and what actions
Marti Bolivar42818032017-08-04 15:45:01 -0400246should be taken during the current boot operation, it uses metadata stored in
247the image flash areas. While swapping, some of this metadata is temporarily
248copied into and out of the scratch area.
249
250This metadata is located at the end of the image flash areas, and is called an
251image trailer. An image trailer has the following structure:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800252
David Brown17e20d12017-09-12 11:53:20 -0600253```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800254 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 Collins92ea77f2016-12-12 15:59:26 -0800257 ~ ~
Fabio Utzig2c05f1b2018-04-04 10:35:17 -0300258 ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~
Christopher Collins92ea77f2016-12-12 15:59:26 -0800259 ~ ~
260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collinsa1c12042019-05-23 14:00:28 -0700261 | Encryption key 0 (16 octets) [*] |
262 | |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collinsa1c12042019-05-23 14:00:28 -0700264 | Encryption key 1 (16 octets) [*] |
265 | |
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300266 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collinsa1c12042019-05-23 14:00:28 -0700267 | Swap size (4 octets) |
Fabio Utzigea422c22017-09-11 11:02:47 -0300268 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collinsa1c12042019-05-23 14:00:28 -0700269 | Swap type | 0xff padding (7 octets) |
Fabio Utzigea422c22017-09-11 11:02:47 -0300270 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collinsa1c12042019-05-23 14:00:28 -0700271 | Copy done | 0xff padding (7 octets) |
272 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
273 | Image OK | 0xff padding (7 octets) |
274 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
275 | MAGIC (16 octets) |
276 | |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800277 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
David Brown17e20d12017-09-12 11:53:20 -0600278```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800279
Christopher Collinsa1c12042019-05-23 14:00:28 -0700280[*]: Only present if the encryption option is enabled (`MCUBOOT_ENC_IMAGES`).
281
Marti Bolivar42818032017-08-04 15:45:01 -0400282The offset immediately following such a record represents the start of the next
283flash area.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800284
285Note: "min-write-size" is a property of the flash hardware. If the hardware
286allows individual bytes to be written at arbitrary addresses, then
287min-write-size is 1. If the hardware only allows writes at even addresses,
288then min-write-size is 2, and so on.
289
Marti Bolivar1dcb6852017-08-04 15:59:32 -0400290An image trailer contains the following fields:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800291
Marti Bolivar1dcb6852017-08-04 15:59:32 -04002921. Swap status: A series of records which records the progress of an image
David Vincze2d736ad2019-02-18 11:50:22 +0100293 swap. To swap entire images, data are swapped between the two image areas
294 one or more sectors at a time, like this:
Marti Bolivar1dcb6852017-08-04 15:59:32 -0400295
David Vincze2d736ad2019-02-18 11:50:22 +0100296 - 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 Bolivar1dcb6852017-08-04 15:59:32 -0400300
301As it swaps images, the bootloader updates the swap status field in a way that
302allows it to compute how far this swap operation has progressed for each
303sector. The swap status field can thus used to resume a swap operation if the
304bootloader is halted while a swap operation is ongoing and later reset. The
David Vincze2d736ad2019-02-18 11:50:22 +0100305`BOOT_MAX_IMG_SECTORS` value is the configurable maximum number of sectors
306mcuboot supports for each image; its value defaults to 128, but allows for
307either decreasing this size, to limit RAM usage, or to increase it in devices
308that have massive amounts of Flash or very small sized sectors and thus require
309a bigger configuration to allow for the handling of all slot's sectors.
310The factor of min-write-sz is due to the behavior of flash hardware. The factor
311of 3 is explained below.
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300312
Christopher Collinsa1c12042019-05-23 14:00:28 -07003132. 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
3173. Swap size: When beginning a new swap operation, the total size that needs
David Vincze2d736ad2019-02-18 11:50:22 +0100318 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 Utzigea422c22017-09-11 11:02:47 -0300321
Christopher Collinsa1c12042019-05-23 14:00:28 -07003224. 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
3345. Copy done: A single byte indicating whether the image in this slot is
David Brown17e20d12017-09-12 11:53:20 -0600335 complete (0x01=done; 0xff=not done).
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300336
Christopher Collinsa1c12042019-05-23 14:00:28 -07003376. Image OK: A single byte indicating whether the image in this slot has been
David Brown17e20d12017-09-12 11:53:20 -0600338 confirmed as good by the user (0x01=confirmed; 0xff=not confirmed).
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300339
Christopher Collinsa1c12042019-05-23 14:00:28 -07003407. MAGIC: The following 16 bytes, written in host-byte-order:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800341
David Brown17e20d12017-09-12 11:53:20 -0600342``` c
Christopher Collins92ea77f2016-12-12 15:59:26 -0800343 const uint32_t boot_img_magic[4] = {
344 0xf395c277,
345 0x7fefd260,
346 0x0f505235,
347 0x8079b62c,
348 };
David Brown17e20d12017-09-12 11:53:20 -0600349```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800350
David Brown17e20d12017-09-12 11:53:20 -0600351## IMAGE TRAILERS
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300352
Marti Bolivar048d8d82017-08-04 17:14:24 -0400353At startup, the boot loader determines the boot swap type by inspecting the
354image trailers. When using the term "image trailers" what is meant is the
355aggregate information provided by both image slot's trailers.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300356
Christopher Collinsa1c12042019-05-23 14:00:28 -0700357### New swaps (non-resumes)
358
359For new swaps, mcuboot must inspect a collection of fields to determine which
360swap operation to perform.
361
David Vincze2d736ad2019-02-18 11:50:22 +0100362The image trailers records are structured around the limitations imposed by
363flash hardware. As a consequence, they do not have a very intuitive design, and
364it is difficult to get a sense of the state of the device just by looking at the
Marti Bolivar048d8d82017-08-04 17:14:24 -0400365image trailers. It is better to map all the possible trailer states to the swap
366types described above via a set of tables. These tables are reproduced below.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300367
368Note: An important caveat about the tables described below is that they must
369be evaluated in the order presented here. Lower state numbers must have a
370higher priority when testing the image trailers.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800371
David Brown17e20d12017-09-12 11:53:20 -0600372```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800373 State I
David Vincze2d736ad2019-02-18 11:50:22 +0100374 | 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 Utzig5bd4e582017-07-20 08:55:38 -0300382
Christopher Collins92ea77f2016-12-12 15:59:26 -0800383
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300384 State II
David Vincze2d736ad2019-02-18 11:50:22 +0100385 | 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 Utzig5bd4e582017-07-20 08:55:38 -0300393
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800394
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300395 State III
David Vincze2d736ad2019-02-18 11:50:22 +0100396 | 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 Brown17e20d12017-09-12 11:53:20 -0600404```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800405
Marti Bolivar048d8d82017-08-04 17:14:24 -0400406Any of the above three states results in mcuboot attempting to swap images.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800407
Marti Bolivar048d8d82017-08-04 17:14:24 -0400408Otherwise, mcuboot does not attempt to swap images, resulting in one of the
409other three swap types, as illustrated by State IV.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300410
David Brown17e20d12017-09-12 11:53:20 -0600411```
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300412 State IV
David Vincze2d736ad2019-02-18 11:50:22 +0100413 | 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 Brown17e20d12017-09-12 11:53:20 -0600423```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800424
Marti Bolivar048d8d82017-08-04 17:14:24 -0400425In State IV, when no errors occur, mcuboot will attempt to boot the contents of
David Vincze2d736ad2019-02-18 11:50:22 +0100426the primary slot directly, and the result is `BOOT_SWAP_TYPE_NONE`. If the image
427in the primary slot is not valid, the result is `BOOT_SWAP_TYPE_FAIL`. If a
428fatal error occurs during boot, the result is `BOOT_SWAP_TYPE_PANIC`. If the
429result is either `BOOT_SWAP_TYPE_FAIL` or `BOOT_SWAP_TYPE_PANIC`, mcuboot hangs
430rather than booting an invalid or compromised image.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300431
Marti Bolivar048d8d82017-08-04 17:14:24 -0400432Note: An important caveat to the above is the result when a swap is requested
David Vincze2d736ad2019-02-18 11:50:22 +0100433 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 Utzig86fe4b22017-07-28 18:56:29 -0300437
Christopher Collinsa1c12042019-05-23 14:00:28 -0700438### Resumed swaps
439
440If mcuboot determines that it is resuming an interrupted swap (i.e., a reset
441occurred 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
443section are not necessary in the resume case.
444
David Brown17e20d12017-09-12 11:53:20 -0600445## High-Level Operation
Christopher Collins92ea77f2016-12-12 15:59:26 -0800446
447With the terms defined, we can now explore the boot loader's operation. First,
448a high-level overview of the boot process is presented. Then, the following
449sections describe each step of the process in more detail.
450
451Procedure:
452
David Brown17e20d12017-09-12 11:53:20 -06004531. 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 Collins92ea77f2016-12-12 15:59:26 -0800456
David Brown17e20d12017-09-12 11:53:20 -06004572. Inspect image trailers; is a swap requested?
Christopher Collins92ea77f2016-12-12 15:59:26 -0800458 Yes.
David Vincze2d736ad2019-02-18 11:50:22 +0100459 ​ 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 Brown17e20d12017-09-12 11:53:20 -0600468 No: Proceed to step 3.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800469
David Vincze2d736ad2019-02-18 11:50:22 +01004703. Boot into image in primary slot.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800471
David Brown17e20d12017-09-12 11:53:20 -0600472## Image Swapping
Christopher Collins92ea77f2016-12-12 15:59:26 -0800473
474The boot loader swaps the contents of the two image slots for two reasons:
David Vincze2d736ad2019-02-18 11:50:22 +0100475 * 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 Collins92ea77f2016-12-12 15:59:26 -0800480
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300481If the image trailers indicates that the image in the secondary slot should be
Christopher Collins92ea77f2016-12-12 15:59:26 -0800482run, the boot loader needs to copy it to the primary slot. The image currently
483in the primary slot also needs to be retained in flash so that it can be used
484later. Furthermore, both images need to be recoverable if the boot loader
485resets in the middle of the swap operation. The two images are swapped
486according to the following procedure:
487
David Brown17e20d12017-09-12 11:53:20 -0600488<!-- Markdown doesn't do nested numbered lists. It will do nested
489bulletted lists, so maybe that is better. -->
David Vincze2d736ad2019-02-18 11:50:22 +0100490​ 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 Collins92ea77f2016-12-12 15:59:26 -0800513
David Vincze2d736ad2019-02-18 11:50:22 +0100514The additional caveats in step 2f are necessary so that the secondary slot image
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800515trailer can be written by the user at a later time. With the image trailer
David Vincze2d736ad2019-02-18 11:50:22 +0100516unwritten, the user can test the image in the secondary slot
517(i.e., transition to state II).
Christopher Collins92ea77f2016-12-12 15:59:26 -0800518
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300519Note1: If the sector being copied is the last sector, then swap status is
520temporarily maintained on scratch for the duration of this operation, always
David Vincze2d736ad2019-02-18 11:50:22 +0100521using the primary slot's area otherwise.
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300522
523Note2: The bootloader tries to copy only used sectors (based on largest image
524installed on any of the slots), minimizing the amount of sectors copied and
525reducing the amount of time required for a swap operation.
526
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800527The particulars of step 3 vary depending on whether an image is being tested,
David Vincze2d736ad2019-02-18 11:50:22 +0100528permanently used, reverted or a validation failure of the secondary slot
529happened when a swap was requested:
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300530
Christopher Collins92ea77f2016-12-12 15:59:26 -0800531 * test:
David Vincze2d736ad2019-02-18 11:50:22 +0100532 o Write primary_slot.copy_done = 1
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800533 (swap caused the following values to be written:
David Vincze2d736ad2019-02-18 11:50:22 +0100534 primary_slot.magic = BOOT_MAGIC
535 primary_slot.image_ok = Unset)
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800536
537 * permanent:
David Vincze2d736ad2019-02-18 11:50:22 +0100538 o Write primary_slot.copy_done = 1
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800539 (swap caused the following values to be written:
David Vincze2d736ad2019-02-18 11:50:22 +0100540 primary_slot.magic = BOOT_MAGIC
541 primary_slot.image_ok = 0x01)
Christopher Collins92ea77f2016-12-12 15:59:26 -0800542
543 * revert:
David Vincze2d736ad2019-02-18 11:50:22 +0100544 o Write primary_slot.copy_done = 1
545 o Write primary_slot.image_ok = 1
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300546 (swap caused the following values to be written:
David Vincze2d736ad2019-02-18 11:50:22 +0100547 primary_slot.magic = BOOT_MAGIC)
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300548
David Vincze2d736ad2019-02-18 11:50:22 +0100549 * failure to validate the secondary slot:
550 o Write primary_slot.image_ok = 1
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300551
David Vincze2d736ad2019-02-18 11:50:22 +0100552After completing the operations as described above the image in the primary slot
553should be booted.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800554
David Brown17e20d12017-09-12 11:53:20 -0600555## Swap Status
Christopher Collins92ea77f2016-12-12 15:59:26 -0800556
557The swap status region allows the boot loader to recover in case it restarts in
558the middle of an image swap operation. The swap status region consists of a
559series of single-byte records. These records are written independently, and
560therefore must be padded according to the minimum write size imposed by the
561flash hardware. In the below figure, a min-write-size of 1 is assumed for
562simplicity. The structure of the swap status region is illustrated below. In
563this figure, a min-write-size of 1 is assumed for simplicity.
564
David Brown17e20d12017-09-12 11:53:20 -0600565```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800566 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 Brown17e20d12017-09-12 11:53:20 -0600581```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800582
583The above is probably not helpful at all; here is a description in English.
584
585Each image slot is partitioned into a sequence of flash sectors. If we were to
586enumerate the sectors in a single slot, starting at 0, we would have a list of
587sector indices. Since there are two image slots, each sector index would
588correspond to a pair of sectors. For example, sector index 0 corresponds to
David Vincze2d736ad2019-02-18 11:50:22 +0100589the first sector in the primary slot and the first sector in the secondary slot.
590Finally, 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
592representation of this reversed list.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800593
594During a swap operation, each sector index transitions through four separate
595states:
David Brown17e20d12017-09-12 11:53:20 -0600596```
David Vincze2d736ad2019-02-18 11:50:22 +01005970. primary slot: image 0, secondary slot: image 1, scratch: N/A
5981. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1)
5992. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0)
6003. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0)
David Brown17e20d12017-09-12 11:53:20 -0600601```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800602
603Each time a sector index transitions to a new state, the boot loader writes a
604record to the swap status region. Logically, the boot loader only needs one
605record per sector index to keep track of the current swap state. However, due
606to limitations imposed by flash hardware, a record cannot be overwritten when
607an index's state changes. To solve this problem, the boot loader uses three
608records per sector index rather than just one.
609
610Each sector-state pair is represented as a set of three records. The record
611values map to the above four states as follows
612
David Brown17e20d12017-09-12 11:53:20 -0600613```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800614 | 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 Brown17e20d12017-09-12 11:53:20 -0600620```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800621
Fabio Utzig2c05f1b2018-04-04 10:35:17 -0300622The swap status region can accommodate `BOOT_MAX_IMG_SECTORS` sector indices.
David Vincze2d736ad2019-02-18 11:50:22 +0100623Hence, the size of the region, in bytes, is
624`BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index
625count 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
627device's image slots have been configured with `BOOT_MAX_IMG_SECTORS: 128` and
628use less than 128 sectors, the first record that gets written will be somewhere
629in the middle of the region. For example, if a slot uses 64 sectors, the first
630sector index that gets swapped is 63, which corresponds to the exact halfway
631point within the region.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800632
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300633Note: since the scratch area only ever needs to record swapping of the last
634sector, it uses at most min-write-size * 3 bytes for its own status area.
635
David Brown17e20d12017-09-12 11:53:20 -0600636## Reset Recovery
Christopher Collins92ea77f2016-12-12 15:59:26 -0800637
638If the boot loader resets in the middle of a swap operation, the two images may
639be discontiguous in flash. Bootutil recovers from this condition by using the
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300640image trailers to determine how the image parts are distributed in flash.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800641
642The first step is determine where the relevant swap status region is located.
643Because this region is embedded within the image slots, its location in flash
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300644changes during a swap operation. The below set of tables map image trailers
Christopher Collins92ea77f2016-12-12 15:59:26 -0800645contents to swap status location. In these tables, the "source" field
646indicates where the swap status region is located.
647
David Brown17e20d12017-09-12 11:53:20 -0600648```
David Vincze2d736ad2019-02-18 11:50:22 +0100649 | primary slot | scratch |
650 ----------+--------------+--------------|
651 magic | Good | Any |
652 copy-done | 0x01 | N/A |
653 ----------+--------------+--------------'
654 source: none |
655 ----------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400656
David Vincze2d736ad2019-02-18 11:50:22 +0100657 | primary slot | scratch |
658 ----------+--------------+--------------|
659 magic | Good | Any |
660 copy-done | 0xff | N/A |
661 ----------+--------------+--------------'
662 source: primary slot |
663 ----------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400664
David Vincze2d736ad2019-02-18 11:50:22 +0100665 | primary slot | scratch |
666 ----------+--------------+--------------|
667 magic | Any | Good |
668 copy-done | Any | N/A |
669 ----------+--------------+--------------'
670 source: scratch |
671 ----------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400672
David Vincze2d736ad2019-02-18 11:50:22 +0100673 | 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 Brown17e20d12017-09-12 11:53:20 -0600686```
Christopher Collins92ea77f2016-12-12 15:59:26 -0800687
Christopher Collinsa1c12042019-05-23 14:00:28 -0700688If the swap status region indicates that the images are not contiguous, mcuboot
689determines the type of swap operation that was interrupted by reading the `swap
690type` field in the active image trailer, and then resumes the operation. In
691other words, it applies the procedure defined in the previous section, moving
692image 1 into the primary slot and image 0 into the secondary slot. If the boot
693status indicates that an image part is present in the scratch area, this part
694is copied into the correct location by starting at step e or step h in the
695area-swap procedure, depending on whether the part belongs to image 0 or image
6961.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800697
698After the swap operation has been completed, the boot loader proceeds as though
699it had just been started.
700
David Brown17e20d12017-09-12 11:53:20 -0600701## Integrity Check
Christopher Collins92ea77f2016-12-12 15:59:26 -0800702
703An image is checked for integrity immediately before it gets copied into the
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300704primary slot. If the boot loader doesn't perform an image swap, then it can
David Vincze2d736ad2019-02-18 11:50:22 +0100705perform 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
707integrity check.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800708
709During the integrity check, the boot loader verifies the following aspects of
710an image:
David Vincze2d736ad2019-02-18 11:50:22 +0100711​ * 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 Collins92ea77f2016-12-12 15:59:26 -0800720
David Brown17e20d12017-09-12 11:53:20 -0600721## Security
Christopher Collins92ea77f2016-12-12 15:59:26 -0800722
723As indicated above, the final step of the integrity check is signature
724verification. The boot loader can have one or more public keys embedded in it
725at build time. During signature verification, the boot loader verifies that an
Fabio Utzigea422c22017-09-11 11:02:47 -0300726image was signed with a private key that corresponds to the embedded keyhash
727TLV.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800728
729For information on embedding public keys in the boot loader, as well as
Fabio Utzig4dce6aa2018-02-12 15:31:32 -0200730producing signed images, see: [signed_images](signed_images.md).
Fabio Utzigcdfa11a2018-10-01 09:45:54 -0300731
732If you want to enable and use encrypted images, see:
733[encrypted_images](encrypted_images.md).