1 /* 2 * SPDX-FileCopyrightText: 2018-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 #include "esp_flash_partitions.h" 9 #include "esp_image_format.h" 10 #include "esp_app_format.h" 11 // [refactor-todo]: we shouldn't expose ROM header files in a public API header, remove them in v5.0 12 // Tracked in IDF-1968 13 #if CONFIG_IDF_TARGET_ESP32 14 #include "esp32/rom/rtc.h" 15 #elif CONFIG_IDF_TARGET_ESP32S2 16 #include "esp32s2/rom/rtc.h" 17 #elif CONFIG_IDF_TARGET_ESP32S3 18 #include "esp32s3/rom/rtc.h" 19 #elif CONFIG_IDF_TARGET_ESP32C3 20 #include "esp32c3/rom/rtc.h" 21 #elif CONFIG_IDF_TARGET_ESP32H2 22 #include "esp32h2/rom/rtc.h" 23 #endif 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /// Type of hold a GPIO in low state 30 typedef enum { 31 GPIO_LONG_HOLD = 1, /*!< The long hold GPIO */ 32 GPIO_SHORT_HOLD = -1, /*!< The short hold GPIO */ 33 GPIO_NOT_HOLD = 0 /*!< If the GPIO input is not low */ 34 } esp_comm_gpio_hold_t; 35 36 typedef enum { 37 ESP_IMAGE_BOOTLOADER, 38 ESP_IMAGE_APPLICATION 39 } esp_image_type; 40 41 /** 42 * @brief Calculate crc for the OTA data select. 43 * 44 * @param[in] s The OTA data select. 45 * @return Returns crc value. 46 */ 47 uint32_t bootloader_common_ota_select_crc(const esp_ota_select_entry_t *s); 48 49 /** 50 * @brief Verifies the validity of the OTA data select 51 * 52 * @param[in] s The OTA data select. 53 * @return Returns true on valid, false otherwise. 54 */ 55 bool bootloader_common_ota_select_valid(const esp_ota_select_entry_t *s); 56 57 /** 58 * @brief Returns true if OTADATA is not marked as bootable partition. 59 * 60 * @param[in] s The OTA data select. 61 * @return Returns true if OTADATA invalid, false otherwise. 62 */ 63 bool bootloader_common_ota_select_invalid(const esp_ota_select_entry_t *s); 64 65 /** 66 * @brief Check if a GPIO input is held low for a long period, short period, or not 67 * at all. 68 * 69 * This function will configure the specified GPIO as an input with internal pull-up enabled. 70 * 71 * If the GPIO input is held low continuously for delay_sec period then it is a long hold. 72 * If the GPIO input is held low for less period then it is a short hold. 73 * 74 * @param[in] num_pin Number of the GPIO input. 75 * @param[in] delay_sec Input must be driven low for at least this long, continuously. 76 * @return esp_comm_gpio_hold_t Type of low level hold detected, if any. 77 */ 78 esp_comm_gpio_hold_t bootloader_common_check_long_hold_gpio(uint32_t num_pin, uint32_t delay_sec); 79 80 /** 81 * @brief Check if a GPIO input is held low or high for a long period, short period, or not 82 * at all. 83 * 84 * This function will configure the specified GPIO as an input with internal pull-up enabled. 85 * 86 * If the GPIO input is held at 'level' continuously for delay_sec period then it is a long hold. 87 * If the GPIO input is held at 'level' for less period then it is a short hold. 88 * 89 * @param[in] num_pin Number of the GPIO input. 90 * @param[in] delay_sec Input must be driven to 'level' for at least this long, continuously. 91 * @param[in] level Input pin level to trigger on hold 92 * @return esp_comm_gpio_hold_t Type of hold detected, if any. 93 */ 94 esp_comm_gpio_hold_t bootloader_common_check_long_hold_gpio_level(uint32_t num_pin, uint32_t delay_sec, bool level); 95 96 97 /** 98 * @brief Erase the partition data that is specified in the transferred list. 99 * 100 * @param[in] list_erase String containing a list of cleared partitions. Like this "nvs, phy". The string must be null-terminal. 101 * @param[in] ota_data_erase If true then the OTA data partition will be cleared (if there is it in partition table). 102 * @return Returns true on success, false otherwise. 103 */ 104 bool bootloader_common_erase_part_type_data(const char *list_erase, bool ota_data_erase); 105 106 /** 107 * @brief Determines if the list contains the label 108 * 109 * @param[in] list A string of names delimited by commas or spaces. Like this "nvs, phy, data". The string must be null-terminated. 110 * @param[in] label The substring that will be searched in the list. 111 * @return Returns true if the list contains the label, false otherwise. 112 */ 113 bool bootloader_common_label_search(const char *list, char *label); 114 115 /** 116 * @brief Configure default SPI pin modes and drive strengths 117 * 118 * @param drv GPIO drive level (determined by clock frequency) 119 */ 120 void bootloader_configure_spi_pins(int drv); 121 122 /** 123 * @brief Get flash CS IO 124 * 125 * Can be determined by eFuse values, or the default value 126 * 127 * @return Flash CS IO 128 */ 129 uint8_t bootloader_flash_get_cs_io(void); 130 131 /** 132 * @brief Calculates a sha-256 for a given partition or returns a appended digest. 133 * 134 * This function can be used to return the SHA-256 digest of application, bootloader and data partitions. 135 * For apps with SHA-256 appended to the app image, the result is the appended SHA-256 value for the app image content. 136 * The hash is verified before returning, if app content is invalid then the function returns ESP_ERR_IMAGE_INVALID. 137 * For apps without SHA-256 appended to the image, the result is the SHA-256 of all bytes in the app image. 138 * For other partition types, the result is the SHA-256 of the entire partition. 139 * 140 * @param[in] address Address of partition. 141 * @param[in] size Size of partition. 142 * @param[in] type Type of partition. For applications the type is 0, otherwise type is data. 143 * @param[out] out_sha_256 Returned SHA-256 digest for a given partition. 144 * 145 * @return 146 * - ESP_OK: In case of successful operation. 147 * - ESP_ERR_INVALID_ARG: The size was 0 or the sha_256 was NULL. 148 * - ESP_ERR_NO_MEM: Cannot allocate memory for sha256 operation. 149 * - ESP_ERR_IMAGE_INVALID: App partition doesn't contain a valid app image. 150 * - ESP_FAIL: An allocation error occurred. 151 */ 152 esp_err_t bootloader_common_get_sha256_of_partition(uint32_t address, uint32_t size, int type, uint8_t *out_sha_256); 153 154 /** 155 * @brief Returns the number of active otadata. 156 * 157 * @param[in] two_otadata Pointer on array from two otadata structures. 158 * 159 * @return The number of active otadata (0 or 1). 160 * - -1: If it does not have active otadata. 161 */ 162 int bootloader_common_get_active_otadata(esp_ota_select_entry_t *two_otadata); 163 164 /** 165 * @brief Returns the number of active otadata. 166 * 167 * @param[in] two_otadata Pointer on array from two otadata structures. 168 * @param[in] valid_two_otadata Pointer on array from two bools. True means select. 169 * @param[in] max True - will select the maximum ota_seq number, otherwise the minimum. 170 * 171 * @return The number of active otadata (0 or 1). 172 * - -1: If it does not have active otadata. 173 */ 174 int bootloader_common_select_otadata(const esp_ota_select_entry_t *two_otadata, bool *valid_two_otadata, bool max); 175 176 /** 177 * @brief Returns esp_app_desc structure for app partition. This structure includes app version. 178 * 179 * Returns a description for the requested app partition. 180 * @param[in] partition App partition description. 181 * @param[out] app_desc Structure of info about app. 182 * @return 183 * - ESP_OK: Successful. 184 * - ESP_ERR_INVALID_ARG: The arguments passed are not valid. 185 * - ESP_ERR_NOT_FOUND: app_desc structure is not found. Magic word is incorrect. 186 * - ESP_FAIL: mapping is fail. 187 */ 188 esp_err_t bootloader_common_get_partition_description(const esp_partition_pos_t *partition, esp_app_desc_t *app_desc); 189 190 /** 191 * @brief Get chip revision 192 * 193 * @return Chip revision number 194 */ 195 uint8_t bootloader_common_get_chip_revision(void); 196 197 /** 198 * @brief Get chip package 199 * 200 * @return Chip package number 201 */ 202 uint32_t bootloader_common_get_chip_ver_pkg(void); 203 204 /** 205 * @brief Query reset reason 206 * 207 * @param cpu_no CPU number 208 * @return reset reason enumeration 209 */ 210 RESET_REASON bootloader_common_get_reset_reason(int cpu_no); 211 212 /** 213 * @brief Check if the image (bootloader and application) has valid chip ID and revision 214 * 215 * @param[in] img_hdr: image header 216 * @param[in] type: image type, bootloader or application 217 * @return 218 * - ESP_OK: image and chip are matched well 219 * - ESP_FAIL: image doesn't match to the chip 220 */ 221 esp_err_t bootloader_common_check_chip_validity(const esp_image_header_t* img_hdr, esp_image_type type); 222 223 /** 224 * @brief Configure VDDSDIO, call this API to rise VDDSDIO to 1.9V when VDDSDIO regulator is enabled as 1.8V mode. 225 */ 226 void bootloader_common_vddsdio_configure(void); 227 228 #if defined( CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP ) || defined( CONFIG_BOOTLOADER_CUSTOM_RESERVE_RTC ) 229 /** 230 * @brief Returns partition from rtc_retain_mem 231 * 232 * Uses to get the partition of application which was worked before to go to the deep sleep. 233 * This partition was stored in rtc_retain_mem. 234 * Note: This function operates the RTC FAST memory which available only for PRO_CPU. 235 * Make sure that this function is used only PRO_CPU. 236 * 237 * @return partition: If rtc_retain_mem is valid. 238 * - NULL: If it is not valid. 239 */ 240 esp_partition_pos_t* bootloader_common_get_rtc_retain_mem_partition(void); 241 242 /** 243 * @brief Update the partition and reboot_counter in rtc_retain_mem. 244 * 245 * This function saves the partition of application for fast booting from the deep sleep. 246 * An algorithm uses this partition to avoid reading the otadata and does not validate an image. 247 * Note: This function operates the RTC FAST memory which available only for PRO_CPU. 248 * Make sure that this function is used only PRO_CPU. 249 * 250 * @param[in] partition App partition description. Can be NULL, in this case rtc_retain_mem.partition is not updated. 251 * @param[in] reboot_counter If true then update reboot_counter. 252 * 253 */ 254 void bootloader_common_update_rtc_retain_mem(esp_partition_pos_t* partition, bool reboot_counter); 255 256 /** 257 * @brief Reset entire rtc_retain_mem. 258 * 259 * Note: This function operates the RTC FAST memory which available only for PRO_CPU. 260 * Make sure that this function is used only PRO_CPU. 261 */ 262 void bootloader_common_reset_rtc_retain_mem(void); 263 264 /** 265 * @brief Returns reboot_counter from rtc_retain_mem 266 * 267 * The reboot_counter counts the number of reboots. Reset only when power is off. 268 * The very first launch of the application will be from 1. 269 * Overflow is not possible, it will stop at the value UINT16_MAX. 270 * Note: This function operates the RTC FAST memory which available only for PRO_CPU. 271 * Make sure that this function is used only PRO_CPU. 272 * 273 * @return reboot_counter: 1..65535 274 * - 0: If rtc_retain_mem is not valid. 275 */ 276 uint16_t bootloader_common_get_rtc_retain_mem_reboot_counter(void); 277 278 /** 279 * @brief Returns rtc_retain_mem 280 * 281 * Note: This function operates the RTC FAST memory which available only for PRO_CPU. 282 * Make sure that this function is used only PRO_CPU. 283 * 284 * @return rtc_retain_mem 285 */ 286 rtc_retain_mem_t* bootloader_common_get_rtc_retain_mem(void); 287 288 #endif 289 290 #ifdef __cplusplus 291 } 292 #endif 293
