Merge branch 'feature/ota_buffer_cap_config' into 'master'

feat(esp_https_ota): Add config to configure memory capability for OTA buffer

Closes IDF-8836

See merge request espressif/esp-idf!27927

components/esp_https_ota/include/esp_https_ota.h

@@ -59,6 +59,7 @@ typedef struct {
     bool bulk_flash_erase;                         /*!< Erase entire flash partition during initialization. By default flash partition is erased during write operation and in chunk of 4K sector size */
     bool partial_http_download;                    /*!< Enable Firmware image to be downloaded over multiple HTTP requests */
     int max_http_request_size;                     /*!< Maximum request size for partial HTTP download */
+    uint32_t buffer_caps;                          /*!< The memory capability to use when allocating the buffer for OTA update. Default capability is MALLOC_CAP_DEFAULT */
 #if CONFIG_ESP_HTTPS_OTA_DECRYPT_CB
     decrypt_cb_t decrypt_cb;                       /*!< Callback for external decryption layer */
     void *decrypt_user_ctx;                        /*!< User context for external decryption layer */
@@ -223,7 +224,7 @@ esp_err_t esp_https_ota_get_img_desc(esp_https_ota_handle_t https_ota_handle, es
 /**
 * @brief  This function returns OTA image data read so far.
 *
-* @note   This API should be called only if `esp_https_ota_perform()` has been called atleast once or
+* @note   This API should be called only if `esp_https_ota_perform()` has been called at least once or
 *         if `esp_https_ota_get_img_desc` has been called before.
 *
 * @param[in]   https_ota_handle   pointer to esp_https_ota_handle_t structure

components/esp_https_ota/src/esp_https_ota.c

@@ -374,7 +374,11 @@ esp_err_t esp_https_ota_begin(const esp_https_ota_config_t *ota_config, esp_http
         https_ota_handle->update_partition->subtype, https_ota_handle->update_partition->address);
 
     const int alloc_size = MAX(ota_config->http_config->buffer_size, DEFAULT_OTA_BUF_SIZE);
-    https_ota_handle->ota_upgrade_buf = (char *)malloc(alloc_size);
+    if (ota_config->buffer_caps != 0) {
+        https_ota_handle->ota_upgrade_buf = (char *)heap_caps_malloc(alloc_size, ota_config->buffer_caps);
+    } else {
+        https_ota_handle->ota_upgrade_buf = (char *)malloc(alloc_size);
+    }
     if (!https_ota_handle->ota_upgrade_buf) {
         ESP_LOGE(TAG, "Couldn't allocate memory to upgrade data buffer");
         err = ESP_ERR_NO_MEM;
@@ -499,7 +503,7 @@ esp_err_t esp_https_ota_perform(esp_https_ota_handle_t https_ota_handle)
 
     esp_err_t err;
     int data_read;
-    const int erase_size = handle->bulk_flash_erase ? OTA_SIZE_UNKNOWN : OTA_WITH_SEQUENTIAL_WRITES;
+    const int erase_size = handle->bulk_flash_erase ? (handle->image_length > 0 ? handle->image_length : OTA_SIZE_UNKNOWN) : OTA_WITH_SEQUENTIAL_WRITES;
     switch (handle->state) {
         case ESP_HTTPS_OTA_BEGIN:
             err = esp_ota_begin(handle->update_partition, erase_size, &handle->update_handle);

docs/en/api-reference/system/ota.rst

@@ -197,6 +197,21 @@ The verification of signed OTA updates can be performed even without enabling ha
 
   For more information refer to :ref:`signed-app-verify`
 
+Tuning OTA Performance
+----------------------
+
+- Erasing the update partition at once instead of sequential erasing (default mechanism) while write operation might help in reducing the overall time taken for firmware upgrade. To enable this, set :cpp:member:`esp_https_ota_config_t::bulk_flash_erase` to true in :cpp:type:`esp_https_ota_config_t` structure. If the partition to be erased is too large, task watchdog could be triggered. It is advised to increase the watchdog timeout in such cases.
+
+  .. code-block:: c
+
+      esp_https_ota_config_t ota_config = {
+          .bulk_flash_erase = true,
+      }
+
+- Tuning the :cpp:member:`esp_https_ota_config_t::http_config::buffer_size` can also help in improving the OTA performance.
+- :cpp:type:`esp_https_ota_config_t` has a member :cpp:member:`esp_https_ota_config_t::buffer_caps` which can be used to specify the memory type to use when allocating memory to the OTA buffer. Configuring this value to MALLOC_CAP_INTERNAL might help in improving the OTA performance when SPIRAM is enabled.
+- For optimizing network performance, please refer to **Improving Network Speed** section in the :doc:`/api-guides/performance/speed` for more details.
+
 
 OTA Tool ``otatool.py``
 -----------------------

docs/en/migration-guides/release-5.x/5.3/index.rst

@@ -9,6 +9,7 @@ Migration from 5.2 to 5.3
     bluetooth-low-energy
     gcc
     peripherals
+    protocols
     security
     storage
     system

docs/en/migration-guides/release-5.x/5.3/protocols.rst

@@ -0,0 +1,12 @@
+Protocols
+=========
+
+:link_to_translation:`zh_CN:[中文]`
+
+ESP HTTPS OTA
+--------------
+
+Breaking Changes (Summary)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- If the image length is found in the HTTP header and :cpp:member:`esp_https_ota_config_t::bulk_flash_erase` is set to true, then instead of erasing the entire flash, the erase operation will be performed to accommodate the size of the image length.

docs/zh_CN/migration-guides/release-5.x/5.3/index.rst

@@ -9,6 +9,7 @@
     bluetooth-low-energy
     gcc
     peripherals
+    protocols
     security
     storage
     system

docs/zh_CN/migration-guides/release-5.x/5.3/protocols.rst

@@ -0,0 +1 @@
+.. include:: ../../../../en/migration-guides/release-5.x/5.3/protocols.rst