1 /*
2 * SPDX-License-Identifier: Apache-2.0
3 *
4 * Copyright (c) 2019 JUUL Labs
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 #ifndef H_SWAP_PRIV_
20 #define H_SWAP_PRIV_
21
22 #include "mcuboot_config/mcuboot_config.h"
23
24 #if defined(MCUBOOT_SWAP_USING_SCRATCH) || defined(MCUBOOT_SWAP_USING_MOVE) || defined(MCUBOOT_SWAP_USING_OFFSET)
25
26 /**
27 * Calculates the amount of space required to store the trailer, and erases
28 * all sectors required for this storage in the given flash_area.
29 */
30 int swap_erase_trailer_sectors(const struct boot_loader_state *state,
31 const struct flash_area *fap);
32
33 /**
34 * Initialize the given flash_area with the metadata required to start a new
35 * swap upgrade.
36 */
37 int swap_status_init(const struct boot_loader_state *state,
38 const struct flash_area *fap,
39 const struct boot_status *bs);
40
41 /**
42 * Tries to locate an interrupted swap status (metadata). If not metadata
43 * was found returns BOOT_STATUS_SOURCE_NONE.
44 *
45 * Must return one of:
46 * - BOOT_STATUS_SOURCE_NONE
47 * - BOOT_STATUS_SOURCE_SCRATCH
48 * - BOOT_STATUS_SOURCE_PRIMARY_SLOT
49 */
50 int swap_status_source(struct boot_loader_state *state);
51
52 /**
53 * Reads the boot status from the flash. The boot status contains
54 * the current state of an interrupted image copy operation. If the boot
55 * status is not present, or it indicates that previous copy finished,
56 * there is no operation in progress.
57 */
58 int swap_read_status(struct boot_loader_state *state, struct boot_status *bs);
59
60 /**
61 * Iterate over the swap status bytes in the given flash_area and populate
62 * the given boot_status with the calculated index where a swap upgrade was
63 * interrupted.
64 */
65 int swap_read_status_bytes(const struct flash_area *fap,
66 struct boot_loader_state *state,
67 struct boot_status *bs);
68
69 /**
70 * Marks the image in the primary slot as fully copied.
71 */
72 int swap_set_copy_done(uint8_t image_index);
73
74 /**
75 * Marks a reverted image in the primary slot as confirmed. This is necessary to
76 * ensure the status bytes from the image revert operation don't get processed
77 * on a subsequent boot.
78 *
79 * NOTE: image_ok is tested before writing because if there's a valid permanent
80 * image installed on the primary slot and the new image to be upgrade to has a
81 * bad sig, image_ok would be overwritten.
82 */
83 int swap_set_image_ok(uint8_t image_index);
84
85 /**
86 * Start a new or resume an interrupted swap according to the parameters
87 * found in the given boot_status.
88 */
89 void swap_run(struct boot_loader_state *state,
90 struct boot_status *bs,
91 uint32_t copy_size);
92
93 #if MCUBOOT_SWAP_USING_SCRATCH
94 #define BOOT_SCRATCH_AREA(state) ((state)->scratch.area)
95
boot_scratch_area_size(const struct boot_loader_state * state)96 static inline size_t boot_scratch_area_size(const struct boot_loader_state *state)
97 {
98 return flash_area_get_size(BOOT_SCRATCH_AREA(state));
99 }
100 #endif
101
102 #endif /* defined(MCUBOOT_SWAP_USING_SCRATCH) || defined(MCUBOOT_SWAP_USING_MOVE) || defined(MCUBOOT_SWAP_USING_OFFSET) */
103
104 #if defined(MCUBOOT_SWAP_USING_MOVE) || defined(MCUBOOT_SWAP_USING_OFFSET)
105 /**
106 * Check if device write block sizes are as expected, function should emit an error if there is
107 * a problem. If true is returned, the slots are marked as compatible, otherwise the slots are
108 * marked as incompatible.
109 *
110 * Requires MCUBOOT_SLOT0_EXPECTED_WRITE_SIZE be set to the write block size of image 0 primary
111 * slot and MCUBOOT_SLOT1_EXPECTED_WRITE_SIZE be set to the write block size of image 0 secondary
112 * slot.
113 */
114 bool swap_write_block_size_check(struct boot_loader_state *state);
115 #endif /* defined(MCUBOOT_SWAP_USING_MOVE) || defined(MCUBOOT_SWAP_USING_OFFSET) */
116
117 /**
118 * Returns the maximum size of an application that can be loaded to a slot.
119 */
120 int app_max_size(struct boot_loader_state *state);
121
122 #endif /* H_SWAP_PRIV_ */
123
