1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef _OTA_OPS_H 16 #define _OTA_OPS_H 17 18 #include <stdint.h> 19 #include <stdbool.h> 20 #include <stddef.h> 21 #include "esp_err.h" 22 #include "esp_partition.h" 23 #include "esp_image_format.h" 24 #include "esp_flash_partitions.h" 25 26 #ifdef __cplusplus 27 extern "C" 28 { 29 #endif 30 31 #define OTA_SIZE_UNKNOWN 0xffffffff /*!< Used for esp_ota_begin() if new image size is unknown */ 32 #define OTA_WITH_SEQUENTIAL_WRITES 0xfffffffe /*!< Used for esp_ota_begin() if new image size is unknown and erase can be done in incremental manner (assuming write operation is in continuous sequence) */ 33 34 #define ESP_ERR_OTA_BASE 0x1500 /*!< Base error code for ota_ops api */ 35 #define ESP_ERR_OTA_PARTITION_CONFLICT (ESP_ERR_OTA_BASE + 0x01) /*!< Error if request was to write or erase the current running partition */ 36 #define ESP_ERR_OTA_SELECT_INFO_INVALID (ESP_ERR_OTA_BASE + 0x02) /*!< Error if OTA data partition contains invalid content */ 37 #define ESP_ERR_OTA_VALIDATE_FAILED (ESP_ERR_OTA_BASE + 0x03) /*!< Error if OTA app image is invalid */ 38 #define ESP_ERR_OTA_SMALL_SEC_VER (ESP_ERR_OTA_BASE + 0x04) /*!< Error if the firmware has a secure version less than the running firmware. */ 39 #define ESP_ERR_OTA_ROLLBACK_FAILED (ESP_ERR_OTA_BASE + 0x05) /*!< Error if flash does not have valid firmware in passive partition and hence rollback is not possible */ 40 #define ESP_ERR_OTA_ROLLBACK_INVALID_STATE (ESP_ERR_OTA_BASE + 0x06) /*!< Error if current active firmware is still marked in pending validation state (ESP_OTA_IMG_PENDING_VERIFY), essentially first boot of firmware image post upgrade and hence firmware upgrade is not possible */ 41 42 43 /** 44 * @brief Opaque handle for an application OTA update 45 * 46 * esp_ota_begin() returns a handle which is then used for subsequent 47 * calls to esp_ota_write() and esp_ota_end(). 48 */ 49 typedef uint32_t esp_ota_handle_t; 50 51 /** 52 * @brief Return esp_app_desc structure. This structure includes app version. 53 * 54 * Return description for running app. 55 * @return Pointer to esp_app_desc structure. 56 */ 57 const esp_app_desc_t *esp_ota_get_app_description(void); 58 59 /** 60 * @brief Fill the provided buffer with SHA256 of the ELF file, formatted as hexadecimal, null-terminated. 61 * If the buffer size is not sufficient to fit the entire SHA256 in hex plus a null terminator, 62 * the largest possible number of bytes will be written followed by a null. 63 * @param dst Destination buffer 64 * @param size Size of the buffer 65 * @return Number of bytes written to dst (including null terminator) 66 */ 67 int esp_ota_get_app_elf_sha256(char* dst, size_t size); 68 69 /** 70 * @brief Commence an OTA update writing to the specified partition. 71 72 * The specified partition is erased to the specified image size. 73 * 74 * If image size is not yet known, pass OTA_SIZE_UNKNOWN which will 75 * cause the entire partition to be erased. 76 * 77 * On success, this function allocates memory that remains in use 78 * until esp_ota_end() is called with the returned handle. 79 * 80 * Note: If the rollback option is enabled and the running application has the ESP_OTA_IMG_PENDING_VERIFY state then 81 * it will lead to the ESP_ERR_OTA_ROLLBACK_INVALID_STATE error. Confirm the running app before to run download a new app, 82 * use esp_ota_mark_app_valid_cancel_rollback() function for it (this should be done as early as possible when you first download a new application). 83 * 84 * @param partition Pointer to info for partition which will receive the OTA update. Required. 85 * @param image_size Size of new OTA app image. Partition will be erased in order to receive this size of image. If 0 or OTA_SIZE_UNKNOWN, the entire partition is erased. 86 * @param out_handle On success, returns a handle which should be used for subsequent esp_ota_write() and esp_ota_end() calls. 87 88 * @return 89 * - ESP_OK: OTA operation commenced successfully. 90 * - ESP_ERR_INVALID_ARG: partition or out_handle arguments were NULL, or partition doesn't point to an OTA app partition. 91 * - ESP_ERR_NO_MEM: Cannot allocate memory for OTA operation. 92 * - ESP_ERR_OTA_PARTITION_CONFLICT: Partition holds the currently running firmware, cannot update in place. 93 * - ESP_ERR_NOT_FOUND: Partition argument not found in partition table. 94 * - ESP_ERR_OTA_SELECT_INFO_INVALID: The OTA data partition contains invalid data. 95 * - ESP_ERR_INVALID_SIZE: Partition doesn't fit in configured flash size. 96 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. 97 * - ESP_ERR_OTA_ROLLBACK_INVALID_STATE: If the running app has not confirmed state. Before performing an update, the application must be valid. 98 */ 99 esp_err_t esp_ota_begin(const esp_partition_t* partition, size_t image_size, esp_ota_handle_t* out_handle); 100 101 /** 102 * @brief Write OTA update data to partition 103 * 104 * This function can be called multiple times as 105 * data is received during the OTA operation. Data is written 106 * sequentially to the partition. 107 * 108 * @param handle Handle obtained from esp_ota_begin 109 * @param data Data buffer to write 110 * @param size Size of data buffer in bytes. 111 * 112 * @return 113 * - ESP_OK: Data was written to flash successfully. 114 * - ESP_ERR_INVALID_ARG: handle is invalid. 115 * - ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte. 116 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. 117 * - ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents 118 */ 119 esp_err_t esp_ota_write(esp_ota_handle_t handle, const void* data, size_t size); 120 121 /** 122 * @brief Write OTA update data to partition 123 * 124 * This function can write data in non contiguous manner. 125 * If flash encryption is enabled, data should be 16 byte aligned. 126 * 127 * @param handle Handle obtained from esp_ota_begin 128 * @param data Data buffer to write 129 * @param size Size of data buffer in bytes 130 * @param offset Offset in flash partition 131 * 132 * @note While performing OTA, if the packets arrive out of order, esp_ota_write_with_offset() can be used to write data in non contiguous manner. 133 * Use of esp_ota_write_with_offset() in combination with esp_ota_write() is not recommended. 134 * 135 * @return 136 * - ESP_OK: Data was written to flash successfully. 137 * - ESP_ERR_INVALID_ARG: handle is invalid. 138 * - ESP_ERR_OTA_VALIDATE_FAILED: First byte of image contains invalid app image magic byte. 139 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash write failed. 140 * - ESP_ERR_OTA_SELECT_INFO_INVALID: OTA data partition has invalid contents 141 */ 142 esp_err_t esp_ota_write_with_offset(esp_ota_handle_t handle, const void *data, size_t size, uint32_t offset); 143 144 /** 145 * @brief Finish OTA update and validate newly written app image. 146 * 147 * @param handle Handle obtained from esp_ota_begin(). 148 * 149 * @note After calling esp_ota_end(), the handle is no longer valid and any memory associated with it is freed (regardless of result). 150 * 151 * @return 152 * - ESP_OK: Newly written OTA app image is valid. 153 * - ESP_ERR_NOT_FOUND: OTA handle was not found. 154 * - ESP_ERR_INVALID_ARG: Handle was never written to. 155 * - ESP_ERR_OTA_VALIDATE_FAILED: OTA image is invalid (either not a valid app image, or - if secure boot is enabled - signature failed to verify.) 156 * - ESP_ERR_INVALID_STATE: If flash encryption is enabled, this result indicates an internal error writing the final encrypted bytes to flash. 157 */ 158 esp_err_t esp_ota_end(esp_ota_handle_t handle); 159 160 /** 161 * @brief Abort OTA update, free the handle and memory associated with it. 162 * 163 * @param handle obtained from esp_ota_begin(). 164 * 165 * @return 166 * - ESP_OK: Handle and its associated memory is freed successfully. 167 * - ESP_ERR_NOT_FOUND: OTA handle was not found. 168 */ 169 esp_err_t esp_ota_abort(esp_ota_handle_t handle); 170 171 172 /** 173 * @brief Configure OTA data for a new boot partition 174 * 175 * @note If this function returns ESP_OK, calling esp_restart() will boot the newly configured app partition. 176 * 177 * @param partition Pointer to info for partition containing app image to boot. 178 * 179 * @return 180 * - ESP_OK: OTA data updated, next reboot will use specified partition. 181 * - ESP_ERR_INVALID_ARG: partition argument was NULL or didn't point to a valid OTA partition of type "app". 182 * - ESP_ERR_OTA_VALIDATE_FAILED: Partition contained invalid app image. Also returned if secure boot is enabled and signature validation failed. 183 * - ESP_ERR_NOT_FOUND: OTA data partition not found. 184 * - ESP_ERR_FLASH_OP_TIMEOUT or ESP_ERR_FLASH_OP_FAIL: Flash erase or write failed. 185 */ 186 esp_err_t esp_ota_set_boot_partition(const esp_partition_t* partition); 187 188 /** 189 * @brief Get partition info of currently configured boot app 190 * 191 * If esp_ota_set_boot_partition() has been called, the partition which was set by that function will be returned. 192 * 193 * If esp_ota_set_boot_partition() has not been called, the result is usually the same as esp_ota_get_running_partition(). 194 * The two results are not equal if the configured boot partition does not contain a valid app (meaning that the running partition 195 * will be an app that the bootloader chose via fallback). 196 * 197 * If the OTA data partition is not present or not valid then the result is the first app partition found in the 198 * partition table. In priority order, this means: the factory app, the first OTA app slot, or the test app partition. 199 * 200 * Note that there is no guarantee the returned partition is a valid app. Use esp_image_verify(ESP_IMAGE_VERIFY, ...) to verify if the 201 * returned partition contains a bootable image. 202 * 203 * @return Pointer to info for partition structure, or NULL if partition table is invalid or a flash read operation failed. Any returned pointer is valid for the lifetime of the application. 204 */ 205 const esp_partition_t* esp_ota_get_boot_partition(void); 206 207 208 /** 209 * @brief Get partition info of currently running app 210 * 211 * This function is different to esp_ota_get_boot_partition() in that 212 * it ignores any change of selected boot partition caused by 213 * esp_ota_set_boot_partition(). Only the app whose code is currently 214 * running will have its partition information returned. 215 * 216 * The partition returned by this function may also differ from esp_ota_get_boot_partition() if the configured boot 217 * partition is somehow invalid, and the bootloader fell back to a different app partition at boot. 218 * 219 * @return Pointer to info for partition structure, or NULL if no partition is found or flash read operation failed. Returned pointer is valid for the lifetime of the application. 220 */ 221 const esp_partition_t* esp_ota_get_running_partition(void); 222 223 224 /** 225 * @brief Return the next OTA app partition which should be written with a new firmware. 226 * 227 * Call this function to find an OTA app partition which can be passed to esp_ota_begin(). 228 * 229 * Finds next partition round-robin, starting from the current running partition. 230 * 231 * @param start_from If set, treat this partition info as describing the current running partition. Can be NULL, in which case esp_ota_get_running_partition() is used to find the currently running partition. The result of this function is never the same as this argument. 232 * 233 * @return Pointer to info for partition which should be updated next. NULL result indicates invalid OTA data partition, or that no eligible OTA app slot partition was found. 234 * 235 */ 236 const esp_partition_t* esp_ota_get_next_update_partition(const esp_partition_t *start_from); 237 238 /** 239 * @brief Returns esp_app_desc structure for app partition. This structure includes app version. 240 * 241 * Returns a description for the requested app partition. 242 * @param[in] partition Pointer to app partition. (only app partition) 243 * @param[out] app_desc Structure of info about app. 244 * @return 245 * - ESP_OK Successful. 246 * - ESP_ERR_NOT_FOUND app_desc structure is not found. Magic word is incorrect. 247 * - ESP_ERR_NOT_SUPPORTED Partition is not application. 248 * - ESP_ERR_INVALID_ARG Arguments is NULL or if partition's offset exceeds partition size. 249 * - ESP_ERR_INVALID_SIZE Read would go out of bounds of the partition. 250 * - or one of error codes from lower-level flash driver. 251 */ 252 esp_err_t esp_ota_get_partition_description(const esp_partition_t *partition, esp_app_desc_t *app_desc); 253 254 /** 255 * @brief This function is called to indicate that the running app is working well. 256 * 257 * @return 258 * - ESP_OK: if successful. 259 */ 260 esp_err_t esp_ota_mark_app_valid_cancel_rollback(void); 261 262 /** 263 * @brief This function is called to roll back to the previously workable app with reboot. 264 * 265 * If rollback is successful then device will reset else API will return with error code. 266 * Checks applications on a flash drive that can be booted in case of rollback. 267 * If the flash does not have at least one app (except the running app) then rollback is not possible. 268 * @return 269 * - ESP_FAIL: if not successful. 270 * - ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have any apps. 271 */ 272 esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void); 273 274 /** 275 * @brief Returns last partition with invalid state (ESP_OTA_IMG_INVALID or ESP_OTA_IMG_ABORTED). 276 * 277 * @return partition. 278 */ 279 const esp_partition_t* esp_ota_get_last_invalid_partition(void); 280 281 /** 282 * @brief Returns state for given partition. 283 * 284 * @param[in] partition Pointer to partition. 285 * @param[out] ota_state state of partition (if this partition has a record in otadata). 286 * @return 287 * - ESP_OK: Successful. 288 * - ESP_ERR_INVALID_ARG: partition or ota_state arguments were NULL. 289 * - ESP_ERR_NOT_SUPPORTED: partition is not ota. 290 * - ESP_ERR_NOT_FOUND: Partition table does not have otadata or state was not found for given partition. 291 */ 292 esp_err_t esp_ota_get_state_partition(const esp_partition_t *partition, esp_ota_img_states_t *ota_state); 293 294 /** 295 * @brief Erase previous boot app partition and corresponding otadata select for this partition. 296 * 297 * When current app is marked to as valid then you can erase previous app partition. 298 * @return 299 * - ESP_OK: Successful, otherwise ESP_ERR. 300 */ 301 esp_err_t esp_ota_erase_last_boot_app_partition(void); 302 303 /** 304 * @brief Checks applications on the slots which can be booted in case of rollback. 305 * 306 * These applications should be valid (marked in otadata as not UNDEFINED, INVALID or ABORTED and crc is good) and be able booted, 307 * and secure_version of app >= secure_version of efuse (if anti-rollback is enabled). 308 * 309 * @return 310 * - True: Returns true if the slots have at least one app (except the running app). 311 * - False: The rollback is not possible. 312 */ 313 bool esp_ota_check_rollback_is_possible(void); 314 315 #if SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS > 1 && (CONFIG_SECURE_BOOT_V2_ENABLED || __DOXYGEN__) 316 317 /** 318 * Secure Boot V2 public key indexes. 319 */ 320 typedef enum { 321 SECURE_BOOT_PUBLIC_KEY_INDEX_0, /*!< Points to the 0th index of the Secure Boot v2 public key */ 322 SECURE_BOOT_PUBLIC_KEY_INDEX_1, /*!< Points to the 1st index of the Secure Boot v2 public key */ 323 SECURE_BOOT_PUBLIC_KEY_INDEX_2 /*!< Points to the 2nd index of the Secure Boot v2 public key */ 324 } esp_ota_secure_boot_public_key_index_t; 325 326 /** 327 * @brief Revokes the old signature digest. To be called in the application after the rollback logic. 328 * 329 * Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1). 330 * When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N. 331 * After successfully booting the OTA app should call this function to revoke Key #N-1. 332 * 333 * @param index - The index of the signature block to be revoked 334 * 335 * @return 336 * - ESP_OK: If revocation is successful. 337 * - ESP_ERR_INVALID_ARG: If the index of the public key to be revoked is incorrect. 338 * - ESP_FAIL: If secure boot v2 has not been enabled. 339 */ 340 esp_err_t esp_ota_revoke_secure_boot_public_key(esp_ota_secure_boot_public_key_index_t index); 341 #endif /* SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS > 1 */ 342 343 #ifdef __cplusplus 344 } 345 #endif 346 347 #endif /* OTA_OPS_H */ 348
