blob: bc4abea2e7994d095d4a74407500e8b0fbae8c09 [file] [log] [blame]
Christopher Collins92ea77f2016-12-12 15:59:26 -08001#
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
Marti Bolivar49b29172017-08-04 14:50:51 -04009#
Christopher Collins92ea77f2016-12-12 15:59:26 -080010# http://www.apache.org/licenses/LICENSE-2.0
11#
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
23
Fabio Utzigac834962017-07-20 13:20:48 -030024mcuboot comprises two packages:
Christopher Collins92ea77f2016-12-12 15:59:26 -080025
26 * The bootutil library (boot/bootutil)
Fabio Utzig5bd4e582017-07-20 08:55:38 -030027 * 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
36*** LIMITATIONS
37
38The boot loader currently only supports images with the following
39characteristics:
40 * Built to run from flash.
Marti Bolivar49b29172017-08-04 14:50:51 -040041 * Built to run from a fixed location (i.e., not position-independent).
Christopher Collins92ea77f2016-12-12 15:59:26 -080042
43*** IMAGE FORMAT
44
45The following definitions describe the image format.
46
47#define IMAGE_MAGIC 0x96f3b83c
48
49#define IMAGE_HEADER_SIZE 32
50
51struct image_version {
52 uint8_t iv_major;
53 uint8_t iv_minor;
54 uint16_t iv_revision;
55 uint32_t iv_build_num;
56};
57
58/** Image header. All fields are in little endian byte order. */
59struct image_header {
60 uint32_t ih_magic;
61 uint16_t ih_tlv_size; /* Combined size of trailing TLVs (bytes). */
62 uint8_t ih_key_id; /* Which key image is signed with (0xff=unsigned). */
63 uint8_t _pad1;
64 uint16_t ih_hdr_size; /* Size of image header (bytes). */
65 uint16_t _pad2;
66 uint32_t ih_img_size; /* Does not include header. */
67 uint32_t ih_flags; /* IMAGE_F_[...] */
68 struct image_version ih_ver;
69 uint32_t _pad3;
70};
71
72/** Image trailer TLV format. All fields in little endian. */
73struct image_tlv {
74 uint8_t it_type; /* IMAGE_TLV_[...]. */
75 uint8_t _pad;
Marti Bolivar49b29172017-08-04 14:50:51 -040076 uint16_t it_len; /* Data length (not including TLV header). */
Christopher Collins92ea77f2016-12-12 15:59:26 -080077};
78
79/*
80 * Image header flags.
81 */
Marti Bolivar7c057e92017-08-04 14:46:39 -040082#define IMAGE_F_PIC 0x00000001 /* Not supported. */
83#define IMAGE_F_SHA256 0x00000002 /* Hash TLV is present */
84#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 /* PKCS15 w/RSA and SHA */
85#define IMAGE_F_ECDSA224_SHA256 0x00000008 /* ECDSA224 over SHA256 */
86#define IMAGE_F_NON_BOOTABLE 0x00000010 /* Split image app. */
87#define IMAGE_F_ECDSA256_SHA256 0x00000020 /* ECDSA256 over SHA256 */
88#define IMAGE_F_PKCS1_PSS_RSA2048_SHA256 0x00000040 /* PKCS1 PSS */
Christopher Collins92ea77f2016-12-12 15:59:26 -080089
90/*
91 * Image trailer TLV types.
92 */
Fabio Utzig150ea962017-03-08 11:25:09 -030093#define IMAGE_TLV_SHA256 1 /* SHA256 of image hdr and body */
94#define IMAGE_TLV_RSA2048 2 /* RSA2048 of hash output */
Christopher Collins92ea77f2016-12-12 15:59:26 -080095#define IMAGE_TLV_ECDSA224 3 /* ECDSA of hash output */
Fabio Utzig150ea962017-03-08 11:25:09 -030096#define IMAGE_TLV_ECDSA256 4 /* ECDSA of hash output */
Christopher Collins92ea77f2016-12-12 15:59:26 -080097
98Optional type-length-value records (TLVs) containing image metadata are placed
99after the end of the image.
100
101The ih_hdr_size field indicates the length of the header, and therefore the
102offset of the image itself. This field provides for backwards compatibility in
103case of changes to the format of the image header.
104
105*** FLASH MAP
106
Fabio Utzigac834962017-07-20 13:20:48 -0300107A device's flash is partitioned according to its _flash map_. At a high
Christopher Collins92ea77f2016-12-12 15:59:26 -0800108level, the flash map maps numeric IDs to _flash areas_. A flash area is a
109region of disk with the following properties:
110 (1) An area can be fully erased without affecting any other areas.
111 (2) A write to one area does not restrict writes to other areas.
112
113The boot loader uses the following flash areas:
114
115#define FLASH_AREA_BOOTLOADER 0
116#define FLASH_AREA_IMAGE_0 1
117#define FLASH_AREA_IMAGE_1 2
118#define FLASH_AREA_IMAGE_SCRATCH 3
119
120*** IMAGE SLOTS
121
122A portion of the flash memory is partitioned into two image slots: a primary
123slot (0) and a secondary slot (1). The boot loader will only run an image from
124the primary slot, so images must be built such that they can run from that
125fixed location in flash. If the boot loader needs to run the image resident in
126the secondary slot, it must swap the two images in flash prior to booting.
127
128In addition to the two image slots, the boot loader requires a scratch area to
129allow for reliable image swapping.
130
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800131*** BOOT STATES
132
133Logically, you can think of a pair of values associated with each image slot:
134pending and confirmed. On startup, the boot loader determines the state of the
135device by inspecting each pair of values. These values have the following
136meanings:
137
138* pending: Indicates whether the image should be used on the next reboot; can
139 hold one of three values:
140 " " (unset): Don't use image on next boot
141 "T" (temporary): Use image on next boot; absent subsequent confirm command,
142 revert to original image on second reboot.
143 "P" (permanent): Use image on next boot and all subsequent boots
144
145* confirmed: always use image unless excluded by a test image.
146
147In English, when the user wants to run the secondary image, they set the
148pending flag for the second slot and reboot the device. On startup, the boot
149loader will swap the two images in flash, clear the secondary slot's pending
150flag, and run the newly-copied image in slot 0. If the user set the pending
151flag to "temporary," then this is only a temporary state; if the device reboots
152again, the boot loader swaps the images back to their original slots and boots
153into the original image. If the user doesn't want to revert to the original
154state, they can make the current state permanent by setting the confirmed flag
155in slot 0.
156
157Switching to an alternate image is a two-step process (set + confirm) to
158prevent a device from becoming "bricked" by bad firmware. If the device
159crashes immediately upon booting the second image, the boot loader reverts to
160the working image, rather than repeatedly rebooting into the bad image.
161
162Alternatively, if the user is confident that the second image is good, they can
163set and confirm in a single action by setting the pending flag to "permanent."
164
165The following set of tables illustrate the four possible states that the device
166can be in:
167
168 | slot-0 | slot-1 |
169 ---------------+--------+--------|
170 pending | | |
171 confirmed | X | |
172 ---------------+--------+--------'
173 Image 0 confirmed; |
174 No change on reboot |
175 ---------------------------------'
176
177 | slot-0 | slot-1 |
178 ---------------+--------+--------|
179 pending | | T |
180 confirmed | X | |
181 ---------------+--------+--------'
182 Image 0 confirmed; |
183 Test image 1 on next reboot |
184 ---------------------------------'
185
186 | slot-0 | slot-1 |
187 ---------------+--------+--------|
188 pending | | P |
189 confirmed | X | |
190 ---------------+--------+--------'
191 Image 0 confirmed; |
192 Use image 1 permanently on boot |
193 ---------------------------------'
194
195 | slot-0 | slot-1 |
196 ---------------+--------+--------|
197 pending | | |
198 confirmed | | X |
199 ---------------+--------+--------'
200 Testing image 0; |
201 Revert to image 1 on next reboot |
202 ---------------------------------'
203
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300204*** IMAGE TRAILER
Christopher Collins92ea77f2016-12-12 15:59:26 -0800205
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300206For the bootloader to be able to determine the current state and what actions
207should be taken during the current boot operation, it uses metadata existing
208on both slots, and while doing a swap operation it can be located in scratch.
209This metadata is located at the end of the slot and is called image trailer.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800210An image trailer has the following structure:
211
212 0 1 2 3
213 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
214 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Christopher Collins92ea77f2016-12-12 15:59:26 -0800215 ~ ~
216 ~ Swap status (128 * min-write-size * 3) ~
217 ~ ~
218 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Fabio Utzig2c305aa2017-07-20 13:14:25 -0300219 | Copy done | 0xff padding (7 octets) |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800220 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Fabio Utzig2c305aa2017-07-20 13:14:25 -0300221 | Image OK | 0xff padding (7 octets) |
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300222 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
223 | MAGIC (16 octets) |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800224 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
225
226These records are at the end of each image slot. The offset immediately
227following such a record represents the start of the next flash area.
228
229Note: "min-write-size" is a property of the flash hardware. If the hardware
230allows individual bytes to be written at arbitrary addresses, then
231min-write-size is 1. If the hardware only allows writes at even addresses,
232then min-write-size is 2, and so on.
233
234The fields are defined as follows:
235
Fabio Utzig5bd4e582017-07-20 08:55:38 -03002361. Swap status: A series of single-byte records. Each record corresponds to a
237flash sector in an image slot. A swap status byte indicate the location of
238the corresponding sector data. During an image swap, image data is moved one
239sector at a time. The swap status is necessary for resuming a swap operation
240if the device rebooted before a swap operation completed.
241
2422. Copy done: A single byte indicating whether the image in this slot is
243complete (0x01=done; 0xff=not done).
244
2453. Image OK: A single byte indicating whether the image in this slot has been
246confirmed as good by the user (0x01=confirmed; 0xff=not confirmed).
247
2484. MAGIC: The following 16 bytes, written in host-byte-order:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800249
250 const uint32_t boot_img_magic[4] = {
251 0xf395c277,
252 0x7fefd260,
253 0x0f505235,
254 0x8079b62c,
255 };
256
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300257*** IMAGE TRAILERS
258
259At startup, the boot loader determines which of the above four states the
260device is in by inspecting the image trailers. When using the term "image
261trailers" what is meant is the aggregate information provided by both image
262slot's trailers.
263
264The image trailers records are structured around the limitations imposed by flash
Christopher Collins92ea77f2016-12-12 15:59:26 -0800265hardware. As a consequence, they do not have a very intuitive design, and it
266is difficult to get a sense of the state of the device just by looking at the
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300267image trailers. It is better to map all the possible trailer states to the four
Christopher Collins92ea77f2016-12-12 15:59:26 -0800268states described above via a set of tables. These tables are reproduced below.
269In these tables, the "pending" and "confirmed" flags are shown for illustrative
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300270purposes; they are not actually present in the image trailers.
271
272Note: An important caveat about the tables described below is that they must
273be evaluated in the order presented here. Lower state numbers must have a
274higher priority when testing the image trailers.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800275
276
277 State I
278 | slot-0 | slot-1 |
279 -----------------+--------+--------|
Christopher Collins92ea77f2016-12-12 15:59:26 -0800280 magic | Any | Good |
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800281 image-ok | Any | Unset |
Fabio Utzigf9d44282017-07-20 15:05:13 -0300282 copy-done | Any | Any |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800283 -----------------+--------+--------'
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800284 pending | | T |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800285 confirmed | X | |
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800286 -----------------+--------+--------'
287 swap: test |
288 -----------------------------------'
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300289
Christopher Collins92ea77f2016-12-12 15:59:26 -0800290
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300291 State II
Christopher Collins92ea77f2016-12-12 15:59:26 -0800292 | slot-0 | slot-1 |
293 -----------------+--------+--------|
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800294 magic | Any | Good |
295 image-ok | Any | 0x01 |
Fabio Utzigf9d44282017-07-20 15:05:13 -0300296 copy-done | Any | Any |
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800297 -----------------+--------+--------'
298 pending | | P |
299 confirmed | X | |
300 -----------------+--------+--------'
301 swap: permanent |
302 -----------------------------------'
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300303
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800304
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300305 State III
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800306 | slot-0 | slot-1 |
307 -----------------+--------+--------|
Christopher Collins92ea77f2016-12-12 15:59:26 -0800308 magic | Good | Unset |
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800309 image-ok | 0xff | Any |
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300310 copy-done | 0x01 | Any |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800311 -----------------+--------+--------'
312 pending | | |
313 confirmed | | X |
314 -----------------+--------+--------'
315 swap: revert (test image running) |
316 -----------------------------------'
317
318
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300319Those three states described above are explicity tested for and result in a
320swap decision by the bootloader. If the existing values in the the image trailers
321are not one of those previously described the bootloader will assume no swap
322operation is to be performed which is illustrated by state IV.
323
324
325 State IV
Christopher Collins92ea77f2016-12-12 15:59:26 -0800326 | slot-0 | slot-1 |
327 -----------------+--------+--------|
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300328 magic | Any | Any |
329 image-ok | Any | Any |
Fabio Utzigf9d44282017-07-20 15:05:13 -0300330 copy-done | Any | Any |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800331 -----------------+--------+--------'
332 pending | | |
333 confirmed | X | |
334 -----------------+--------+--------'
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300335 swap: none |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800336 -----------------------------------'
337
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300338
339Note: An important caveat to be mentioned here is, that due to the physical
340limitations of the storage and another possible failure, two extra "states"
341were added specifically to signal a failure in the boot process.
342
3431. One of them is a result of any device read/write error, called panic and
344 will result in the bootloader hanging without booting the image in slot 0.
345
3462. Another state was added specifically to handle the situation in which a swap
347 was requested and the image in slot 1 fails to validate, due to hashing
348 or signing error. This state behaves as state IV with the extra action of
349 marking the image in slot 0 as confirmed.
350
351
Christopher Collins92ea77f2016-12-12 15:59:26 -0800352*** HIGH-LEVEL OPERATION
353
354With the terms defined, we can now explore the boot loader's operation. First,
355a high-level overview of the boot process is presented. Then, the following
356sections describe each step of the process in more detail.
357
358Procedure:
359
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300360A. Inspect swap status region; is an interrupted swap being resumed?
Christopher Collins92ea77f2016-12-12 15:59:26 -0800361 Yes: Complete the partial swap operation; skip to step C.
362 No: Proceed to step B.
363
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300364B. Inspect image trailers; is a swap requested?
Christopher Collins92ea77f2016-12-12 15:59:26 -0800365 Yes.
366 1. Is the requested image valid (integrity and security check)?
367 Yes.
368 a. Perform swap operation.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300369 b. Persist completion of swap procedure to image trailers.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800370 c. Proceed to step C.
371 No.
372 a. Erase invalid image.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300373 b. Persist failure of swap procedure to image trailers.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800374 c. Proceed to step C.
375 No: Proceed to step C.
376
377C. Boot into image in slot 0.
378
Christopher Collins92ea77f2016-12-12 15:59:26 -0800379*** IMAGE SWAPPING
380
381The boot loader swaps the contents of the two image slots for two reasons:
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800382 * User has issued a "set pending" operation; the image in slot-1 should be
383 run once (state II) or repeatedly (state III), depending on whether a
384 permanent swap was specified.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800385 * Test image rebooted without being confirmed; the boot loader should
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800386 revert to the original image currently in slot-1 (state IV).
Christopher Collins92ea77f2016-12-12 15:59:26 -0800387
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300388If the image trailers indicates that the image in the secondary slot should be
Christopher Collins92ea77f2016-12-12 15:59:26 -0800389run, the boot loader needs to copy it to the primary slot. The image currently
390in the primary slot also needs to be retained in flash so that it can be used
391later. Furthermore, both images need to be recoverable if the boot loader
392resets in the middle of the swap operation. The two images are swapped
393according to the following procedure:
394
395 1. Determine how many flash sectors each image slot consists of. This
396 number must be the same for both slots.
397 2. Iterate the list of sector indices in descending order (i.e., starting
398 with the greatest index); current element = "index".
399 b. Erase scratch area.
400 c. Copy slot0[index] to scratch area.
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300401 - If these are the last sectors (i.e., first swap being perfomed),
402 copy the full sector *except* the image trailer.
403 - Else, copy entire sector contents.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800404 d. Write updated swap status (i).
405
406 e. Erase slot1[index]
407 f. Copy slot0[index] to slot1[index]
408 - If these are the last sectors (i.e., first swap being perfomed),
409 copy the full sector *except* the image trailer.
410 - Else, copy entire sector contents.
411 g. Write updated swap status (ii).
412
413 h. Erase slot0[index].
414 i. Copy scratch area slot0[index].
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300415 - If these are the last sectors (i.e., first swap being perfomed),
416 copy the full sector *except* the image trailer.
417 - Else, copy entire sector contents.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800418 j. Write updated swap status (iii).
419
420 3. Persist completion of swap procedure to slot 0 image trailer.
421
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800422The additional caveats in step 2f are necessary so that the slot 1 image
423trailer can be written by the user at a later time. With the image trailer
424unwritten, the user can test the image in slot 1 (i.e., transition to state
425II).
Christopher Collins92ea77f2016-12-12 15:59:26 -0800426
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300427Note1: If the sector being copied is the last sector, then swap status is
428temporarily maintained on scratch for the duration of this operation, always
429using slot0's area otherwise.
430
431Note2: The bootloader tries to copy only used sectors (based on largest image
432installed on any of the slots), minimizing the amount of sectors copied and
433reducing the amount of time required for a swap operation.
434
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800435The particulars of step 3 vary depending on whether an image is being tested,
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300436permanently used, reverted or a validation failure of slot 1 happened when a
437swap was requested:
438
Christopher Collins92ea77f2016-12-12 15:59:26 -0800439 * test:
440 o Write slot0.copy_done = 1
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800441 (swap caused the following values to be written:
442 slot0.magic = BOOT_MAGIC
443 slot0.image_ok = Unset)
Christopher Collinsfd7eb5c2016-12-21 13:46:08 -0800444
445 * permanent:
446 o Write slot0.copy_done = 1
447 (swap caused the following values to be written:
448 slot0.magic = BOOT_MAGIC
449 slot0.image_ok = 0x01)
Christopher Collins92ea77f2016-12-12 15:59:26 -0800450
451 * revert:
Christopher Collins92ea77f2016-12-12 15:59:26 -0800452 o Write slot0.copy_done = 1
453 o Write slot0.image_ok = 1
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300454 (swap caused the following values to be written:
455 slot0.magic = BOOT_MAGIC)
456
457 * failure to validate slot 1:
458 o Write slot0.image_ok = 1
459
460After completing the operations as described above the image in slot 0 should
461be booted.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800462
463*** SWAP STATUS
464
465The swap status region allows the boot loader to recover in case it restarts in
466the middle of an image swap operation. The swap status region consists of a
467series of single-byte records. These records are written independently, and
468therefore must be padded according to the minimum write size imposed by the
469flash hardware. In the below figure, a min-write-size of 1 is assumed for
470simplicity. The structure of the swap status region is illustrated below. In
471this figure, a min-write-size of 1 is assumed for simplicity.
472
473 0 1 2 3
474 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
475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
476 |sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |
477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
478 |sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |
479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
480 |sec125,state 2 | |
481 +-+-+-+-+-+-+-+-+ +
482 ~ ~
483 ~ [Records for indices 124 through 1 ~
484 ~ ~
485 ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
486 ~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |
487 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
488
489The above is probably not helpful at all; here is a description in English.
490
491Each image slot is partitioned into a sequence of flash sectors. If we were to
492enumerate the sectors in a single slot, starting at 0, we would have a list of
493sector indices. Since there are two image slots, each sector index would
494correspond to a pair of sectors. For example, sector index 0 corresponds to
495the first sector in slot 0 and the first sector in slot 1. Furthermore, we
496impose a limit of 128 indices. If an image slot consists of more than 128
497sectors, the flash layout is not compatible with this boot loader. Finally,
498reverse the list of indices such that the list starts with index 127 and ends
499with 0. The swap status region is a representation of this reversed list.
500
501During a swap operation, each sector index transitions through four separate
502states:
503 0. slot 0: image 0, slot 1: image 1, scratch: N/A
504 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1->s, erase 1)
505 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0->1, erase 0)
506 3. slot 0: image 1, slot 1: image 0, scratch: N/A (s->0)
507
508Each time a sector index transitions to a new state, the boot loader writes a
509record to the swap status region. Logically, the boot loader only needs one
510record per sector index to keep track of the current swap state. However, due
511to limitations imposed by flash hardware, a record cannot be overwritten when
512an index's state changes. To solve this problem, the boot loader uses three
513records per sector index rather than just one.
514
515Each sector-state pair is represented as a set of three records. The record
516values map to the above four states as follows
517
518 | rec0 | rec1 | rec2
519 --------+------+------+------
520 state 0 | 0xff | 0xff | 0xff
521 state 1 | 0x01 | 0xff | 0xff
522 state 2 | 0x01 | 0x02 | 0xff
523 state 3 | 0x01 | 0x02 | 0x03
524
525The swap status region can accommodate 128 sector indices. Hence, the size of
526the region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen
527somewhat arbitrarily and will likely be made configurable. The only
528requirement for the index count is that is is great enough to account for a
529maximum-sized image (i.e., at least as great as the total sector count in an
530image slot). If a device's image slots use less than 128 sectors, the first
531record that gets written will be somewhere in the middle of the region. For
532example, if a slot uses 64 sectors, the first sector index that gets swapped is
53363, which corresponds to the exact halfway point within the region.
534
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300535Note: since the scratch area only ever needs to record swapping of the last
536sector, it uses at most min-write-size * 3 bytes for its own status area.
537
Christopher Collins92ea77f2016-12-12 15:59:26 -0800538*** RESET RECOVERY
539
540If the boot loader resets in the middle of a swap operation, the two images may
541be discontiguous in flash. Bootutil recovers from this condition by using the
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300542image trailers to determine how the image parts are distributed in flash.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800543
544The first step is determine where the relevant swap status region is located.
545Because this region is embedded within the image slots, its location in flash
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300546changes during a swap operation. The below set of tables map image trailers
Christopher Collins92ea77f2016-12-12 15:59:26 -0800547contents to swap status location. In these tables, the "source" field
548indicates where the swap status region is located.
549
550 | slot-0 | scratch |
551 ----------+------------+------------|
552 magic | Good | Any |
553 copy-done | 0x01 | N/A |
554 ----------+------------+------------'
555 source: none |
556 ------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400557
Christopher Collins92ea77f2016-12-12 15:59:26 -0800558 | slot-0 | scratch |
559 ----------+------------+------------|
560 magic | Good | Any |
561 copy-done | 0xff | N/A |
562 ----------+------------+------------'
563 source: slot 0 |
564 ------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400565
Christopher Collins92ea77f2016-12-12 15:59:26 -0800566 | slot-0 | scratch |
567 ----------+------------+------------|
568 magic | Any | Good |
569 copy-done | Any | N/A |
570 ----------+------------+------------'
571 source: scratch |
572 ------------------------------------'
Marti Bolivar49b29172017-08-04 14:50:51 -0400573
Christopher Collins92ea77f2016-12-12 15:59:26 -0800574 | slot-0 | scratch |
575 ----------+------------+------------|
576 magic | Unset | Any |
577 copy-done | 0xff | N/A |
578 ----------+------------+------------|
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300579 source: slot 0 |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800580 ------------------------------------+------------------------------+
581 This represents one of two cases: |
582 o No swaps ever (no status to read, so no harm in checking). |
583 o Mid-revert; status in slot 0. |
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300584 For this reason we assume slot 0 as source, to trigger a check |
585 of the status area and find out if there was swapping under way. |
Christopher Collins92ea77f2016-12-12 15:59:26 -0800586 -------------------------------------------------------------------'
587
588
589If the swap status region indicates that the images are not contiguous,
590bootutil completes the swap operation that was in progress when the system was
591reset. In other words, it applies the procedure defined in the previous
592section, moving image 1 into slot 0 and image 0 into slot 1. If the boot
593status file indicates that an image part is present in the scratch area, this
594part is copied into the correct location by starting at step e or step h in the
595area-swap procedure, depending on whether the part belongs to image 0 or image
5961.
597
598After the swap operation has been completed, the boot loader proceeds as though
599it had just been started.
600
601*** INTEGRITY CHECK
602
603An image is checked for integrity immediately before it gets copied into the
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300604primary slot. If the boot loader doesn't perform an image swap, then it can
605perform an optional integrity check of the image in slot0 if
606MCUBOOT_VALIDATE_SLOT0 is set, otherwise it doesn't perform an integrity check.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800607
608During the integrity check, the boot loader verifies the following aspects of
609an image:
610 * 32-bit magic number must be correct (0x96f3b83c).
611 * Image must contain a SHA256 TLV.
Fabio Utzig86fe4b22017-07-28 18:56:29 -0300612 * Calculated SHA256 must match SHA256 TLV contents.
Christopher Collins92ea77f2016-12-12 15:59:26 -0800613 * Image *may* contain a signature TLV. If it does, its contents must be
614 verifiable using a key embedded in the boot loader.
615
616*** SECURITY
617
618As indicated above, the final step of the integrity check is signature
619verification. The boot loader can have one or more public keys embedded in it
620at build time. During signature verification, the boot loader verifies that an
621image was signed with a private key that corresponds to one of its public keys.
622The image signature TLV indicates the index of the key that is has been signed
623with. The boot loader uses this index to identify the corresponding public
624key.
625
626For information on embedding public keys in the boot loader, as well as
Fabio Utzig5bd4e582017-07-20 08:55:38 -0300627producing signed images, see: doc/signed_images.md