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