1 /*
2  * SPDX-FileCopyrightText: 2018-2021 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 #pragma once
7 
8 #include "bootloader_config.h"
9 #include "esp_image_format.h"
10 #include "bootloader_config.h"
11 
12 /**
13  * @brief Load partition table.
14  *
15  * Parse partition table, get useful data such as location of
16  * OTA data partition, factory app partition, and test app partition.
17  *
18  * @param[out] bs Bootloader state structure used to save read data.
19  * @return        Return true if the partition table was succesfully loaded and MD5 checksum is valid.
20  */
21 bool bootloader_utility_load_partition_table(bootloader_state_t* bs);
22 
23 /**
24  * @brief Return the index of the selected boot partition.
25  *
26  * This is the preferred boot partition, as determined by the partition table &
27  * any OTA sequence number found in OTA data.
28  * This partition will only be booted if it contains a valid app image, otherwise load_boot_image() will search
29  * for a valid partition using this selection as the starting point.
30  *
31  * @param[in] bs Bootloader state structure.
32  * @return       Returns the index on success, INVALID_INDEX otherwise.
33  */
34 int bootloader_utility_get_selected_boot_partition(const bootloader_state_t *bs);
35 
36 /**
37  * @brief Load the selected partition and start application.
38  *
39  * Start from partition 'start_index', if not bootable then work backwards to FACTORY_INDEX
40  * (ie try any OTA slots in descending order and then the factory partition).
41  * If still nothing, start from 'start_index + 1' and work up to highest numbered OTA partition.
42  * If still nothing, try TEST_APP_INDEX.
43  * Everything this function calls must be located in the iram_loader_seg segment.
44  *
45  * @param[in] bs Bootloader state structure.
46  * @param[in] start_index The index from which the search for images begins.
47  */
48 __attribute__((__noreturn__)) void bootloader_utility_load_boot_image(const bootloader_state_t *bs, int start_index);
49 
50 #ifdef CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP
51 /**
52  * @brief Load that application which was worked before we go to the deep sleep.
53  *
54  * Checks the reboot reason if it is the deep sleep and has a valid partition in the RTC memory
55  * then try to load the application which was worked before we go to the deep sleep.
56  *
57  */
58 void bootloader_utility_load_boot_image_from_deep_sleep(void);
59 #endif
60 
61 /**
62  * @brief Software reset the ESP32
63  *
64  * Bootloader code should call this in the case that it cannot proceed.
65  *
66  * It is not recommended to call this function from an app (if called, the app will abort).
67  */
68 __attribute__((__noreturn__)) void bootloader_reset(void);
69 
70 /**
71  * @brief Do any cleanup before exiting the bootloader, before starting the app or resetting
72  */
73 void bootloader_atexit(void);
74 
75 /**
76  * @brief Converts an array to a printable string.
77  *
78  * This function is useful for printing SHA-256 digest.
79  * \code{c}
80  * // Example of using. image_hash will be printed
81  * #define HASH_LEN 32 // SHA-256 digest length
82  * ...
83  * char hash_print[HASH_LEN * 2 + 1];
84  * hash_print[HASH_LEN * 2] = 0;
85  * bootloader_sha256_hex_to_str(hash_print, image_hash, HASH_LEN);
86  * ESP_LOGI(TAG, %s", hash_print);
87  * \endcode
88 
89  * @param[out] out_str       Output string
90  * @param[in]  in_array_hex  Pointer to input array
91  * @param[in]  len           Length of input array
92  *
93  * @return   ESP_OK: Successful
94  *           ESP_ERR_INVALID_ARG: Error in the passed arguments
95  */
96 esp_err_t bootloader_sha256_hex_to_str(char *out_str, const uint8_t *in_array_hex, size_t len);
97 
98 /**
99  * @brief Debug log contents of a buffer as hexadecimal.
100  *
101  * @note - Only works if component log level is DEBUG or higher.
102  *       - It will print at most 128 bytes from @c buffer.
103  *
104  * @param buffer Buffer to log
105  * @param length Length of buffer in bytes. Maximum length 128 bytes.
106  * @param label Label to print at beginning of log line.
107  */
108 void bootloader_debug_buffer(const void *buffer, size_t length, const char *label);
109 
110 /** @brief Generates the digest of the data between offset & offset+length.
111  *
112  * This function should be used when the size of the data is larger than 3.2MB.
113  * The MMU capacity is 3.2MB (50 pages - 64KB each). This function generates the SHA-256
114  * of the data in chunks of 3.2MB, considering the MMU capacity.
115  *
116  * @param[in]  flash_offset  Offset of the data in flash.
117  * @param[in]  len           Length of data in bytes.
118  * @param[out] digest        Pointer to buffer where the digest is written, if ESP_OK is returned.
119  *
120  * @return ESP_OK if secure boot digest is generated successfully.
121  */
122 esp_err_t bootloader_sha256_flash_contents(uint32_t flash_offset, uint32_t len, uint8_t *digest);
123