Skip to content

Commit

Permalink
[doc]: NVS documentation updates
Browse files Browse the repository at this point in the history 
* Move nvs flash README to common doc directory
* correct markup of functions and types in text
  from old README
* Better comment of nvs_get_used_entry_count()
* Mention C++ example in API reference
* Used target instead of hard code ESP32
* Note that strings can only span one page
* Reflect that item types have been moved
* Some clarification about nvs_commit()
* Improved reference to the ESP Partition API
* fixed little mistake in documenting-code.rst
* Change of nvs_open_from_part() to
  nvs_open_from_partition() reflected in docs
* Corrected documentation of
  NVSHandle::get_string(), NVSHandle::get_blob()
  and NVSHandle::get_item_size().

* Closes DOC-165
* Closes IDF-1563
* Closes IDF-859
* Closes #6123
  • Loading branch information
@0xjakob
0xjakob committed Jun 2, 2021
1 parent 98c20ce commit 5395f45
Show file tree
Hide file tree
Showing 7 changed files with 803 additions and 676 deletions.
340 changes: 0 additions & 340 deletions components/nvs_flash/README.rst
View file

This file was deleted.

303 changes: 0 additions & 303 deletions components/nvs_flash/README_CN.rst
View file

This file was deleted.

156 changes: 136 additions & 20 deletions components/nvs_flash/include/nvs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,17 +171,15 @@ esp_err_t nvs_open_from_partition(const char *part_name, const char* name, nvs_o

/**@{*/
/**
* @brief set value for given key
* @brief set int8_t value for given key
*
* This family of functions set value for the key, given its name. Note that
* actual storage will not be updated until nvs_commit function is called.
* Set value for the key, given its name. Note that the actual storage will not be updated
* until \c nvs_commit is called.
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set.
* For strings, the maximum length (including null character) is
* 4000 bytes.
*
* @return
* - ESP_OK if value was set successfully
Expand All @@ -194,16 +192,85 @@ esp_err_t nvs_open_from_partition(const char *part_name, const char* name, nvs_o
* 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_t nvs_set_i8 (nvs_handle_t handle, const char* key, int8_t value);
esp_err_t nvs_set_u8 (nvs_handle_t handle, const char* key, uint8_t value);
esp_err_t nvs_set_i8 (nvs_handle_t handle, const char* key, int8_t value);

/**
* @brief set uint8_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u8 (nvs_handle_t handle, const char* key, uint8_t value);

/**
* @brief set int16_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i16 (nvs_handle_t handle, const char* key, int16_t value);

/**
* @brief set uint16_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u16 (nvs_handle_t handle, const char* key, uint16_t value);

/**
* @brief set int32_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i32 (nvs_handle_t handle, const char* key, int32_t value);

/**
* @brief set uint32_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u32 (nvs_handle_t handle, const char* key, uint32_t value);

/**
* @brief set int64_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_i64 (nvs_handle_t handle, const char* key, int64_t value);

/**
* @brief set uint64_t value for given key
*
* This function is the same as \c nvs_set_i8 except for the data type.
*/
esp_err_t nvs_set_u64 (nvs_handle_t handle, const char* key, uint64_t value);

/**
* @brief set string for given key
*
* Set value for the key, given its name. Note that the actual storage will not be updated
* until \c nvs_commit is called.
*
* @param[in] handle Handle obtained from nvs_open function.
* Handles that were opened read only cannot be used.
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set.
* For strings, the maximum length (including null character) is
* 4000 bytes, if there is one complete page free for writing.
* This decreases, however, if the free space is fragmented.
*
* @return
* - ESP_OK if value was set successfully
* - 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_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_t nvs_set_str (nvs_handle_t handle, const char* key, const char* value);
/**@}*/

Expand Down Expand Up @@ -238,16 +305,15 @@ esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value,

/**@{*/
/**
* @brief get value for given key
* @brief get int8_t value for given key
*
* These functions retrieve value for the key, given its name. If key does not
* These functions retrieve value for the key, given its name. If \c key does not
* exist, or the requested variable type doesn't match the type which was used
* when setting a value, an error is returned.
*
* In case of any error, out_value is not modified.
*
* All functions expect out_value to be a pointer to an already allocated variable
* of the given type.
* \c out_value has to be a pointer to an already allocated variable of the given type.
*
* \code{c}
* // Example of using nvs_get_i32:
Expand All @@ -272,18 +338,61 @@ esp_err_t nvs_set_blob(nvs_handle_t handle, const char* key, const void* value,
* - 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_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value);
esp_err_t nvs_get_u8 (nvs_handle_t handle, const char* key, uint8_t* out_value);
esp_err_t nvs_get_i8 (nvs_handle_t handle, const char* key, int8_t* out_value);

/**
* @brief get uint8_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u8 (nvs_handle_t handle, const char* key, uint8_t* out_value);

/**
* @brief get int16_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i16 (nvs_handle_t handle, const char* key, int16_t* out_value);

/**
* @brief get uint16_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u16 (nvs_handle_t handle, const char* key, uint16_t* out_value);

/**
* @brief get int32_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i32 (nvs_handle_t handle, const char* key, int32_t* out_value);

/**
* @brief get uint32_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u32 (nvs_handle_t handle, const char* key, uint32_t* out_value);

/**
* @brief get int64_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_i64 (nvs_handle_t handle, const char* key, int64_t* out_value);

/**
* @brief get uint64_t value for given key
*
* This function is the same as \c nvs_get_i8 except for the data type.
*/
esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value);
/**@}*/

/**@{*/
/**
* @brief get value for given key
* @brief get string value for given key
*
* These functions retrieve the data of an entry, given its key. If key does not
* exist, or the requested variable type doesn't match the type which was used
Expand Down Expand Up @@ -320,7 +429,7 @@ esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value
*
* @param[in] handle Handle obtained from nvs_open function.
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param out_value Pointer to the output value.
* @param[out] out_value Pointer to the output value.
* May be NULL for nvs_get_str and nvs_get_blob, in this
* case required length will be returned in length argument.
* @param[inout] length A non-zero pointer to the variable holding the length of out_value.
Expand All @@ -334,10 +443,15 @@ esp_err_t nvs_get_u64 (nvs_handle_t handle, const char* key, uint64_t* out_value
* - 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_INVALID_LENGTH if length is not sufficient to store data
* - 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);

/**
* @brief get blob value for given key
*
* This function behaves the same as \c nvs_get_str, except for the data type.
*/
esp_err_t nvs_get_blob(nvs_handle_t handle, const char* key, void* out_value, size_t* length);
/**@}*/

Expand Down Expand Up @@ -454,7 +568,9 @@ esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats);
/**
* @brief Calculate all entries in a namespace.
*
* Note that to find out the total number of records occupied by the namespace,
* An entry represents the smallest storage unit in NVS.
* Strings and blobs may occupy more than one entry.
* Note that to find out the total number of entries occupied by the namespace,
* add one to the returned value used_entries (if err is equal to ESP_OK).
* Because the name space entry takes one entry.
*
Expand All @@ -466,7 +582,7 @@ esp_err_t nvs_get_stats(const char *part_name, nvs_stats_t *nvs_stats);
* size_t used_entries;
* size_t total_entries_namespace;
* if(nvs_get_used_entry_count(handle, &used_entries) == ESP_OK){
* // the total number of records occupied by the namespace
* // the total number of entries occupied by the namespace
* total_entries_namespace = used_entries + 1;
* }
* \endcode
Expand Down
27 changes: 18 additions & 9 deletions components/nvs_flash/include/nvs_handle.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,8 @@ class NVSHandle {
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] value The value to set. Allowed types are the ones declared in ItemType as well as enums.
* For strings, the maximum length (including null character) is
* 4000 bytes.
* 4000 bytes, if there is one complete page free for writing.
* This decreases, however, if the free space is fragmented.
* Note that enums loose their type information when stored in NVS. Ensure that the correct
* enum type is used during retrieval with \ref get_item!
*
Expand Down Expand Up @@ -131,15 +132,14 @@ class NVSHandle {
* Both functions expect out_value to be a pointer to an already allocated variable
* of the given type.
*
* It is suggested that nvs_get/set_str is used for zero-terminated C strings, and
* nvs_get/set_blob used for arbitrary data structures.
* It is suggested that nvs_get/set_str is used for zero-terminated short C strings, and
* nvs_get/set_blob is used for arbitrary data structures and long C strings.
*
* @param[in] key Key name. Maximal length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param out_str/ Pointer to the output value.
* out_blob
* @param[inout] length A non-zero pointer to the variable holding the length of out_value.
* It will be set to the actual length of the value
* written. For nvs_get_str this includes the zero terminator.
* @param[inout] len The length of the output buffer pointed to by out_str/out_blob.
* Use \c get_item_size to query the size of the item beforehand.
*
* @return
* - ESP_OK if the value was retrieved successfully
Expand All @@ -151,9 +151,16 @@ class NVSHandle {
virtual esp_err_t get_blob(const char *key, void* out_blob, size_t len) = 0;

/**
* @brief Looks up the size of an entry's data.
* @brief Look up the size of an entry's data.
*
* @param[in] datatype Data type to search for.
* @param[in] key Key name. Maximum length is (NVS_KEY_NAME_MAX_SIZE-1) characters. Shouldn't be empty.
* @param[out] size Size of the item, if it exists.
* For strings, this size includes the zero terminator.
*
* 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.
*/
virtual esp_err_t get_item_size(ItemType datatype, const char *key, size_t &size) = 0;

Expand All @@ -171,6 +178,8 @@ class NVSHandle {

/**
* 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.
*/
virtual esp_err_t commit() = 0;

Expand Down
Loading

0 comments on commit 5395f45

Please sign in to comment.