Skip to content

Commit c8eb726

Browse files
author
Offir Kochalsky
committed
Global KVStore Example Only
1 parent 07683b0 commit c8eb726

File tree

8 files changed

+130
-554
lines changed

8 files changed

+130
-554
lines changed

‎README.md

Lines changed: 129 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,148 @@
1-
# Getting started with the Mbed OS Key Value Store API
1+
# Getting started with the Mbed OS Key Value Store Global API
2+
3+
This example demonstrates how to use the Mbed OS Key Value Storage Global API.
24

3-
This example demonstrates how to use the Mbed OS Key Value Storage (KVStore) API.
45
KVStore is a key-value storage based API over a block device.
56
Mbed-OS provides several KVStore implementation options, that can be optimized to
67
the specific application requirements and target hardware:
78
- TDBStore - Default implementation of the KVStore API. It provides static wear-leveling and quick access for when you have a small number of KV pairs.
89
- FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API.
910
- SecureStore - Class that provides encryption, authentication and rollback protection on top of the KVStore API. It requires two KVStore implementations, one that provides the storage for the KV pairs and one that provides storage for the CMACs that protect KV pairs stored in the KVStore.
1011

12+
KVStore Global APIs use Mbed-OS [KVStore configuration](#kvstore-configuration) json file to define the selected KVStore implementation option of the above.
13+
1114
You can find more information about Mbed OS Key Value Store Design and other related items in the [kvstore design documentation](https://github.com/ARMmbed/mbed-os/tree/master/docs/design-documents/features/storage/KVStore/KVStore_design.md).
1215

1316
**Table of contents:**
1417

15-
1. [Working with KVStore Class-vs-Global APIs](#working-wit-kvstor)
16-
2. [Examples Class/Global APIs](#examples-global/class-apis)
17-
2. [Hardware requirements](#hardware-requirements)
18+
1. [Scenario](#scenario)
19+
2. [Hardware Requirements](#hardware-requirements)
20+
3. [Usage](#usage)
21+
- [Import the example](#import-the-example)
22+
- [Compile the example](#compile-the-example)
23+
- [Run the example](#run-the-example)
24+
- [Troubleshooting](#troubleshooting)
25+
4. [Default Global KVStore Configuration](#kvstore-configuration)
26+
27+
## Scenario
1828

19-
## Working with KVStore
29+
The example sets several key/value pairs, some are defined as 'dummy' and some as 'real'. The example demonstrates several possible scenarios that set, get, search and remove specific keys, and iterate all keys.
2030

21-
There are two main options for building a KVStore solution and working with it:
22-
1. Option A: Use Mbed-OS [KVStore configuration](#kvstore-configuration) json file to define your selected KVStore implementation.
23-
2. Option B: Build your own KVStore solution by directly defining the class modules that best fit your applicatio0n and hardware (either TDBStore, FileSystemStore or SecureStore)
31+
The example contains an [mbed-lib.json](./mbed-lib.json) configuration file that demonstrates how to set KVStore configuration for a specific target (K64F) that may override the [default configuration](#kvstore-configuration).
2432

25-
Each of the above options has its own set of API functions:
26-
1. Option A: Global APIs - using the higher level static retargetting layer APIs, which rely on [KVStore configuration](#kvstore-configuration)
27-
2. Option B: Class APIs - directly calling the APIs of KVStore class on the implementing class instance (either TDBStore, FileSystemStore or SecureStore)
33+
## Hardware requirements
2834

29-
## Examples Global/Class APIs
35+
KVStore general API may use several types of key/value storage classes, according to the configuration, that run on top of an underlying Block Device. Each type has different HW requirements for the underlying Block Device.
36+
1. TDB_INTERNAL - may run on top of flash Block Device only (typically internal flash)
37+
2. TDB_EXTERNAL - requires external flash for the key/value storage and typically internal flash for its replay protection storage.
38+
3. TDB_EXTERNAL_NO_RBP - requires external flash for the key/value storage
39+
4. FILESYSTEM - may use either flash or SD card for the key/value storage and typically internal flash for its replay protection storage.
40+
5. FILESYSTEM_NO_RBP - may use either flash or SD card for the key/value storage
3041

31-
Each of the Options above has its own example:
32-
1. Example A: [Global APIs Example](./kvstore_global/README_KVStore_global.md)
33-
2. Example B: [Class APIs Example](./kvstore_api/README_KVStore_api.md)
42+
## Usage
3443

35-
## Hardware requirements
44+
#### Import the example
45+
46+
Make sure you have an Mbed development environment set up. [Get started with Mbed OS](https://os.mbed.com/docs/latest/tutorials/your-first-program.html)
47+
to set everything up.
48+
49+
From the command-line, import the example:
50+
51+
```
52+
mbed import mbed-os-example-kvstore
53+
cd mbed-os-example-kvstore
54+
```
55+
56+
#### Compile the example
57+
58+
Invoke `mbed compile`, and specify the name of your platform and your favorite
59+
toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5:
60+
61+
```
62+
mbed compile -m K64F -t ARM
63+
```
64+
65+
Your PC may take a few moments to compile your code. At the end, you'll see a
66+
result similar to:
67+
68+
```
69+
[snip]
70+
+--------------------------+-------+-------+-------+
71+
| Module | .text | .data | .bss |
72+
+--------------------------+-------+-------+-------+
73+
| [fill] | 235 | 4 | 345 |
74+
| [lib]/c.a | 31247 | 2472 | 89 |
75+
| [lib]/gcc.a | 3112 | 0 | 0 |
76+
| [lib]/misc | 204 | 4 | 28 |
77+
| [lib]/nosys.a | 32 | 0 | 0 |
78+
| main.o | 1719 | 0 | 0 |
79+
| mbed-os/cmsis | 1029 | 0 | 84 |
80+
| mbed-os/components | 4161 | 0 | 48 |
81+
| mbed-os/drivers | 1487 | 0 | 100 |
82+
| mbed-os/features | 42061 | 4 | 1426 |
83+
| mbed-os/hal | 2043 | 4 | 68 |
84+
| mbed-os/platform | 3095 | 260 | 134 |
85+
| mbed-os/rtos | 7804 | 168 | 5969 |
86+
| mbed-os/targets | 15561 | 12 | 413 |
87+
| Subtotals |113790 | 2928 | 8704 |
88+
+--------------------------+-------+-------+-------+
89+
Total Static RAM memory (data + bss): 11632(+0) bytes
90+
Total Flash memory (text + data): 116718(+0) bytes
91+
92+
Image: ./BUILD/K82F/GCC_ARM/kvstore.bin
93+
```
94+
95+
#### Run the example
96+
97+
1. Connect your Mbed Enabled device to the computer over USB.
98+
1. Copy the binary file to the Mbed Enabled device.
99+
1. Press the reset button to start the program.
100+
1. Open the UART of the board in your favorite UART viewing program. For
101+
example, `screen /dev/ttyACM0`.
102+
103+
**Note:** The default serial port baud rate is 9600 bit/s.
104+
105+
Expected output:
106+
107+
```
108+
--- Mbed OS KVStore static API example ---
109+
kv_reset
110+
kv_reset -> 0
111+
kv_set first dummy key
112+
kv_set -> 0
113+
kv_get_info of first key
114+
kv_get_info -> 0
115+
kv_get_info key: /kv/dummy_key1
116+
kv_get_info info - size: 31, flags: 0
117+
kv_get first key
118+
kv_get -> 0
119+
kv_get key: /kv/dummy_key1
120+
kv_get value: kvstore_dummy_value_hello_world
121+
kv_set second dummy key
122+
kv_set -> 0
123+
kv_set third key with Confidentiality, Integrity and Replay Protection flags
124+
kv_set -> 0
125+
kv_set Set 'Real' Key 1
126+
kv_set -> 0
127+
kv_set Set 'Real' Key 2 with flag write-once
128+
kv_set -> 0
129+
Removing 'Dummy' Keys
130+
1) Removing dummy_key1
131+
2) Removing dummy_key2
132+
3) Removing dummy_auth_enc_key
133+
Remaining with 'Real' Keys:
134+
1) real_wo_key
135+
2) real_key1
136+
kv_remove write-once file - should fail!
137+
kv_remove -> 274
138+
kv_reset format kvstore (including write-once)
139+
kv_reset -> 0
140+
```
141+
142+
#### Troubleshooting
143+
144+
If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html)
145+
for suggestions on what could be wrong and how to fix it.
36146

37-
This example uses several types of key/value storage classes that run on top of an underlying Block Device. Each type has different HW requirements for the underlying Block Device.
38-
1. TDBStore - may run on top of Flash Block Device only
39-
2. FileSystemStore - may run on top of either Flash or SD card Block Device
40-
3. SecureStore - may run on either TDBStore or FileSystemStore for underlying storage and requires TDBStore for its rollback protection storage.
147+
## Default Global KVStore Configuration
148+
The Global KVStore APIs rely on the higher level Mbes-OS KVSTore retargetting layer [json configuration]()

‎kvstore_api/README_KVStore_api.md

Lines changed: 0 additions & 205 deletions
This file was deleted.

0 commit comments

Comments
 (0)