feat(app_update): esp_ota_mark_app_invalid_rollback() without reboot (IDFGH-14234)

components/app_update/esp_ota_ops.c

@@ -857,8 +857,7 @@ static esp_err_t esp_ota_current_ota_is_workable(bool valid)
             if (err != ESP_OK) {
                 return err;
             }
-            ESP_LOGI(TAG, "Rollback to previously worked partition. Restart.");
-            esp_restart();
+            ESP_LOGI(TAG, "Rollback to previously worked partition.");
         }
     } else {
         ESP_LOGE(TAG, "Running firmware is factory");
@@ -872,11 +871,20 @@ esp_err_t esp_ota_mark_app_valid_cancel_rollback(void)
     return esp_ota_current_ota_is_workable(true);
 }
 
-esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void)
+esp_err_t esp_ota_mark_app_invalid_rollback(void)
 {
     return esp_ota_current_ota_is_workable(false);
 }
 
+esp_err_t esp_ota_mark_app_invalid_rollback_and_reboot(void)
+{
+    esp_err_t ret = esp_ota_mark_app_invalid_rollback();
+    if (ret == ESP_OK) {
+        esp_restart();
+    }
+    return ret;
+}
+
 static bool check_invalid_otadata (const esp_ota_select_entry_t *s) {
     return s->ota_seq != UINT32_MAX &&
            s->crc == bootloader_common_ota_select_crc(s) &&

components/app_update/include/esp_ota_ops.h

@@ -319,12 +319,23 @@ uint8_t esp_ota_get_app_partition_count(void);
 esp_err_t esp_ota_mark_app_valid_cancel_rollback(void);
 
 /**
- * @brief This function is called to roll back to the previously workable app with reboot.
+ * @brief This function is called to roll back to the previously workable app without reboot.
  *
- * If rollback is successful then device will reset else API will return with error code.
  * Checks applications on a flash drive that can be booted in case of rollback.
  * If the flash does not have at least one app (except the running app) then rollback is not possible.
  * @return
+ *  - ESP_OK: if successful.
+ *  - ESP_FAIL: if not successful.
+ *  - ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have any apps.
+ */
+esp_err_t esp_ota_mark_app_invalid_rollback(void);
+
+/**
+ * @brief This function is called to roll back to the previously workable app with reboot.
+ *
+ * Equivalent to calling esp_ota_mark_app_invalid_rollback(), and if successful followed by esp_restart().
+ *
+ * @return
  *  - ESP_FAIL: if not successful.
  *  - ESP_ERR_OTA_ROLLBACK_FAILED: The rollback is not possible due to flash does not have any apps.
  */

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

@@ -140,7 +140,7 @@ A brief description of where the states are set:
 * ``ESP_OTA_IMG_VALID`` state is set by :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function.
 * ``ESP_OTA_IMG_UNDEFINED`` state is set by :cpp:func:`esp_ota_set_boot_partition` function if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is not enabled.
 * ``ESP_OTA_IMG_NEW`` state is set by :cpp:func:`esp_ota_set_boot_partition` function if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled.
-* ``ESP_OTA_IMG_INVALID`` state is set by  :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function.
+* ``ESP_OTA_IMG_INVALID`` state is set by  :cpp:func:`esp_ota_mark_app_invalid_rollback` function.
 * ``ESP_OTA_IMG_ABORTED`` state is set if there was no confirmation of the application operability and occurs reboots (if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled).
 * ``ESP_OTA_IMG_PENDING_VERIFY`` state is set in a bootloader if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled and selected app has ``ESP_OTA_IMG_NEW`` state.
 
@@ -165,7 +165,7 @@ A Typical Anti-rollback Scheme Is
 - To make it bootable, run the function :cpp:func:`esp_ota_set_boot_partition`. If the security version of the new application is smaller than the version in the chip, the new application will be erased. Update to new firmware is not possible.
 - Reboot.
 - In the bootloader, an application with a security version greater than or equal to the version in the chip will be selected. If otadata is in the initial state, and one firmware was loaded via a serial channel, whose secure version is higher than the chip, then the secure version of efuse will be immediately updated in the bootloader.
-- New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function to mark the running application with the ``ESP_OTA_IMG_VALID`` state and update the secure version on chip. Note that if was called :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function a rollback may not happen as the device may not have any bootable apps. It will then return ``ESP_ERR_OTA_ROLLBACK_FAILED`` error and stay in the ``ESP_OTA_IMG_PENDING_VERIFY`` state.
+- New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function to mark the running application with the ``ESP_OTA_IMG_VALID`` state and update the secure version on chip. Note that if the :cpp:func:`esp_ota_mark_app_invalid_rollback` function is called a rollback may not happen as the device may not have any bootable apps. It will then return ``ESP_ERR_OTA_ROLLBACK_FAILED`` error and stay in the ``ESP_OTA_IMG_PENDING_VERIFY`` state.
 - The next update of app is possible if a running app is in the ``ESP_OTA_IMG_VALID`` state.
 
 Recommendation: