Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(nvs_flash): correct public API docs for error code

Browse Source 
-align nvs.h / nvs_handle.hpp Doxygen with the implementation: fix return codes
-guard nvs_open against a NULL out_handle
This commit is contained in:
radek.tandler
2026-09-02 15:11:35 +02:00
parent 5e6f53cdb3
commit 2e8f578aaf
3 changed files with 123 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/nvs_flash/include/nvs.h
+43 -25
View File
@@ -152,9 +152,9 @@ typedef struct nvs_opaque_iterator_t *nvs_iterator_t;
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "nvs" is not found
* - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
* - ESP_ERR_NVS_NOT_FOUND if namespace doesn't exist yet and
* mode is NVS_READONLY
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the namespace name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is no space for a new entry or there are too many different
* namespaces (maximum allowed different namespaces: 254)
@@ -173,9 +173,12 @@ esp_err_t nvs_open(const char* namespace_name, nvs_open_mode_t open_mode, nvs_ha
*
* @param[in] part_name Label (name) of the partition of interest for object read/write/erase
* @param[in] namespace_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] open_mode NVS_READWRITE or NVS_READONLY. If NVS_READONLY, will
* open a handle for reading only. All write requests will
* be rejected for this handle.
* @param[in] open_mode NVS_READONLY opens a read only handle
* NVS_READWRITE opens a read/write handle. erase and set operations are allowed.
* previous data is marked as deleted only and new data is written to a new location.
* NVS_READWRITE_PURGE opens a read/write handle. Update and erase operations are allowed.
* previous data is purged from flash memory to ensure that it cannot be recovered.
* New data is written to a new location.
* @param[out] out_handle If successful (return code is zero), handle will be
* returned in this argument.
*
@@ -185,9 +188,9 @@ esp_err_t nvs_open(const char* namespace_name, nvs_open_mode_t open_mode, nvs_ha
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with specified name is not found
* - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
* - ESP_ERR_NVS_NOT_FOUND if namespace doesn't exist yet and
* mode is NVS_READONLY
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the namespace name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NO_MEM in case memory could not be allocated for the internal structures
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is no space for a new entry or there are too many different
* namespaces (maximum allowed different namespaces: 254)
@@ -218,7 +221,7 @@ esp_err_t nvs_open_from_partition(const char *part_name, const char* namespace_n
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -280,13 +283,17 @@ esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value);
/**
* @brief set string for given key
*
* Sets string value for the key. Function requires whole space for new data to be available
* as contiguous entries in same nvs page. Operation consumes 1 overhead entry and 1 entry per
* each 32 characters of new string including zero character to be set. In case of value update
* for existing key, entries occupied by the previous value and overhead entry are returned to
* the pool of available entries.
* Sets string value for the key. The whole string (including the null terminator) must fit as a
* contiguous run of entries on a single NVS page. The operation consumes 1 overhead (metadata)
* entry plus \c ceil((strlen(value) + 1) / 32) data entries.
*
* On update, the new value is written first and the previous value is erased afterwards, so free
* space for the new value is required regardless of the size of the old one. Entries occupied by
* the previous value become available only for subsequent operations (and only after page reclaim).
*
* Note that storage of long string values can fail due to fragmentation of nvs pages even if
* \c available_entries returned by \c nvs_get_stats suggests enough overall space available.
* See the NVS documentation section "Space Consumption" for details.
* Note that the underlying storage will not be updated until \c nvs_commit is called.
*
*
@@ -300,9 +307,11 @@ esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value);
*
* @return
* - ESP_OK if value was set successfully
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -317,10 +326,19 @@ esp_err_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value);
/**
* @brief set variable length binary value for given key
*
* Sets variable length binary value for the key. Function uses 2 overhead and 1 entry
* per each 32 bytes of new data from the pool of available entries. See \c nvs_get_stats .
* In case of value update for existing key, space occupied by the existing value and 2 overhead entries
* are returned to the pool of available entries.
* Sets variable length binary value for the key. A blob is stored as one \c BLOB_INDEX entry plus
* one or more data chunks (each chunk is a \c BLOB_DATA header entry followed by its payload
* entries, on a separate page). Storing a blob therefore needs
* \c 1 + k + ceil(length / 32) entries, where \c k is the number of chunks/pages used. The
* overhead is exactly 2 entries only when the blob fits in a single chunk; fragmentation
* increases \c k. See \c nvs_get_stats and the NVS documentation section "Space Consumption".
*
* On update, the new value is written first and the previous value is erased afterwards, so free
* space for the new value is required regardless of the size of the old one. Entries occupied by
* the previous value become available only for subsequent operations (and only after page reclaim).
*
* Note that storage of large blobs can fail due to fragmentation of nvs pages even if
* \c available_entries returned by \c nvs_get_stats suggests enough overall space available.
* Note that the underlying storage will not be updated until \c nvs_commit is called.
*
* @param[in] handle Handle obtained from nvs_open function.
@@ -337,7 +355,7 @@ esp_err_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value);
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -384,6 +402,7 @@ esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value,
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - ESP_ERR_NVS_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
*/
esp_err_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value);
@@ -491,7 +510,7 @@ esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value
* NVS partition (only if NVS assertion checks are disabled)
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_HANDLE if handle has been closed or is NULL
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if \c length is not sufficient to store data
*/
esp_err_t nvs_get_str (nvs_handle_t handle, const char* key, char* out_value, size_t* length);
@@ -645,12 +664,11 @@ typedef struct {
* @return
* - ESP_OK if the changes have been written successfully.
* Return param nvs_stats will be filled.
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "name" is not found.
* Return param nvs_stats will be filled 0.
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized.
* Return param nvs_stats will be filled 0.
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized, or if the
* partition with label \c part_name is not found / not initialized.
* Return param nvs_stats will be filled with 0.
* - ESP_ERR_INVALID_ARG if nvs_stats is equal to NULL.
* - ESP_ERR_INVALID_STATE if there is page with the status of INVALID.
* - ESP_ERR_NVS_INVALID_STATE if there is a page with the status of INVALID.
* Return param nvs_stats will be filled not with correct values because
* not all pages will be counted. Counting will be interrupted at the first INVALID page.
*/
components/nvs_flash/include/nvs_handle.hpp
+76 -16
View File
@@ -73,15 +73,19 @@ public:
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
* write operation has failed. The value was written however, and
* update will be finished after re-initialization of nvs, provided that
* flash operation doesn't fail again.
* - ESP_ERR_NVS_VALUE_TOO_LONG if the string value is too long
* - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*/
template<typename T>
esp_err_t set_item(const char *key, T value);
@@ -104,9 +108,12 @@ public:
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - ESP_ERR_NVS_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*/
template<typename T>
esp_err_t get_item(const char *key, T &value);
@@ -125,8 +132,9 @@ public:
*
* @return
* - ESP_OK if value was set successfully
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the key name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is not enough space in the
* underlying storage to save the value
* - ESP_ERR_NVS_REMOVE_FAILED if the value wasn't updated because flash
@@ -134,6 +142,9 @@ public:
* update will be finished after re-initialization of nvs, provided that
* flash operation doesn't fail again.
* - ESP_ERR_NVS_VALUE_TOO_LONG if the value is too long
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*
* @note compare to \ref nvs_set_blob in nvs.h
*/
@@ -162,9 +173,13 @@ public:
*
* @return
* - ESP_OK if the value was retrieved successfully
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_ERR_NVS_INVALID_NAME if key name doesn't satisfy constraints
* - ESP_ERR_NVS_TYPE_MISMATCH if the type of the stored value doesn't match the requested type
* - ESP_ERR_NVS_INVALID_LENGTH if length is not sufficient to store data
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*/
virtual esp_err_t get_string(const char *key, char* out_str, size_t len) = 0;
virtual esp_err_t get_blob(const char *key, void* out_blob, size_t len) = 0;
@@ -178,8 +193,10 @@ public:
* For strings, this size includes the zero terminator.
*
* @return - ESP_OK if the item with specified type and key exists. Its size will be returned via \c size.
* - ESP_ERR_NVS_NOT_FOUND if an item with the requested key and type doesn't exist or any other
* error occurs.
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_NOT_FOUND if an item with the requested key and type doesn't exist
* - ESP_ERR_NVS_TYPE_MISMATCH if an item with the requested key exists but has a different type
* - other error codes from the underlying storage driver
*/
virtual esp_err_t get_item_size(ItemType datatype, const char *key, size_t &size) = 0;
@@ -200,18 +217,46 @@ public:
/**
* @brief Erases an entry.
*
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - ESP_ERR_NVS_NOT_FOUND if the requested key doesn't exist
* - ESP_FAIL if there is an internal error; most likely due to corrupted
* NVS partition (only if NVS assertion checks are disabled)
* - other error codes from the underlying storage driver
*/
virtual esp_err_t erase_item(const char* key) = 0;
/**
* Erases all entries in the scope of this handle. The scope may vary, depending on the implementation.
*
* @not If you want to erase the whole nvs flash (partition), refer to \ref
* The scope may vary, depending on the implementation (typically the opened namespace).
*
* @note If you want to erase the whole NVS flash partition, use nvs_flash_erase() /
* nvs_flash_erase_partition() instead.
*
* @return
* - ESP_OK if erase operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
virtual esp_err_t erase_all() = 0;
/**
* Purges all erased entries in the scope of this handle. The scope may vary, depending on the implementation.
* @brief Purges all erased entries in the scope of this handle.
*
* The scope may vary, depending on the implementation.
*
* @return
* - ESP_OK if purge operation was successful
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
* - ESP_ERR_NVS_READ_ONLY if storage handle was opened as read only
* - other error codes from the underlying storage driver
*/
virtual esp_err_t purge_all() = 0;
@@ -219,6 +264,10 @@ public:
* Commits all changes done through this handle so far.
* Currently, NVS writes to storage right after the set and get functions,
* but this is not guaranteed.
*
* @return
* - ESP_OK if commit was successful
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL
*/
virtual esp_err_t commit() = 0;
@@ -229,13 +278,14 @@ public:
*
*
* @return
* - ESP_OK if the changes have been written successfully.
* Return param used_entries will be filled valid value.
* - ESP_OK if the used entry count has been calculated successfully.
* Return param usedEntries will be filled with a valid value.
* - ESP_ERR_NVS_INVALID_HANDLE if the handle has been closed or is NULL.
* Return param usedEntries will be filled with 0.
* - ESP_ERR_NVS_NOT_INITIALIZED if the storage driver is not initialized.
* Return param used_entries will be filled 0.
* - ESP_ERR_INVALID_ARG if nvs_stats equal to NULL.
* Return param usedEntries will be filled with 0.
* - Other error codes from the underlying storage driver.
* Return param used_entries will be filled 0.
* Return param usedEntries will be filled with 0.
*/
virtual esp_err_t get_used_entry_count(size_t& usedEntries) = 0;
@@ -260,8 +310,11 @@ protected:
* - ESP_ERR_NVS_PART_NOT_FOUND if the partition with label "nvs" is not found
* - ESP_ERR_NVS_NOT_FOUND id namespace doesn't exist yet and
* mode is NVS_READONLY
* - ESP_ERR_NVS_INVALID_NAME if namespace name doesn't satisfy constraints
* - ESP_ERR_NVS_KEY_TOO_LONG if the namespace name is longer than (NVS_KEY_NAME_MAX_SIZE-1) characters
* - ESP_ERR_NOT_ALLOWED if the NVS partition is read-only and mode is NVS_READWRITE
* - ESP_ERR_NVS_NOT_ENOUGH_SPACE if there is no space for a new entry or there are too many
* different namespaces (maximum allowed different namespaces: 254)
* - ESP_ERR_NO_MEM if memory could not be allocated for the internal structures
* - other error codes from the underlying storage driver
*
* @return unique pointer of an nvs handle on success, an empty unique pointer otherwise
@@ -274,6 +327,13 @@ std::unique_ptr<NVSHandle> open_nvs_handle_from_partition(const char *partition_
/**
* @brief This function does the same as \ref open_nvs_handle_from_partition but uses the default nvs partition
* instead of a partition_name parameter.
*
* @param[in] ns_name Namespace name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters.
* @param[in] open_mode NVS_READONLY, NVS_READWRITE, or NVS_READWRITE_PURGE.
* @param[out] err Optional pointer to an esp_err_t result of the open operation. See
* open_nvs_handle_from_partition() for the list of possible error codes.
*
* @return unique pointer of an nvs handle on success, an empty unique pointer otherwise
*/
std::unique_ptr<NVSHandle> open_nvs_handle(const char *ns_name,
nvs_open_mode_t open_mode,
components/nvs_flash/src/nvs_api.cpp
+4
View File
@@ -293,6 +293,10 @@ static esp_err_t nvs_find_ns_handle(nvs_handle_t c_handle, NVSHandleSimple** han
extern "C" esp_err_t nvs_open_from_partition(const char *part_name, const char* namespace_name, nvs_open_mode_t open_mode, nvs_handle_t *out_handle)
{
if (out_handle == nullptr) {
return ESP_ERR_INVALID_ARG;
}
esp_err_t lock_result = Lock::init();
if (lock_result != ESP_OK) {
return lock_result;