Merge branch 'fix/esp_partition_api_with_error_reporting' into 'master'

feat(esp_partition): add error-returning variants for partition find APIs

Closes IDFGH-7740

See merge request espressif/esp-idf!42089

Author: RathiSonika

components/esp_partition/host_test/partition_api_test/main/partition_api_test.c

@@ -88,6 +88,62 @@ TEST(partition_api, test_partition_find_first)
     TEST_ASSERT_NOT_NULL(partition_data);
 }
 
+TEST(partition_api, test_partition_find_err)
+{
+    esp_partition_iterator_t iter = NULL;
+    esp_err_t err = esp_partition_find_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage", &iter);
+    TEST_ESP_OK(err);
+    TEST_ASSERT_NOT_NULL(iter);
+
+    const esp_partition_t *part = esp_partition_get(iter);
+    TEST_ASSERT_NOT_NULL(part);
+
+    esp_partition_iterator_release(iter);
+
+    // Test error cases
+    err = esp_partition_find_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "nonexistent", &iter);
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, err);
+    TEST_ASSERT_NULL(iter);  // But iterator should be NULL
+
+    // Test invalid argument
+    err = esp_partition_find_err(ESP_PARTITION_TYPE_ANY, ESP_PARTITION_SUBTYPE_DATA_NVS, NULL, &iter);
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, err);
+    TEST_ASSERT_NULL(iter);  // But iterator should be NULL
+
+    // Test NULL pointer
+    err = esp_partition_find_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage", NULL);
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, err);
+    TEST_ASSERT_NULL(iter);  // But iterator should be NULL
+}
+
+TEST(partition_api, test_partition_find_first_err)
+{
+    const esp_partition_t *partition_app = NULL;
+    esp_err_t err = esp_partition_find_first_err(ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_ANY, NULL, &partition_app);
+    TEST_ESP_OK(err);
+    TEST_ASSERT_NOT_NULL(partition_app);
+
+    const esp_partition_t *partition_data = NULL;
+    err = esp_partition_find_first_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage", &partition_data);
+    TEST_ESP_OK(err);
+    TEST_ASSERT_NOT_NULL(partition_data);
+
+    // Test partition not found
+    const esp_partition_t *partition_nonexistent = NULL;
+    err = esp_partition_find_first_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "nonexistent", &partition_nonexistent);
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, err);
+    TEST_ASSERT_NULL(partition_nonexistent);  // But partition should be NULL
+
+    // Test error cases
+    err = esp_partition_find_first_err(ESP_PARTITION_TYPE_ANY, ESP_PARTITION_SUBTYPE_DATA_NVS, NULL, &partition_data);
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, err);
+    TEST_ASSERT_NULL(partition_data);  // But partition should be NULL
+
+    // Test NULL pointer
+    err = esp_partition_find_first_err(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage", NULL);
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, err);
+}
+
 TEST(partition_api, test_partition_ops)
 {
     const esp_partition_t *partition_data = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage");
@@ -122,6 +178,59 @@ TEST(partition_api, test_partition_ops)
     TEST_ASSERT_NOT_NULL(verified_partition);
 }
 
+TEST(partition_api, test_partition_verify_err)
+{
+    // Get a valid partition for testing
+    const esp_partition_t *partition_data = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage");
+    TEST_ASSERT_NOT_NULL(partition_data);
+
+    const esp_partition_t *verified_partition = NULL;
+    esp_err_t err;
+
+    // Test 1: Valid partition verification
+    err = esp_partition_verify_err(partition_data, &verified_partition);
+    TEST_ESP_OK(err);
+    TEST_ASSERT_EQUAL_PTR(partition_data, verified_partition);
+
+    // Test 2: Both parameters NULL
+    err = esp_partition_verify_err(NULL, NULL);
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, err);
+
+    // Test 3: Partition with wrong address should not match
+    esp_partition_t partition_copy = *partition_data;
+    partition_copy.address = 0xFFFFFFFF; // Invalid address
+    verified_partition = NULL;
+    err = esp_partition_verify_err(&partition_copy, &verified_partition);
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, err);
+    TEST_ASSERT_NULL(verified_partition);
+
+    // Test 4: Partition with wrong size should not match
+    partition_copy = *partition_data;
+    partition_copy.size = 0xFFFFFFFF; // Invalid size
+    verified_partition = NULL;
+    err = esp_partition_verify_err(&partition_copy, &verified_partition);
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, err);
+    TEST_ASSERT_NULL(verified_partition);
+
+    // Test 5: Partition with wrong type should not match
+    partition_copy = *partition_data;
+    partition_copy.type = ESP_PARTITION_TYPE_APP; // Wrong type
+    verified_partition = NULL;
+    err = esp_partition_verify_err(&partition_copy, &verified_partition);
+    TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, err);
+    TEST_ASSERT_NULL(verified_partition);
+
+    // Test 6: Test with a partition that has empty label
+    const esp_partition_t *app_partition = esp_partition_find_first(ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_ANY, NULL);
+    if (app_partition != NULL && strlen(app_partition->label) == 0) {
+        verified_partition = NULL;
+        err = esp_partition_verify_err(app_partition, &verified_partition);
+        TEST_ESP_OK(err);
+        TEST_ASSERT_NOT_NULL(verified_partition);
+        TEST_ASSERT_EQUAL_PTR(app_partition, verified_partition);
+    }
+}
+
 TEST(partition_api, test_partition_mmap)
 {
     const esp_partition_t *partition_data = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "storage");
@@ -750,8 +859,11 @@ TEST_GROUP_RUNNER(partition_api)
     RUN_TEST_CASE(partition_api, test_partition_find_app);
     RUN_TEST_CASE(partition_api, test_partition_find_data);
     RUN_TEST_CASE(partition_api, test_partition_find_first);
+    RUN_TEST_CASE(partition_api, test_partition_find_err);
+    RUN_TEST_CASE(partition_api, test_partition_find_first_err);
     RUN_TEST_CASE(partition_api, test_partition_ops);
     RUN_TEST_CASE(partition_api, test_partition_mmap);
+    RUN_TEST_CASE(partition_api, test_partition_verify_err);
     RUN_TEST_CASE(partition_api, test_partition_mmap_support_for_greater_than_4M);
     RUN_TEST_CASE(partition_api, test_partition_mmap_diff_size);
     RUN_TEST_CASE(partition_api, test_partition_mmap_reopen);

components/esp_partition/include/esp_partition.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -169,6 +169,35 @@ typedef struct {
  */
 esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
 
+/**
+ * @brief Find partition based on one or more parameters with error reporting
+ *
+ * This function provides the same functionality as esp_partition_find() but returns
+ * error information instead of just NULL on failure. This allows applications
+ * to distinguish between "no partitions found" and actual error conditions.
+ *
+ * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer.
+ *             To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set
+ *             subtype argument to ESP_PARTITION_SUBTYPE_ANY.
+ * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer.
+ *                To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
+ * @param label (optional) Partition label. Set this value if looking
+ *             for partition with a specific name. Pass NULL otherwise.
+ * @param[out] it Output iterator which can be used to enumerate all the partitions found. Must not be NULL.
+ *               Set to NULL if no partitions were found or on error.
+ *               If not NULL after successful call, iterator must be released using
+ *               esp_partition_iterator_release when not used any more.
+ *
+ * @return
+ *         - ESP_OK: Operation completed successfully
+ *         - ESP_ERR_INVALID_ARG: if param[out] it is NULL, or if type is ESP_PARTITION_TYPE_ANY
+ *                                but subtype is not ESP_PARTITION_SUBTYPE_ANY
+ *         - ESP_ERR_NO_MEM: if memory allocation failed
+ *         - ESP_ERR_NOT_FOUND: if no partition were found
+ *         - Other error codes from partition loading functions
+ */
+esp_err_t esp_partition_find_err(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label, esp_partition_iterator_t* it);
+
 /**
  * @brief Find first partition based on one or more parameters
  *
@@ -185,6 +214,34 @@ esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_parti
  */
 const esp_partition_t* esp_partition_find_first(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label);
 
+/**
+ * @brief Find first partition based on one or more parameters with error reporting
+ *
+ * This function provides the same functionality as esp_partition_find_first() but returns
+ * error information instead of just NULL on failure. This allows applications
+ * to distinguish between "no partition found" and actual error conditions.
+ *
+ * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer.
+ *             To find all partitions, no matter the type, use ESP_PARTITION_TYPE_ANY, and set
+ *             subtype argument to ESP_PARTITION_SUBTYPE_ANY.
+ * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer
+ *                To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
+ * @param label (optional) Partition label. Set this value if looking
+ *             for partition with a specific name. Pass NULL otherwise.
+ * @param[out] partition Output pointer to esp_partition_t structure. Must not be NULL.
+ *                       Set to NULL if no partition is found or on error.
+ *                       If not NULL after successful call, this pointer is valid for the lifetime of the application.
+ *
+ * @return
+ *         - ESP_OK: Operation completed successfully (regardless of whether partition was found)
+ *         - ESP_ERR_INVALID_ARG: if param[out] partition is NULL, or if type is ESP_PARTITION_TYPE_ANY
+ *                                but subtype is not ESP_PARTITION_SUBTYPE_ANY
+ *         - ESP_ERR_NO_MEM: if memory allocation failed
+ *         - ESP_ERR_NOT_FOUND: if no partition were found
+ *         - Other error codes from partition loading functions
+ */
+esp_err_t esp_partition_find_first_err(esp_partition_type_t type, esp_partition_subtype_t subtype, const char* label, const esp_partition_t** partition);
+
 /**
  * @brief Get esp_partition_t structure for given partition
  *
@@ -236,6 +293,45 @@ void esp_partition_iterator_release(esp_partition_iterator_t iterator);
  */
 const esp_partition_t* esp_partition_verify(const esp_partition_t* partition);
 
+/**
+ * @brief Verify partition data with error reporting
+ *
+ * This function provides the same functionality as esp_partition_verify() but returns
+ * error information instead of just NULL on failure. This allows applications
+ * to distinguish between "partition not found" and actual error conditions
+ *
+ * Given a pointer to partition data, verify this partition exists in the partition table
+ * by comparing all key fields (flash_chip, address, size, encrypted status). The function
+ * searches through all registered partitions with matching type, subtype, and label.
+ *
+ * This function is useful to:
+ * - Take partition data from RAM buffer and convert to permanent flash-based pointer
+ * - Validate partition structures obtained from external sources
+ * - Ensure partition data integrity before performing operations
+ *
+ * @param partition Pointer to partition data to verify. Must be non-NULL.
+ *                  The following fields are used for verification:
+ *                  - type: Partition type
+ *                  - subtype: Partition subtype
+ *                  - label: Partition label (if non-empty)
+ *                  - flash_chip: Flash chip pointer
+ *                  - address: Starting address
+ *                  - size: Partition size
+ *                  - encrypted: Encryption status
+ * @param[out] out_partition Output pointer to verified esp_partition_t structure. Must not be NULL.
+ *                           Set to NULL if partition is not found or on error.
+ *                           If not NULL after successful call, this pointer is valid for the
+ *                           lifetime of the application and points to the permanent partition
+ *                           structure in flash.
+ *
+ * @return
+ *         - ESP_OK: Partition verified successfully and found in partition table
+ *         - ESP_ERR_INVALID_ARG: if partition or out_partition is NULL
+ *         - ESP_ERR_NO_MEM: if memory allocation failed during partition search
+ *         - ESP_ERR_NOT_FOUND: if no matching partition found in partition table
+ */
+esp_err_t esp_partition_verify_err(const esp_partition_t* partition, const esp_partition_t** out_partition);
+
 /**
  * @brief Read data from the partition
  *