Lines Matching +full:working +full:- +full:directory
1 <!--
2 - SPDX-License-Identifier: Apache-2.0
4 - Copyright (c) 2017-2020 Linaro LTD
5 - Copyright (c) 2017-2019 JUUL Labs
6 - Copyright (c) 2019-2024 Arm Limited
8 - Original license:
10 - Licensed to the Apache Software Foundation (ASF) under one
11 - or more contributor license agreements. See the NOTICE file
12 - distributed with this work for additional information
13 - regarding copyright ownership. The ASF licenses this file
14 - to you under the Apache License, Version 2.0 (the
15 - "License"); you may not use this file except in compliance
16 - with the License. You may obtain a copy of the License at
18 - http://www.apache.org/licenses/LICENSE-2.0
20 - Unless required by applicable law or agreed to in writing,
21 - software distributed under the License is distributed on an
22 - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
23 - KIND, either express or implied. See the License for the
24 - specific language governing permissions and limitations
25 - under the License.
26 -->
49 * Built to run from a fixed location (i.e., not position-independent).
51 ## [Image format](#image-format)
110 #define IMAGE_TLV_ECDSA224 0x21 /* ECDSA of hash output - Not supported anymore */
114 #define IMAGE_TLV_ENC_RSA2048 0x30 /* Key encrypted with RSA-OAEP-2048 */
115 #define IMAGE_TLV_ENC_KW 0x31 /* Key encrypted with AES-KW-128 or
117 #define IMAGE_TLV_ENC_EC256 0x32 /* Key encrypted with ECIES-P256 */
118 #define IMAGE_TLV_ENC_X25519 0x33 /* Key encrypted with ECIES-X25519 */
123 Optional type-length-value records (TLVs) containing image metadata are placed
137 ## [Flash map](#flash-map)
152 /* If the bootloader is working with the first image */
157 /* If the bootloader is working with the second image */
166 working).
168 ## [Image slots](#image-slots)
174 (the exception to this is the [direct-xip](#direct-xip) and the
175 [ram-load](#ram-load) upgrade mode). If the bootloader needs to run the
178 contents of the primary slot. The bootloader supports either swap- or
179 overwrite-based image upgrades, but must be configured at build time to choose
182 ### [Swap using scratch](#image-swap-using-scratch)
184 When swap-using-scratch algorithm is used, in addition to the slots of
220 There is no *best* ratio, as the right size is use-case dependent. Factors to
226 swap-using scratch algorithm assumes that the primary and the secondary image
231 maximum-image-size = image-slot-size - image-trailer-size
235 `image-slot-size` is the size of the image slot.
236 `image-trailer-size` is the size of the image trailer.
238 ### [Swap without using scratch](#image-swap-no-scratch)
240 This algorithm is an alternative to the swap-using-scratch algorithm.
246 2. Copies the N-th sector from the secondary slot to the N-th sector of the
248 3. Copies the (N+1)-th sector from the primary slot to the N-th sector of the
254 memory-size-effective slot layout is when the primary slot is larger than
257 although same-sized slots are allowed as well.
264 maximum-image-size = (N-1) * slot-sector-size - image-trailer-sectors-size
269 `image-trailer-sectors-size` is the size of the image trailer rounded up to
270 the total size of sectors its occupied. For instance if the image-trailer-size
272 `image-trailer-sectors-size` will be equal to 2048 B.
281 ### [Equal slots (direct-xip)](#direct-xip)
283 When the direct-xip mode is enabled the active image flag is "moved" between the
296 chain-loads it.
299 read the [corresponding section](#direct-xip-revert).
301 images are not moved between the slots, the on-the-fly image
306 The overwrite and the direct-xip upgrade strategies are substantially simpler to
312 ### [RAM loading](#ram-load)
314 In ram-load mode the slots are equal. Like the direct-xip mode, this mode
318 copied to, is stored in the image header. The ram-load upgrade mode can be
324 execution. Ram-load mode requires the image to be built to be executed from
326 ram-load is enabled then platform must define the following parameters:
343 When ram-load is enabled, the `--load-addr <addr>` option of the `imgtool`
348 When the encryption option is enabled (`MCUBOOT_ENC_IMAGES`) along with ram-load
354 ## [Boot swap types](#boot-swap-types)
356 When the device first boots under normal circumstances, there is an up-to-date
358 chain-load. In this case, no image swaps are necessary. During device upgrades,
362 Upgrading an old image with a new one by swapping can be a two-step process. In
376 upon booting a new (bad) image, MCUboot will revert to the old (working) image
378 device firmware to make test swaps permanent only after performing a self-test
387 - `BOOT_SWAP_TYPE_NONE`: The "usual" or "no upgrade" case; attempt to boot the
390 - `BOOT_SWAP_TYPE_TEST`: Boot the contents of the secondary slot by swapping
393 - `BOOT_SWAP_TYPE_PERM`: Permanently swap images, and boot the upgraded image
396 - `BOOT_SWAP_TYPE_REVERT`: A previous test swap was not made permanent;
401 - `BOOT_SWAP_TYPE_FAIL`: Swap failed because image to be run is not valid.
403 - `BOOT_SWAP_TYPE_PANIC`: Swapping encountered an unrecoverable error.
405 The "swap type" is a high-level representation of the outcome of the
407 the bit-level contents of flash.
409 ### [Revert mechanism in direct-xip mode](#direct-xip-revert)
411 The direct-xip mode also supports a "revert" mechanism which is the equivalent
412 of the swap mode's "revert" swap. When the direct-xip mode is selected it can be
414 must also be added to the signed images (the "--pad" option of the `imgtool`
416 [Image Trailer](#image-trailer) section and the [imgtool](imgtool.md)
419 direct-xip mode's "revert" mechanism are the following:
423 + Yes: Did the image mark itself "OK" (was the self-test successful)?
425 - Proceed to step 3.
427 - Erase the image from the slot to prevent it from being selected
429 - Return to step 1 (the bootloader will attempt to select and
432 - Mark the image as "selected" (set the copy_done flag in the trailer).
433 - Proceed to step 3.
436 ## [Image trailer](#image-trailer)
449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
451 ~ Swap status (BOOT_MAX_IMG_SECTORS * min-write-size * 3) ~
453 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
462 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
467 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
470 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
472 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
474 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
476 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
482 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
490 ---
493 *"min-write-size" is a property of the flash hardware. If the hardware*
495 *min-write-size is 1. If the hardware only allows writes at even addresses,*
496 *then min-write-size is 2, and so on.*
498 ---
506 - sector data in the primary slot is copied into scratch, then erased
507 - sector data in the secondary slot is copied into the primary slot,
509 - sector data in scratch is copied into the secondary slot
520 The factor of min-write-size is due to the behavior of flash hardware. The factor
523 2. Encryption keys: key-encrypting keys (KEKs). These keys are needed for
533 - Swap type: Stored in bits 0-3. Indicating the type of swap operation in
537 - Image number: Stored in bits 4-7. It has always 0 value at single image
545 | ------------------------- | ----- |
557 7. MAGIC: A 16-byte field identifying the image trailer layout. It may assume
586 14-byte pattern:
600 ---
604 could be huge. For example, for 128 slot sectors with a 4-byte alignment,
607 ---
609 ## [Image trailers](#image-trailers)
615 ### [New swaps (non-resumes)](#new-swaps-non-resumes)
626 ---
633 ---
638 -----------------+--------------+----------------|
640 image-ok | Any | Unset |
641 copy-done | Any | Any |
642 -----------------+--------------+----------------'
644 -------------------------------------------------'
649 -----------------+--------------+----------------|
651 image-ok | Any | 0x01 |
652 copy-done | Any | Any |
653 -----------------+--------------+----------------'
655 -------------------------------------------------'
660 -----------------+--------------+----------------|
662 image-ok | 0xff | Any |
663 copy-done | 0x01 | Any |
664 -----------------+--------------+----------------'
666 -------------------------------------------------'
677 -----------------+--------------+----------------|
679 image-ok | Any | Any |
680 copy-done | Any | Any |
681 -----------------+--------------+----------------'
685 -------------------------------------------------'
695 ---
704 ---
706 ### [Resumed swaps](#resumed-swaps)
709 occurred mid-swap), it fully determines the operation to resume by reading the
711 0-3. The set of tables in the previous section are not necessary in the resume
714 ## [High-level operation](#high-level-operation)
717 a high-level overview of the boot process is presented. Then, the following
742 ### [Multiple image boot](#multiple-image-boot)
749 +--------------------+
751 +--------------------+
752 ~~~~~ <- memory might be not contiguous
753 +--------------------+
756 +--------------------+
759 +--------------------+
760 ~~~~~ <- memory might be not contiguous
761 +--------------------+
764 +--------------------+
767 +--------------------+
769 +--------------------+
778 iterate over all the firmware images. The high-level overview of the boot
834 …# [Multiple image boot for RAM loading and direct-xip](#multiple-image-boot-for-ram-loading-and-di…
836 The operation of the bootloader is different when the ram-load or the
837 direct-xip strategy is chosen. The flash map is very similar to the swap
845 + Copy it to RAM in case of ram-load strategy.
848 slot. (Image must be deleted from RAM too in case of ram-load
857 + Delete the image from RAM in case of ram-load strategy, but
869 ## [Image swapping](#image-swapping)
898 - If this is the last region in the slot, scratch area has a temporary
902 - Else if this is the first swapped region but not the last region in
905 - Else, copy entire region contents.
910 - If this is not the last region in the slot, erase the trailer in the
916 - If this is the last region in the slot, the status is read from
927 ---
934 ---
941 ---
973 ## [Swap status](#swap-status)
977 series of single-byte records. These records are written independently, and
979 flash hardware. In the below figure, a min-write-size of 1 is assumed for
981 this figure, a min-write-size of 1 is assumed for simplicity.
986 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
988 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
990 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
992 +-+-+-+-+-+-+-+-+ +
996 ~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
998 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1009 `BOOT_MAX_IMG_SECTORS - 1` and ends with 0. The swap status region is a
1016 1. primary slot: image 0, secondary slot: N/A, scratch: image 1 (1->s, erase 1)
1017 2. primary slot: N/A, secondary slot: image 0, scratch: image 1 (0->1, erase 0)
1018 3. primary slot: image 1, secondary slot: image 0, scratch: N/A (s->0)
1028 Each sector-state pair is represented as a set of three records. The record
1033 --------+------+------+------
1042 `BOOT_MAX_IMG_SECTORS * min-write-size * 3`. The only requirement for the index
1043 count is that it is great enough to account for a maximum-sized image
1051 ---
1055 *sector, it uses at most min-write-size * 3 bytes for its own status area.*
1057 ---
1059 ## [Reset recovery](#reset-recovery)
1077 ----------+--------------+--------------|
1079 copy-done | 0x01 | N/A |
1080 ----------+--------------+--------------'
1082 ----------------------------------------'
1085 ----------+--------------+--------------|
1087 copy-done | 0xff | N/A |
1088 ----------+--------------+--------------'
1090 ----------------------------------------'
1093 ----------+--------------+--------------|
1095 copy-done | Any | N/A |
1096 ----------+--------------+--------------'
1098 ----------------------------------------'
1101 ----------+--------------+--------------|
1103 copy-done | 0xff | N/A |
1104 ----------+--------------+--------------|
1106 ----------------------------------------+------------------------------+
1109 o Mid-revert; status in the primary slot. |
1112 -----------------------------------------------------------------------'
1118 0-3 then resumes the operation. In other words, it applies the procedure defined
1122 at step e or step h in the area-swap procedure, depending on whether the part
1128 ## [Integrity check](#integrity-check)
1139 * 32-bit magic number must be correct (`IMAGE_MAGIC`).
1153 (~1-2 seconds on a arm-cortex-M0), the `MCUBOOT_VALIDATE_PRIMARY_SLOT_ONCE`
1175 ---
1178 *Image encryption is not supported when the direct-xip upgrade strategy*
1181 ---
1183 ### [Using hardware keys for verification](#hw-key-support)
1195 - `MCUBOOT_HW_KEY`: In this case the hash of the public key must be
1197 key-hash from there. For this reason the target must provide a definition
1200 the `full` option for the `--public-key-format` imgtool argument in order to
1204 TLV area and compares it with the key-hash that was retrieved from the device.
1205 - `MCUBOOT_BUILTIN_KEY`: With this option the whole public key(s) used for
1217 ## [Protected TLVs](#protected-tlvs)
1232 A +---------------------+
1233 | Header | <- struct image_header
1234 +---------------------+
1236 +---------------------+
1238 | +-----------------+ | struct image_tlv_info with
1239 | | TLV area header | | <- IMAGE_TLV_PROT_INFO_MAGIC (optional)
1240 | +-----------------+ |
1241 | | Protected TLVs | | <- Protected TLVs (struct image_tlv)
1242 B | +-----------------+ |
1243 | | TLV area header | | <- struct image_tlv_info with IMAGE_TLV_INFO_MAGIC
1244 C | +-----------------+ |
1245 | | SHA256 hash | | <- hash from A - B (struct image_tlv)
1246 D | +-----------------+ |
1247 | | Keyhash | | <- indicates which pub. key for sig (struct image_tlv)
1248 | +-----------------+ |
1249 | | Signature | | <- signature from C - D (struct image_tlv), only hash
1250 | +-----------------+ |
1251 +---------------------+
1254 ## [Dependency check](#dependency-check)
1278 ## [Downgrade prevention](#downgrade-prevention)
1285 ### [Software-based downgrade prevention](#sw-downgrade-prevention)
1290 overwrite-based image update strategy is used (i.e. `MCUBOOT_OVERWRITE_ONLY`
1293 ### [Hardware-based downgrade prevention](#hw-downgrade-prevention)
1296 can be added to the image using the `-s` option of the [imgtool](imgtool.md) script.
1299 counter value which must be stored in a non-volatile and trusted component of
1312 ## [Measured boot and data sharing](#boot-data-sharing)
1325 In the shared memory area all data entries are stored in a type-length-value
1355 When enabled, the `--boot_record` argument of the imgtool script must also be
1366 The `sw_type` string that is passed as the `--boot_record` option's parameter
1388 ## [Testing in CI](#testing-in-ci)
1390 ### [Testing Fault Injection Hardening (FIH)](#testing-fih)
1399 - Set breakpoint at specified address.
1400 - Continue execution.
1401 - On breakpoint hit increase the Program Counter.
1402 - Continue execution.
1403 - Detach from target after a timeout reached.
1412 with `-O0` optimisation is more resilient against FI attacks than the code
1413 generated with `-O3` or `-Os` optimizations.
1420 function. For the purpose of this test Trusted-Firmware-M has been selected as
1421 it supports Armv8-M platforms that are also emulated by QEMU.
1431 # Implemented in ci/fih-tests_install.sh
1434 # See details below. Implemented in ci/fih-tests_run.sh.
1473 - The image is corrupted by changing its signature.
1474 - MCUBOOT_FIH_PROFILE_MAX is not tested as it requires TRNG, and the AN521
1479 - The test cases defined in .travis.yml always return `passed`, if they were
1489 are issued from the MCUboot source directory):
1493 $ ./ci/fih-tests_install.sh
1495 ./ci/fih-tests_run.sh
1505 - The docker image needs to be built with `ci/fih-tests_install.sh` as described
1507 - Start the docker image with the following command:
1508 `docker run -i -t mcuboot/fih-test`.
1509 - Execute the test with a command similar to the following: