Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TDBStore.h
1 /*
2  * Copyright (c) 2018 ARM Limited. All rights reserved.
3  * SPDX-License-Identifier: Apache-2.0
4  * Licensed under the Apache License, Version 2.0 (the License); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef MBED_TDBSTORE_H
18 #define MBED_TDBSTORE_H
19 
20 #include <stdint.h>
21 #include <stdio.h>
22 #include "KVStore.h"
23 #include "BlockDevice.h"
24 #include "BufferedBlockDevice.h"
25 #include "PlatformMutex.h"
26 
27 namespace mbed {
28 
29 /** TDBStore class
30  *
31  * Lightweight Key Value storage over a block device
32  */
33 
34 class TDBStore : public KVStore {
35 public:
36 
37  static const uint32_t RESERVED_AREA_SIZE = 64;
38 
39  /**
40  * @brief Class constructor
41  *
42  * @param[in] bd Underlying block device. The BlockDevice
43  * can be any BlockDevice with flash characteristics.
44  * If using a BlockDevice without flash, such as SDBlockDevice,
45  * please add the FlashSimBlockDevice on top of it.
46  *
47  * @returns none
48  */
49  TDBStore(BlockDevice *bd);
50 
51  /**
52  * @brief Class destructor
53  *
54  * @returns none
55  */
56  virtual ~TDBStore();
57 
58  /**
59  * @brief Initialize TDBStore. If data exists, TDBStore will check the data integrity
60  * on initialize. If the integrity checks fails, the TDBStore will use GC to collect
61  * the available data and clean corrupted and erroneous records.
62  *
63  * @returns MBED_SUCCESS Success.
64  * MBED_ERROR_READ_FAILED Unable to read from media.
65  * MBED_ERROR_WRITE_FAILED Unable to write to media.
66  */
67  virtual int init();
68 
69  /**
70  * @brief Deinitialize TDBStore, release and free resources.
71  *
72  * @returns MBED_SUCCESS Success.
73  */
74  virtual int deinit();
75 
76 
77  /**
78  * @brief Reset TDBStore contents (clear all keys)
79  *
80  * @returns MBED_SUCCESS Success.
81  * MBED_ERROR_NOT_READY Not initialized.
82  * MBED_ERROR_READ_FAILED Unable to read from media.
83  * MBED_ERROR_WRITE_FAILED Unable to write to media.
84  */
85  virtual int reset();
86 
87  /**
88  * @brief Set one TDBStore item, given key and value.
89  *
90  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
91  * @param[in] buffer Value data buffer.
92  * @param[in] size Value data size.
93  * @param[in] create_flags Flag mask.
94  *
95  * @returns MBED_SUCCESS Success.
96  * MBED_ERROR_NOT_READY Not initialized.
97  * MBED_ERROR_READ_FAILED Unable to read from media.
98  * MBED_ERROR_WRITE_FAILED Unable to write to media.
99  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
100  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
101  * MBED_ERROR_MEDIA_FULL Not enough room on media.
102  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
103  */
104  virtual int set(const char *key, const void *buffer, size_t size, uint32_t create_flags);
105 
106  /**
107  * @brief Get one TDBStore item by given key.
108  *
109  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
110  * @param[in] buffer Value data buffer.
111  * @param[in] buffer_size Value data buffer size.
112  * @param[out] actual_size Actual read size.
113  * @param[in] offset Offset to read from in data.
114  *
115  * @returns MBED_SUCCESS Success.
116  * MBED_ERROR_NOT_READY Not initialized.
117  * MBED_ERROR_READ_FAILED Unable to read from media.
118  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
119  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
120  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
121  * MBED_ERROR_ITEM_NOT_FOUND No such key.
122  */
123  virtual int get(const char *key, void *buffer, size_t buffer_size, size_t *actual_size = NULL,
124  size_t offset = 0);
125 
126  /**
127  * @brief Get information of a given key. The returned info contains size and flags
128  *
129  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
130  * @param[out] info Returned information structure.
131  *
132  * @returns MBED_SUCCESS Success.
133  * MBED_ERROR_NOT_READY Not initialized.
134  * MBED_ERROR_READ_FAILED Unable to read from media.
135  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
136  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
137  * MBED_ERROR_ITEM_NOT_FOUND No such key.
138  */
139  virtual int get_info(const char *key, info_t *info);
140 
141  /**
142  * @brief Remove a TDBStore item by given key.
143  *
144  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
145  *
146  * @returns MBED_SUCCESS Success.
147  * MBED_ERROR_NOT_READY Not initialized.
148  * MBED_ERROR_READ_FAILED Unable to read from media.
149  * MBED_ERROR_WRITE_FAILED Unable to write to media.
150  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
151  * MBED_ERROR_MEDIA_FULL Not enough room on media.
152  * MBED_ERROR_ITEM_NOT_FOUND No such key.
153  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
154  */
155  virtual int remove(const char *key);
156 
157 
158  /**
159  * @brief Start an incremental TDBStore set sequence. This operation is blocking other operations.
160  * Any get/set/remove/iterator operation will be blocked until set_finalize is called.
161  *
162  * @param[out] handle Returned incremental set handle.
163  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
164  * @param[in] final_data_size Final value data size.
165  * @param[in] create_flags Flag mask.
166  *
167  * @returns MBED_SUCCESS Success.
168  * MBED_ERROR_NOT_READY Not initialized.
169  * MBED_ERROR_READ_FAILED Unable to read from media.
170  * MBED_ERROR_WRITE_FAILED Unable to write to media.
171  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
172  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
173  * MBED_ERROR_MEDIA_FULL Not enough room on media.
174  * MBED_ERROR_WRITE_PROTECTED Already stored with "write once" flag.
175  */
176  virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags);
177 
178  /**
179  * @brief Add data to incremental TDBStore set sequence. This operation is blocking other operations.
180  * Any get/set/remove operation will be blocked until set_finalize will be called.
181  *
182  * @param[in] handle Incremental set handle.
183  * @param[in] value_data Value data to add.
184  * @param[in] data_size Value data size.
185  *
186  * @returns MBED_SUCCESS Success.
187  * MBED_ERROR_NOT_READY Not initialized.
188  * MBED_ERROR_WRITE_FAILED Unable to write to media.
189  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
190  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
191  */
192  virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size);
193 
194  /**
195  * @brief Finalize an incremental KVStore set sequence.
196  *
197  * @param[in] handle Incremental set handle.
198  *
199  * @returns MBED_SUCCESS Success.
200  * MBED_ERROR_NOT_READY Not initialized.
201  * MBED_ERROR_WRITE_FAILED Unable to write to media.
202  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
203  */
204  virtual int set_finalize(set_handle_t handle);
205 
206  /**
207  * @brief Start an iteration over KVStore keys.
208  * There are no issues with any other operations while iterator is open.
209  *
210  * @param[out] it Returned iterator handle.
211  * @param[in] prefix Key prefix (null for all keys).
212  *
213  * @returns MBED_SUCCESS Success.
214  * MBED_ERROR_NOT_READY Not initialized.
215  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
216  */
217  virtual int iterator_open(iterator_t *it, const char *prefix = NULL);
218 
219  /**
220  * @brief Get next key in iteration.
221  * There are no issues with any other operations while iterator is open.
222  *
223  * @param[in] it Iterator handle.
224  * @param[in] key Buffer for returned key.
225  * @param[in] key_size Key buffer size.
226  *
227  * @returns MBED_SUCCESS Success.
228  * MBED_ERROR_NOT_READY Not initialized.
229  * MBED_ERROR_READ_FAILED Unable to read from block device.
230  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
231  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
232  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
233  * MBED_ERROR_ITEM_NOT_FOUND No more keys found.
234  */
235  virtual int iterator_next(iterator_t it, char *key, size_t key_size);
236 
237  /**
238  * @brief Close iteration.
239  *
240  * @param[in] it Iterator handle.
241  *
242  * @returns MBED_SUCCESS Success.
243  * MBED_ERROR_NOT_READY Not initialized.
244  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
245  */
246  virtual int iterator_close(iterator_t it);
247 
248  /**
249  * @brief Set data in reserved area, which is a special location for special data, such as ROT.
250  * The data written to reserved area can't be overwritten.
251  *
252  * @param[in] reserved_data Reserved data buffer.
253  * @param[in] reserved_data_buf_size
254  * Reserved data buffer size.
255  *
256  * @returns MBED_SUCCESS Success.
257  * MBED_ERROR_NOT_READY Not initialized.
258  * MBED_ERROR_READ_FAILED Unable to read from media.
259  * MBED_ERROR_WRITE_FAILED Unable to write to media.
260  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
261  * MBED_ERROR_INVALID_SIZE Invalid size given in function arguments.
262  */
263  virtual int reserved_data_set(const void *reserved_data, size_t reserved_data_buf_size);
264 
265  /**
266  * @brief Get data from reserved area, which is a special location for special data, such as ROT.
267  *
268  * @param[in] reserved_data Reserved data buffer.
269  * @param[in] reserved_data_buf_size
270  * Reserved data buffer size.
271  * @param[in] actual_data_size Return data size.
272  *
273  * @returns MBED_SUCCESS Success.
274  * MBED_ERROR_NOT_READY Not initialized.
275  * MBED_ERROR_READ_FAILED Unable to read from media.
276  * MBED_ERROR_INVALID_ARGUMENT Invalid argument given in function arguments.
277  * MBED_ERROR_INVALID_DATA_DETECTED Data is corrupt.
278  * MBED_ERROR_ITEM_NOT_FOUND No reserved data was written.
279  */
280  virtual int reserved_data_get(void *reserved_data, size_t reserved_data_buf_size,
281  size_t *actual_data_size = 0);
282 
283 #if !defined(DOXYGEN_ONLY)
284 private:
285 
286  typedef struct {
287  uint32_t address;
288  size_t size;
289  } tdbstore_area_data_t;
290 
291  static const int _num_areas = 2;
292  static const int _max_open_iterators = 16;
293 
294  PlatformMutex _mutex;
295  PlatformMutex _inc_set_mutex;
296  void *_ram_table;
297  size_t _max_keys;
298  size_t _num_keys;
299  BlockDevice *_bd;
300  BufferedBlockDevice *_buff_bd;
301  uint32_t _free_space_offset;
302  uint32_t _master_record_offset;
303  uint32_t _master_record_size;
304  bool _is_initialized;
305  int _active_area;
306  uint16_t _active_area_version;
307  size_t _size;
308  tdbstore_area_data_t _area_params[_num_areas];
309  uint32_t _prog_size;
310  uint8_t *_work_buf;
311  char *_key_buf;
312  bool _variant_bd_erase_unit_size;
313  void *_inc_set_handle;
314  void *_iterator_table[_max_open_iterators];
315 
316  /**
317  * @brief Read a block from an area.
318  *
319  * @param[in] area Area.
320  * @param[in] offset Offset in area.
321  * @param[in] size Number of bytes to read.
322  * @param[in] buf Output buffer.
323  *
324  * @returns 0 for success, nonzero for failure.
325  */
326  int read_area(uint8_t area, uint32_t offset, uint32_t size, void *buf);
327 
328  /**
329  * @brief Write a block to an area.
330  *
331  * @param[in] area Area.
332  * @param[in] offset Offset in area.
333  * @param[in] size Number of bytes to write.
334  * @param[in] buf Input buffer.
335  *
336  * @returns 0 for success, non-zero for failure.
337  */
338  int write_area(uint8_t area, uint32_t offset, uint32_t size, const void *buf);
339 
340  /**
341  * @brief Reset an area (erase its start).
342  *
343  * @param[in] area Area.
344  *
345  * @returns 0 for success, nonzero for failure.
346  */
347  int reset_area(uint8_t area);
348 
349  /**
350  * @brief Erase an erase unit.
351  *
352  * @param[in] area Area.
353  * @param[in] offset Offset in area.
354  *
355  * @returns 0 for success, nonzero for failure.
356  */
357  int erase_erase_unit(uint8_t area, uint32_t offset);
358 
359  /**
360  * @brief Calculate addresses and sizes of areas.
361  */
362  void calc_area_params();
363 
364  /**
365  * @brief Read a TDBStore record from a given location.
366  *
367  * @param[in] area Area.
368  * @param[in] offset Offset of record in area.
369  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
370  * @param[in] data_buf Data buffer.
371  * @param[in] data_buf_size Data buffer size.
372  * @param[out] actual_data_size Actual data size.
373  * @param[in] data_offset Offset in data.
374  * @param[in] copy_key Copy key to user buffer.
375  * @param[in] copy_data Copy data to user buffer.
376  * @param[in] check_expected_key Check whether key belongs to this record.
377  * @param[in] calc_hash Calculate hash (on key).
378  * @param[out] hash Calculated hash.
379  * @param[out] flags Record flags.
380  * @param[out] next_offset Offset of next record.
381  *
382  * @returns 0 for success, nonzero for failure.
383  */
384  int read_record(uint8_t area, uint32_t offset, char *key,
385  void *data_buf, uint32_t data_buf_size,
386  uint32_t &actual_data_size, size_t data_offset, bool copy_key,
387  bool copy_data, bool check_expected_key, bool calc_hash,
388  uint32_t &hash, uint32_t &flags, uint32_t &next_offset);
389 
390  /**
391  * @brief Write a master record of a given area.
392  *
393  * @param[in] area Area.
394  * @param[in] version Area version.
395  * @param[out] next_offset Offset of next record.
396  *
397  * @returns 0 for success, nonzero for failure.
398  */
399  int write_master_record(uint8_t area, uint16_t version, uint32_t &next_offset);
400 
401  /**
402  * @brief Copy a record from one area to the opposite one.
403  *
404  * @param[in] from_area Area to copy record from.
405  * @param[in] from_offset Offset in source area.
406  * @param[in] to_offset Offset in destination area.
407  * @param[out] to_next_offset Offset of next record in destination area.
408  *
409  * @returns 0 for success, nonzero for failure.
410  */
411  int copy_record(uint8_t from_area, uint32_t from_offset, uint32_t to_offset,
412  uint32_t &to_next_offset);
413 
414  /**
415  * @brief Garbage collection (compact all records from active area to the standby one).
416  *
417  * @returns 0 for success, nonzero for failure.
418  */
419  int garbage_collection();
420 
421  /**
422  * @brief Return record size given key and data size.
423  *
424  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
425  * @param[in] data_size Data size.
426  *
427  * @returns record size.
428  */
429  uint32_t record_size(const char *key, uint32_t data_size);
430 
431  /**
432  * @brief Find a record given key
433  *
434  * @param[in] area Area.
435  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
436  * @param[out] offset Offset of record.
437  * @param[out] ram_table_ind Index in RAM table (target one if not found).
438  * @param[out] hash Calculated key hash.
439  *
440  * @returns 0 for success, nonzero for failure.
441  */
442  int find_record(uint8_t area, const char *key, uint32_t &offset,
443  uint32_t &ram_table_ind, uint32_t &hash);
444  /**
445  * @brief Actual logics of get API (also covers all other get APIs).
446  *
447  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
448  * @param[in] copy_data Copy data to user buffer.
449  * @param[in] data_buf Buffer to store data on.
450  * @param[in] data_buf_size Data buffer size (bytes).
451  * @param[out] actual_data_size Actual data size (bytes).
452  * @param[out] flags Flags.
453  *
454  * @returns 0 for success, nonzero for failure.
455  */
456  int do_get(const char *key, bool copy_data,
457  void *data_buf, uint32_t data_buf_size, uint32_t &actual_data_size,
458  uint32_t &flags);
459 
460  /**
461  * @brief Actual logics of set API (covers also the remove API).
462  *
463  * @param[in] key Key - must not include '*' '/' '?' ':' ';' '\' '"' '|' ' ' '<' '>' '\'.
464  * @param[in] data_buf Data buffer.
465  * @param[in] data_buf_size Data buffer size (bytes).
466  * @param[in] flags Flags.
467  *
468  * @returns 0 for success, nonzero for failure.
469  */
470  int do_set(const char *key, const void *data_buf, uint32_t data_buf_size, uint32_t flags);
471 
472  /**
473  * @brief Build RAM table and update _free_space_offset (scanning all the records in the area).
474  *
475  * @returns 0 for success, nonzero for failure.
476  */
477  int build_ram_table();
478 
479  /**
480  * @brief Increment maximum number of keys and reallocate RAM table accordingly.
481  *
482  * @param[out] ram_table Updated RAM table.
483  *
484  * @returns 0 for success, nonzero for failure.
485  */
486  int increment_max_keys(void **ram_table = 0);
487 
488  /**
489  * @brief Calculate offset from start of erase unit.
490  *
491  * @param[in] area Area.
492  * @param[in] offset Offset in area.
493  * @param[out] offset_from_start Offset from start of erase unit.
494  * @param[out] dist_to_end Distance to end of erase unit.
495  *
496  * @returns offset in erase unit.
497  */
498  void offset_in_erase_unit(uint8_t area, uint32_t offset, uint32_t &offset_from_start,
499  uint32_t &dist_to_end);
500 
501  /**
502  * @brief Check whether erase unit is erased (from offset until end of unit).
503  *
504  * @param[in] area Area.
505  * @param[in] offset Offset in area.
506  * @param[out] erased Unit is erased.
507  *
508  * @returns 0 for success, nonzero for failure.
509  */
510  int is_erase_unit_erased(uint8_t area, uint32_t offset, bool &erased);
511 
512  /**
513  * @brief Before writing a record, check whether you are crossing an erase unit.
514  * If you do, check if it's erased, and erase it if not.
515  *
516  * @param[in] area Area.
517  * @param[in] offset Offset in area.
518  * @param[in] size Write size.
519  * @param[in] force_check Force checking.
520  *
521  * @returns 0 for success, nonzero for failure.
522  */
523  int check_erase_before_write(uint8_t area, uint32_t offset, uint32_t size,
524  bool force_check = false);
525 
526  /**
527  * @brief Get data from reserved area - worker function.
528  *
529  * @param[in] reserved_data Reserved data buffer (0 to return nothing).
530  * @param[in] reserved_data_buf_size
531  * Reserved data buffer size.
532  * @param[in] actual_data_size Return data size.
533  *
534  * @returns 0 on success or a negative error code on failure
535  */
536  int do_reserved_data_get(void *reserved_data, size_t reserved_data_buf_size,
537  size_t *actual_data_size = 0);
538 
539  /**
540  * @brief Update all iterators after adding or deleting of keys.
541  *
542  * @param[in] added True if added, false if deleted.
543  * @param[in] ram_table_ind RAM table index.
544  *
545  * @returns none
546  */
547  void update_all_iterators(bool added, uint32_t ram_table_ind);
548 
549 #endif
550 
551 };
552 /** @}*/
553 
554 } // namespace mbed
555 
556 #endif
mbed::TDBStore::set_finalize
virtual int set_finalize(set_handle_t handle)
Finalize an incremental KVStore set sequence.
mbed::KVStore::info
Holds key information.
Definition: KVStore.h:48
mbed::TDBStore::~TDBStore
virtual ~TDBStore()
Class destructor.
mbed::BlockDevice
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
mbed::TDBStore::TDBStore
TDBStore(BlockDevice *bd)
Class constructor.
mbed::TDBStore::set_start
virtual int set_start(set_handle_t *handle, const char *key, size_t final_data_size, uint32_t create_flags)
Start an incremental TDBStore set sequence.
mbed::TDBStore::init
virtual int init()
Initialize TDBStore.
mbed::TDBStore::iterator_next
virtual int iterator_next(iterator_t it, char *key, size_t key_size)
Get next key in iteration.
mbed::TDBStore::iterator_open
virtual int iterator_open(iterator_t *it, const char *prefix=NULL)
Start an iteration over KVStore keys.
mbed::TDBStore::set_add_data
virtual int set_add_data(set_handle_t handle, const void *value_data, size_t data_size)
Add data to incremental TDBStore set sequence.
PlatformMutex
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
mbed::BufferedBlockDevice
Block device for allowing minimal read and program sizes (of 1) for the underlying BD...
Definition: BufferedBlockDevice.h:36
mbed::KVStore
KVStore class.
Definition: KVStore.h:30
mbed::TDBStore::deinit
virtual int deinit()
Deinitialize TDBStore, release and free resources.
mbed::TDBStore
TDBStore class.
Definition: TDBStore.h:34
mbed::TDBStore::get_info
virtual int get_info(const char *key, info_t *info)
Get information of a given key.
mbed::TDBStore::reset
virtual int reset()
Reset TDBStore contents (clear all keys)
mbed::TDBStore::reserved_data_set
virtual int reserved_data_set(const void *reserved_data, size_t reserved_data_buf_size)
Set data in reserved area, which is a special location for special data, such as ROT.
mbed::TDBStore::iterator_close
virtual int iterator_close(iterator_t it)
Close iteration.
mbed::TDBStore::reserved_data_get
virtual int reserved_data_get(void *reserved_data, size_t reserved_data_buf_size, size_t *actual_data_size=0)
Get data from reserved area, which is a special location for special data, such as ROT...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.