Skip to content

Commit 415747d

Browse files
0xc01700xc0170
authored
Merge pull request #8933 from yossi2le/yossi_kvstore_integration
Fixing Doxygen descriptions
2 parents 4491d19 + 6201b8d commit 415747d

File tree

8 files changed

+76
-48
lines changed

8 files changed

+76
-48
lines changed

‎features/device_key/source/DeviceKey.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ class DeviceKey : private mbed::NonCopyable<DeviceKey> {
9191
*/
9292
int generate_derived_key(const unsigned char *isalt, size_t isalt_size, unsigned char *output, uint16_t ikey_type);
9393

94-
/** Set a device key into the KVStore. If TRNG support is missing, call this method
94+
/** Set a device key into the KVStore. If entropy support is missing, call this method
9595
* before calling device_key_derived_key. This method should be called only once!
9696
* @param value Input buffer contain the key.
9797
* @param isize Size of the supplied key. Must be 16 bytes or 32 bytes.
@@ -131,7 +131,7 @@ class DeviceKey : private mbed::NonCopyable<DeviceKey> {
131131
int get_derived_key(uint32_t *ikey_buff, size_t ikey_size, const unsigned char *isalt, size_t isalt_size,
132132
unsigned char *output, uint32_t ikey_type);
133133

134-
/** Generate a random ROT key by using TRNG
134+
/** Generate a random ROT key by using entropy
135135
* @param output Output buffer for the generated key.
136136
* @param size Input: The size of the buffer. If size is less
137137
* than 16 bytes, the method generates an

‎features/storage/kvstore/KVStore.h

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,8 @@ class KVStore {
191191
*/
192192
virtual int iterator_close(iterator_t it) = 0;
193193

194-
/** Convenience function for checking key validity
194+
/** Convenience function for checking key validity.
195+
* Key must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
195196
*
196197
* @param[in] key Key buffer.
197198
*

‎features/storage/kvstore/conf/kv_config.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ extern "C" {
3434
#define _STORAGE_CONFIG(dev) _STORAGE_CONFIG_concat(dev)
3535

3636
/**
37-
* @brief This function initializes one of the configuration that exists in Mbed OS. To overwite
37+
* @brief This function initializes one of the configuration that exists in Mbed OS. To overwrite
3838
* the default configuration, please overwrite this function.
3939
*
4040
* @returns 0 on success or negative value on failure.

‎features/storage/kvstore/filesystemstore/FileSystemStore.h

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,9 @@
2323

2424
namespace mbed {
2525

26-
/** FileSystemStore for Secure Store
26+
/** FileSystemStore for Secure Store.
27+
* This class implements the KVStore interface to
28+
* create a key value store over FileSystem.
2729
*
2830
* @code
2931
* ...
@@ -34,7 +36,7 @@ class FileSystemStore : public KVStore {
3436
public:
3537
/** Create FileSystemStore - A Key Value API on top of FS
3638
*
37-
* @param fs File system on top which FileSystemStore is adding KV API
39+
* @param fs File system (FAT/LITTLE) on top of which FileSystemStore is adding KV API
3840
*/
3941
FileSystemStore(FileSystem *fs);
4042

@@ -44,15 +46,16 @@ class FileSystemStore : public KVStore {
4446
virtual ~FileSystemStore() {}
4547

4648
/**
47-
* @brief Initialize FileSystemStore
49+
* @brief Initialize FileSystemStore, checking validity of
50+
* KVStore writing folder and if it doesn't exist, creating it.
4851
*
4952
* @returns MBED_SUCCESS Success.
5053
* MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
5154
*/
5255
virtual int init();
5356

5457
/**
55-
* @brief Deinitialize FileSystemStore
58+
* @brief Deinitialize FileSystemStore, release and free resources.
5659
*
5760
* @returns MBED_SUCCESS Success.
5861
*/
@@ -85,7 +88,7 @@ class FileSystemStore : public KVStore {
8588
virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags);
8689

8790
/**
88-
* @brief Get one FileSystemStore item, given key.
91+
* @brief Get one FileSystemStore item by given key.
8992
*
9093
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
9194
* @param[in] buffer Value data buffer.
@@ -98,13 +101,13 @@ class FileSystemStore : public KVStore {
98101
* MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
99102
* MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
100103
* MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
101-
* MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
104+
* MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted.
102105
* MBED_ERROR_ITEM_NOT_FOUND No such key.
103106
*/
104107
virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL, size_t offset = 0);
105108

106109
/**
107-
* @brief Get information of a given key.
110+
* @brief Get information of a given key. The returned info contains size and flags
108111
*
109112
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
110113
* @param[out] info Returned information structure.
@@ -114,13 +117,13 @@ class FileSystemStore : public KVStore {
114117
* MBED_ERROR_FAILED_OPERATION Underlying file system failed operation.
115118
* MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
116119
* MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
117-
* MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
120+
* MBED_ERROR_INVALID_DATA_DETECTED Data is corrupted.
118121
* MBED_ERROR_ITEM_NOT_FOUND No such key.
119122
*/
120123
virtual int get_info(const char *key, info_t *info);
121124

122125
/**
123-
* @brief Remove a FileSystemStore item, given key.
126+
* @brief Remove a FileSystemStore item by given key.
124127
*
125128
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
126129
*
@@ -134,7 +137,8 @@ class FileSystemStore : public KVStore {
134137
virtual int remove(const char *key);
135138

136139
/**
137-
* @brief Start an incremental FileSystemStore set sequence.
140+
* @brief Start an incremental FileSystemStore set sequence. This operation is blocking other operations.
141+
* Any get/set/remove/iterator operation will be blocked until set_finalize is called.
138142
*
139143
* @param[out] handle Returned incremental set handle.
140144
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
@@ -151,7 +155,8 @@ class FileSystemStore : public KVStore {
151155
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
152156

153157
/**
154-
* @brief Add data to incremental FileSystemStore set sequence.
158+
* @brief Add data to incremental FileSystemStore set sequence. This operation is blocking other operations.
159+
* Any get/set/remove operation will be blocked until set_finalize is called.
155160
*
156161
* @param[in] handle Incremental set handle.
157162
* @param[in] value_data Value data to add.
@@ -180,6 +185,7 @@ class FileSystemStore : public KVStore {
180185

181186
/**
182187
* @brief Start an iteration over FileSystemStore keys.
188+
* There are no issues with any other operations while iterator is open.
183189
*
184190
* @param[out] it Returned iterator handle.
185191
* @param[in] prefix Key prefix (null for all keys).
@@ -192,6 +198,7 @@ class FileSystemStore : public KVStore {
192198

193199
/**
194200
* @brief Get next key in iteration.
201+
* There are no issues with any other operations while iterator is open.
195202
*
196203
* @param[in] it Iterator handle.
197204
* @param[in] key Buffer for returned key.

‎features/storage/kvstore/global_api/kvstore_global_api.h

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ typedef struct info {
6363
int kv_set(const char *full_name_key, const void *buffer, size_t size, uint32_t create_flags);
6464

6565
/**
66-
* @brief Get one KVStore item, given key.
66+
* @brief Get one KVStore item by given key.
6767
*
6868
* @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
6969
* @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
7575
int kv_get(const char *full_name_key, void *buffer, size_t buffer_size, size_t *actual_size);
7676

7777
/**
78-
* @brief Get information of a given key.
78+
* @brief Get information of a given key.The returned info contains size and flags
7979
*
8080
* @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
8181
* @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 *
8585
int kv_get_info(const char *full_name_key, kv_info_t *info);
8686

8787
/**
88-
* @brief Remove a KVStore item, given key.
88+
* @brief Remove a KVStore item by given key.
8989
*
9090
* @param[in] full_name_key /Partition_path/Key. Must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
9191
*
@@ -95,7 +95,8 @@ int kv_remove(const char *full_name_key);
9595

9696
/**
9797
* @brief Start an iteration over KVStore keys to find all the entries
98-
* that fit the full_prefix
98+
* that fit the full_prefix. There are no issues with any other operations while
99+
* iterator is open.
99100
*
100101
* @param[out] it Allocating iterator handle.
101102
* Do not forget to call kv_iterator_close
@@ -109,7 +110,8 @@ int kv_remove(const char *full_name_key);
109110
int kv_iterator_open(kv_iterator_t *it, const char *full_prefix);
110111

111112
/**
112-
* @brief Get next key in iteration that matches the prefix.
113+
* @brief Get next key in iteration that matches the prefix. There are no issues with any
114+
* other operations while iterator is open.
113115
*
114116
* @param[in] it Iterator handle.
115117
* @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);
129131
int kv_iterator_close(kv_iterator_t it);
130132

131133
/**
132-
* @brief Remove all keys and related data
134+
* @brief Remove all keys and related data from a specified partition.
133135
*
134136
* @param[in] kvstore_path /Partition/
135137
*

‎features/storage/kvstore/kv_map/KVMap.h

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -144,10 +144,11 @@ class KVMap : private mbed::NonCopyable<KVMap> {
144144
/**
145145
* @brief Full name lookup, and then break it into KVStore instance and key
146146
*
147-
* @param full_name String parameter contains the /partition name/key.
148-
* @param kv_instance The main KVStore instance associated with the required partition name.
149-
* @param key_index An index to the first character of the key.
150-
* @param flags_mask Return the flag masking for the current configuration
147+
* @param[in] full_name String parameter contains the partition name to look for.
148+
* The String should be formated as follow "/partition name/key". The key is optional.
149+
* @param[out] kv_instance Returns the main KVStore instance associated with the required partition name.
150+
* @param[out] key_index Returns an index to the first character of the key.
151+
* @param[out] flags_mask Return the flag masking for the current configuration
151152
* @return 0 on success, negative error code on failure
152153
*/
153154
int lookup(const char *full_name, mbed::KVStore **kv_instance, size_t *key_index, uint32_t *flags_mask = NULL);
@@ -211,7 +212,7 @@ class KVMap : private mbed::NonCopyable<KVMap> {
211212
private:
212213

213214
/**
214-
* @brief Deinitialize all components of a partition configuration struct.
215+
* @brief Deinitialize all components of a partition configuration struct.
215216
*
216217
* @param partition Partition configuration struct.
217218
*/
@@ -220,9 +221,9 @@ class KVMap : private mbed::NonCopyable<KVMap> {
220221
/**
221222
* @brief Full name lookup, and then break it into KVStore config and key
222223
*
223-
* @param full_name String parameter contains the /partition name/key.
224-
* @param kv_config The configuration struct associated with the partition name
225-
* @param key_index An index to the first character of the key.
224+
* @param[in] full_name String parameter contains the /partition name/key.
225+
* @param[out] kv_config Returns The configuration struct associated with the partition name
226+
* @param[out] key_index Returns an index to the first character of the key.
226227
* @return 0 on success, negative error code on failure
227228
*/
228229
int config_lookup(const char *full_name, kvstore_config_t **kv_config, size_t *key_index);

‎features/storage/kvstore/securestore/SecureStore.h

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ class SecureStore : public KVStore {
5353
/**
5454
* @brief Class constructor
5555
*
56-
* @param[in] underlying_kv Underlying KVStore.
57-
* @param[in] rbp_kv Rollback protect KVStore.
56+
* @param[in] underlying_kv KVStore that will hold the data.
57+
* @param[in] rbp_kv Additional KVStore used for rollback protection.
5858
*
5959
* @returns none
6060
*/
@@ -68,15 +68,16 @@ class SecureStore : public KVStore {
6868
virtual ~SecureStore();
6969

7070
/**
71-
* @brief Initialize SecureStore
71+
* @brief Initialize SecureStore class. It will also initialize
72+
* the underlying KVStore and the rollback protection KVStore.
7273
*
7374
* @returns MBED_SUCCESS Success.
7475
* or any other error from underlying KVStore instances.
7576
*/
7677
virtual int init();
7778

7879
/**
79-
* @brief Deinitialize SecureStore
80+
* @brief Deinitialize SecureStore class, free handles and memory allocations.
8081
*
8182
* @returns MBED_SUCCESS Success.
8283
* or any other error from underlying KVStore instances.
@@ -100,7 +101,8 @@ class SecureStore : public KVStore {
100101
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
101102
* @param[in] buffer Value data buffer.
102103
* @param[in] size Value data size.
103-
* @param[in] create_flags Flag mask.
104+
* @param[in] create_flags Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG|
105+
* REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG
104106
*
105107
* @returns MBED_SUCCESS Success.
106108
* MBED_ERROR_NOT_READY Not initialized.
@@ -141,7 +143,7 @@ class SecureStore : public KVStore {
141143
* @brief Get information of a given key.
142144
*
143145
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
144-
* @param[out] info Returned information structure.
146+
* @param[out] info Returned information structure containing size and flags.
145147
*
146148
* @returns MBED_SUCCESS Success.
147149
* MBED_ERROR_NOT_READY Not initialized.
@@ -173,12 +175,14 @@ class SecureStore : public KVStore {
173175

174176

175177
/**
176-
* @brief Start an incremental KVStore set sequence.
178+
* @brief Start an incremental KVStore set sequence. This operation is blocking other operations.
179+
* Any get/set/remove/iterator operation will be blocked until set_finalize is called.
177180
*
178181
* @param[out] handle Returned incremental set handle.
179182
* @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
180183
* @param[in] final_data_size Final value data size.
181-
* @param[in] create_flags Flag mask.
184+
* @param[in] create_flags Flag mask - WRITE_ONCE_FLAG|REQUIRE_CONFIDENTIALITY_FLAG|
185+
* REQUIRE_INTEGRITY_FLAG|REQUIRE_REPLAY_PROTECTION_FLAG
182186
*
183187
* @returns MBED_SUCCESS Success.
184188
* MBED_ERROR_NOT_READY Not initialized.
@@ -192,7 +196,8 @@ class SecureStore : public KVStore {
192196
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
193197

194198
/**
195-
* @brief Add data to incremental KVStore set sequence.
199+
* @brief Add data to incremental KVStore set sequence. This operation is blocking other operations.
200+
* Any get/set/remove operation will be blocked until set_finalize is called.
196201
*
197202
* @param[in] handle Incremental set handle.
198203
* @param[in] value_data value data to add.
@@ -223,6 +228,7 @@ class SecureStore : public KVStore {
223228

224229
/**
225230
* @brief Start an iteration over KVStore keys.
231+
* There are no issue with any other operation while iterator is open.
226232
*
227233
* @param[out] it Returned iterator handle.
228234
* @param[in] prefix Key prefix (null for all keys).
@@ -236,6 +242,7 @@ class SecureStore : public KVStore {
236242

237243
/**
238244
* @brief Get next key in iteration.
245+
* There are no issue with any other operation while iterator is open.
239246
*
240247
* @param[in] it Iterator handle.
241248
* @param[in] key Buffer for returned key.

0 commit comments

Comments
 (0)