diff --git a/features/device_key/source/DeviceKey.h b/features/device_key/source/DeviceKey.h index 6dd83ecc67..2b6d3950ea 100644 --- a/features/device_key/source/DeviceKey.h +++ b/features/device_key/source/DeviceKey.h @@ -91,7 +91,7 @@ public: */ int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type); - /** Set a device key into the KVStore. If TRNG support is missing, call this method + /** Set a device key into the KVStore. If entropy support is missing, call this method * before calling device_key_derived_key. This method should be called only once! * @param value Input buffer contain the key. * @param isize Size of the supplied key. Must be 16 bytes or 32 bytes. @@ -131,7 +131,7 @@ private: int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint32_t ikey_type); - /** Generate a random ROT key by using TRNG + /** Generate a random ROT key by using entropy * @param output Output buffer for the generated key. * @param size Input: The size of the buffer. If size is less * than 16 bytes, the method generates an diff --git a/features/storage/kvstore/KVStore.h b/features/storage/kvstore/KVStore.h index f7a67f62ba..ed07691456 100644 --- a/features/storage/kvstore/KVStore.h +++ b/features/storage/kvstore/KVStore.h @@ -191,7 +191,8 @@ public: */ virtual int iterator_close(iterator_t it) = 0; - /** Convenience function for checking key validity + /** Convenience function for checking key validity. + * Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * * @param[in] key Key buffer. * diff --git a/features/storage/kvstore/conf/kv_config.h b/features/storage/kvstore/conf/kv_config.h index 43b8677296..6a78cf3390 100644 --- a/features/storage/kvstore/conf/kv_config.h +++ b/features/storage/kvstore/conf/kv_config.h @@ -34,7 +34,7 @@ extern "C" { #define _STORAGE_CONFIG(dev) _STORAGE_CONFIG_concat(dev) /** - * @brief This function initializes one of the configuration that exists in Mbed OS. To overwite + * @brief This function initializes one of the configuration that exists in Mbed OS. To overwrite * the default configuration, please overwrite this function. * * @returns 0 on success or negative value on failure. diff --git a/features/storage/kvstore/filesystemstore/FileSystemStore.h b/features/storage/kvstore/filesystemstore/FileSystemStore.h index 0112044d88..34807cf6f5 100644 --- a/features/storage/kvstore/filesystemstore/FileSystemStore.h +++ b/features/storage/kvstore/filesystemstore/FileSystemStore.h @@ -23,7 +23,9 @@ namespace mbed { -/** FileSystemStore for Secure Store +/** FileSystemStore for Secure Store. + * This class implements the KVStore interface to + * create a key value store over FileSystem. * * @code * ... @@ -34,7 +36,7 @@ class FileSystemStore : public KVStore { public: /** Create FileSystemStore - A Key Value API on top of FS * - * @param fs File system on top which FileSystemStore is adding KV API + * @param fs File system (FAT/LITTLE) on top which FileSystemStore is adding KV API */ FileSystemStore(FileSystem *fs); @@ -44,7 +46,8 @@ public: virtual ~FileSystemStore() {} /** - * @brief Initialize FileSystemStore + * @brief Initialize FileSystemStore, Checking validity of + * KVStore writing folder and if not exists creates it. * * @returns MBED_SUCCESS Success. * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation. @@ -52,7 +55,7 @@ public: virtual int init(); /** - * @brief Deinitialize FileSystemStore + * @brief Deinitialize FileSystemStore, release and free resources. * * @returns MBED_SUCCESS Success. */ @@ -85,7 +88,7 @@ public: virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags); /** - * @brief Get one FileSystemStore item, given key. + * @brief Get one FileSystemStore item by given key. * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[in] buffer Value data buffer. @@ -98,13 +101,13 @@ public: * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation. * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments. * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments. - * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt. + * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted. * MBED_ERROR_ITEM_NOT_FOUND No such key. */ virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0); /** - * @brief Get information of a given key. + * @brief Get information of a given key. The returned info contains size and flags * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[out] info Returned information structure. @@ -114,13 +117,13 @@ public: * MBED_ERROR_FAILED_OPERATION Underlying file system failed operation. * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments. * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments. - * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt. + * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted. * MBED_ERROR_ITEM_NOT_FOUND No such key. */ virtual int get_info(const char *key, info_t *info); /** - * @brief Remove a FileSystemStore item, given key. + * @brief Remove a FileSystemStore item by given key. * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @@ -134,7 +137,8 @@ public: virtual int remove(const char *key); /** - * @brief Start an incremental FileSystemStore set sequence. + * @brief Start an incremental FileSystemStore set sequence. This operation is blocking other operations. + * Any get/set/remove/iterator operation will be blocked until set_finalize will be called. * * @param[out] handle Returned incremental set handle. * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. @@ -151,7 +155,8 @@ public: virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags); /** - * @brief Add data to incremental FileSystemStore set sequence. + * @brief Add data to incremental FileSystemStore set sequence. This operation is blocking other operations. + * Any get/set/remove operation will be blocked until set_finalize will be called. * * @param[in] handle Incremental set handle. * @param[in] value_data Value data to add. @@ -180,6 +185,7 @@ public: /** * @brief Start an iteration over FileSystemStore keys. + * There are no issues with any other operations while iterator is open. * * @param[out] it Returned iterator handle. * @param[in] prefix Key prefix (null for all keys). @@ -192,6 +198,7 @@ public: /** * @brief Get next key in iteration. + * There are no issues with any other operations while iterator is open. * * @param[in] it Iterator handle. * @param[in] key Buffer for returned key. diff --git a/features/storage/kvstore/global_api/kvstore_global_api.h b/features/storage/kvstore/global_api/kvstore_global_api.h index 43ff72db2a..e588ca292d 100644 --- a/features/storage/kvstore/global_api/kvstore_global_api.h +++ b/features/storage/kvstore/global_api/kvstore_global_api.h @@ -63,7 +63,7 @@ typedef struct info { int kv_set(const char *full_name_key, const void *buffer, size_t size, uint32_t create_flags); /** - * @brief Get one KVStore item, given key. + * @brief Get one KVStore item by given key. * * @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[in] buffer Value data buffer. @@ -75,7 +75,7 @@ int kv_set(const char *full_name_key, const void *buffer, size_t size, uint32_t int kv_get(const char *full_name_key, void *buffer, size_t buffer_size, size_t *actual_size); /** - * @brief Get information of a given key. + * @brief Get information of a given key.The returned info contains size and flags * * @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[out] info Returned information structure. @@ -85,7 +85,7 @@ int kv_get(const char *full_name_key, void *buffer, size_t buffer_size, size_t * int kv_get_info(const char *full_name_key, kv_info_t *info); /** - * @brief Remove a KVStore item, given key. + * @brief Remove a KVStore item by given key. * * @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @@ -95,7 +95,8 @@ int kv_remove(const char *full_name_key); /** * @brief Start an iteration over KVStore keys to find all the entries - * that fit the full_prefix + * that fit the full_prefix. There are no issues with any other operations while + * iterator is open. * * @param[out] it Allocating iterator handle. * Do not forget to call kv_iterator_close @@ -109,7 +110,8 @@ int kv_remove(const char *full_name_key); int kv_iterator_open(kv_iterator_t *it, const char *full_prefix); /** - * @brief Get next key in iteration that matches the prefix. + * @brief Get next key in iteration that matches the prefix. There are no issues with any + * other operations while iterator is open. * * @param[in] it Iterator handle. * @param[in] key Buffer for returned key. @@ -129,7 +131,7 @@ int kv_iterator_next(kv_iterator_t it, char *key, size_t key_size); int kv_iterator_close(kv_iterator_t it); /** - * @brief Remove all keys and related data + * @brief Remove all keys and related data from a specified partition. * * @param[in] kvstore_path /Partition/ * diff --git a/features/storage/kvstore/kv_map/KVMap.h b/features/storage/kvstore/kv_map/KVMap.h index 8f128f2f01..3c462a1f44 100644 --- a/features/storage/kvstore/kv_map/KVMap.h +++ b/features/storage/kvstore/kv_map/KVMap.h @@ -144,10 +144,11 @@ public: /** * @brief Full name lookup, and then break it into KVStore instance and key * - * @param full_name String parameter contains the /partition name/key. - * @param kv_instance The main KVStore instance associated with the required partition name. - * @param key_index An index to the first character of the key. - * @param flags_mask Return the flag masking for the current configuration + * @param[in] full_name String parameter contains the partition name to look for. + * The String should be formated as follow "/partition name/key". key is optional. + * @param[out] kv_instance Returns the main KVStore instance associated with the required partition name. + * @param[out] key_index Returns an index to the first character of the key. + * @param[out] flags_mask Return the flag masking for the current configuration * @return 0 on success, negative error code on failure */ int lookup(const char *full_name, mbed::KVStore **kv_instance, size_t *key_index, uint32_t *flags_mask = NULL); @@ -211,7 +212,7 @@ public: private: /** - * @brief Deinitialize all components of a partition configuration struct. + * @brief Deinitialize all components of a partition configuration struct. * * @param partition Partition configuration struct. */ @@ -220,9 +221,9 @@ private: /** * @brief Full name lookup, and then break it into KVStore config and key * - * @param full_name String parameter contains the /partition name/key. - * @param kv_config The configuration struct associated with the partition name - * @param key_index An index to the first character of the key. + * @param[in] full_name String parameter contains the /partition name/key. + * @param[out] kv_config Returns The configuration struct associated with the partition name + * @param[out] key_index Returns an index to the first character of the key. * @return 0 on success, negative error code on failure */ int config_lookup(const char *full_name, kvstore_config_t **kv_config, size_t *key_index); diff --git a/features/storage/kvstore/securestore/SecureStore.h b/features/storage/kvstore/securestore/SecureStore.h index e6d73b528d..cecc5e4e93 100644 --- a/features/storage/kvstore/securestore/SecureStore.h +++ b/features/storage/kvstore/securestore/SecureStore.h @@ -53,8 +53,8 @@ public: /** * @brief Class constructor * - * @param[in] underlying_kv Underlying KVStore. - * @param[in] rbp_kv Rollback protect KVStore. + * @param[in] underlying_kv KVStore that will hold the data. + * @param[in] rbp_kv Additional KVStore used for rollback protection. * * @returns none */ @@ -68,7 +68,8 @@ public: virtual ~SecureStore(); /** - * @brief Initialize SecureStore + * @brief Initialize SecureStore class. It will also initialize + * the underlying KVStore and the rollback protection KVStore. * * @returns MBED_SUCCESS Success. * or any other error from underlying KVStore instances. @@ -76,7 +77,7 @@ public: virtual int init(); /** - * @brief Deinitialize SecureStore + * @brief Deinitialize SecureStore class, free handles and memory allocations. * * @returns MBED_SUCCESS Success. * or any other error from underlying KVStore instances. @@ -100,7 +101,8 @@ public: * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[in] buffer Value data buffer. * @param[in] size Value data size. - * @param[in] create_flags Flag mask. + * @param[in] create_flags Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG| + * REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG * * @returns MBED_SUCCESS Success. * MBED_ERROR_NOT_READY Not initialized. @@ -141,7 +143,7 @@ public: * @brief Get information of a given key. * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. - * @param[out] info Returned information structure. + * @param[out] info Returned information structure containing size and flags. * * @returns MBED_SUCCESS Success. * MBED_ERROR_NOT_READY Not initialized. @@ -173,12 +175,14 @@ public: /** - * @brief Start an incremental KVStore set sequence. + * @brief Start an incremental KVStore set sequence. This operation is blocking other operations. + * Any get/set/remove/iterator operation will be blocked until set_finalize will be called. * * @param[out] handle Returned incremental set handle. * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[in] final_data_size Final value data size. - * @param[in] create_flags Flag mask. + * @param[in] create_flags Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG| + * REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG * * @returns MBED_SUCCESS Success. * MBED_ERROR_NOT_READY Not initialized. @@ -192,7 +196,8 @@ public: virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags); /** - * @brief Add data to incremental KVStore set sequence. + * @brief Add data to incremental KVStore set sequence. This operation is blocking other operations. + * Any get/set/remove operation will be blocked until set_finalize will be called. * * @param[in] handle Incremental set handle. * @param[in] value_data value data to add. @@ -223,6 +228,7 @@ public: /** * @brief Start an iteration over KVStore keys. + * There are no issue with any other operation while iterator is open. * * @param[out] it Returned iterator handle. * @param[in] prefix Key prefix (null for all keys). @@ -236,6 +242,7 @@ public: /** * @brief Get next key in iteration. + * There are no issue with any other operation while iterator is open. * * @param[in] it Iterator handle. * @param[in] key Buffer for returned key. diff --git a/features/storage/kvstore/tdbstore/TDBStore.h b/features/storage/kvstore/tdbstore/TDBStore.h index 8a5ca7d8cc..8746360728 100644 --- a/features/storage/kvstore/tdbstore/TDBStore.h +++ b/features/storage/kvstore/tdbstore/TDBStore.h @@ -39,7 +39,10 @@ public: /** * @brief Class constructor * - * @param[in] bd Underlying block device. + * @param[in] bd Underlying block device. The BlockDevice + * can be any BlockDevice with flash characteristics. + * If using a non flash BlockDevice, like SDBlockDevice, + * please add the FlashSimBlockDevice on top of it. * * @returns none */ @@ -53,7 +56,9 @@ public: virtual ~TDBStore(); /** - * @brief Initialize TDBStore + * @brief Initialize TDBStore. If data exists, TDBStore will check the data integrity + * on initialize. If Integrity checks fails the TDBStore will use GC to collect + * the available data and clean corrupted and erroneous records. * * @returns MBED_SUCCESS Success. * MBED_ERROR_READ_FAILED Unable to read from media. @@ -62,7 +67,7 @@ public: virtual int init(); /** - * @brief Deinitialize TDBStore + * @brief Deinitialize TDBStore, release and free resources. * * @returns MBED_SUCCESS Success. */ @@ -99,7 +104,7 @@ public: virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags); /** - * @brief Get one TDBStore item, given key. + * @brief Get one TDBStore item by given key. * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[in] buffer Value data buffer. @@ -119,7 +124,7 @@ public: size_t offset = 0); /** - * @brief Get information of a given key. + * @brief Get information of a given key. The returned info contains size and flags * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @param[out] info Returned information structure. @@ -134,7 +139,7 @@ public: virtual int get_info(const char *key, info_t *info); /** - * @brief Remove a TDBStore item, given key. + * @brief Remove a TDBStore item by given key. * * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. * @@ -151,7 +156,8 @@ public: /** - * @brief Start an incremental TDBStore set sequence. + * @brief Start an incremental TDBStore set sequence. This operation is blocking other operations. + * Any get/set/remove/iterator operation will be blocked until set_finalize will be called. * * @param[out] handle Returned incremental set handle. * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'. @@ -170,7 +176,8 @@ public: virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags); /** - * @brief Add data to incremental TDBStore set sequence. + * @brief Add data to incremental TDBStore set sequence. This operation is blocking other operations. + * Any get/set/remove operation will be blocked until set_finalize will be called. * * @param[in] handle Incremental set handle. * @param[in] value_data Value data to add. @@ -198,6 +205,7 @@ public: /** * @brief Start an iteration over KVStore keys. + * There are no issues with any other operations while iterator is open. * * @param[out] it Returned iterator handle. * @param[in] prefix Key prefix (null for all keys). @@ -210,6 +218,7 @@ public: /** * @brief Get next key in iteration. + * There are no issues with any other operations while iterator is open. * * @param[in] it Iterator handle. * @param[in] key Buffer for returned key. @@ -237,7 +246,8 @@ public: virtual int iterator_close(iterator_t it); /** - * @brief Set data in reserved area. + * @brief Set data in reserved area which is a special location for special data such as ROT. + * The data written to reserved area can not be overwritten. * * @param[in] reserved_data Reserved data buffer. * @param[in] reserved_data_buf_size @@ -253,7 +263,7 @@ public: virtual int reserved_data_set(const void *reserved_data, size_t reserved_data_buf_size); /** - * @brief Get data from reserved area. + * @brief Get data from reserved area which is a special location for special data such as ROT. * * @param[in] reserved_data Reserved data buffer. * @param[in] reserved_data_buf_size