Skip to content

Commit 28992b6

Browse files
author
Offir Kochalsky
authored
Merge pull request #1 from ARMmbed/offir-example-kvstore
KVStore Example - Global API
2 parents 42c1dc0 + 5caa68c commit 28992b6

File tree

5 files changed

+312
-1
lines changed

5 files changed

+312
-1
lines changed

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.build
2+
.mbed
3+
projectfiles
4+
*.py*

‎README.md

100644100755
Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,152 @@
1-
# mbed-os-example-kvstore
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.
4+
5+
KVStore is a key-value storage based API over a block device.
6+
Mbed-OS provides several KVStore implementation options, that can be optimized to
7+
the specific application requirements and target hardware:
8+
- 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.
9+
- FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API.
10+
- 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 providing storage for the CMACs that protect KV pairs stored in the KVStore.
11+
12+
KVStore Global APIs use Mbed-OS [KVStore configuration](#kvstore-configuration) json file to define the selected KVStore implementation option of the above.
13+
14+
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/blob/master/docs/design-documents/features/storage/KVStore/KVStore_design.md).
15+
16+
**Table of contents:**
17+
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
28+
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.
30+
31+
The example contains an [mbed_app.json](./mbed_app.json) configuration file that demonstrates how to set KVStore configuration for a specific target (K64F) that may override the [default configuration](#kvstore-configuration).
32+
33+
## Hardware requirements
34+
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
41+
42+
## Usage
43+
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 115200 bit/s.
104+
You may open serial term with:
105+
```
106+
mbed sterm -b 115200 -r
107+
```
108+
109+
Expected output:
110+
111+
```
112+
--- Mbed OS KVStore static API example ---
113+
kv_reset
114+
kv_reset -> 0
115+
kv_set first dummy key
116+
kv_set -> 0
117+
kv_get_info of first key
118+
kv_get_info -> 0
119+
kv_get_info key: /kv/dummy_key1
120+
kv_get_info info - size: 31, flags: 0
121+
kv_get first key
122+
kv_get -> 0
123+
kv_get key: /kv/dummy_key1
124+
kv_get value: kvstore_dummy_value_hello_world
125+
kv_set second dummy key
126+
kv_set -> 0
127+
kv_set third key with Confidentiality, Integrity and Replay Protection flags
128+
kv_set -> 0
129+
kv_set Set 'Real' Key 1
130+
kv_set -> 0
131+
kv_set Set 'Real' Key 2 with flag write-once
132+
kv_set -> 0
133+
Removing 'Dummy' Keys
134+
1) Removing dummy_key1
135+
2) Removing dummy_key2
136+
3) Removing dummy_auth_enc_key
137+
Remaining with 'Real' Keys:
138+
1) real_wo_key
139+
2) real_key1
140+
kv_remove write-once file - should fail!
141+
kv_remove -> 274
142+
kv_reset format kvstore (including write-once)
143+
kv_reset -> 0
144+
```
145+
146+
#### Troubleshooting
147+
148+
If you have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html)
149+
for suggestions on what could be wrong and how to fix it.
150+
151+
## KVStore Configuration
152+
The Global KVStore API options can be set up in the higher level Mbes-OS KVSTore retargetting layer [json configuration](https://github.com/ARMmbed/mbed-os/blob/master/features/storage/kvstore/conf/mbed_lib.json)

‎main.cpp

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
/* Copyright (c) 2018 Arm Limited
2+
*
3+
* SPDX-License-Identifier: Apache-2.0
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
#include "mbed.h"
19+
#include <stdio.h>
20+
#include <string.h>
21+
#include "KVStore.h"
22+
#include "kvstore_global_api.h"
23+
24+
using namespace mbed;
25+
26+
#define EXAMPLE_KV_VALUE_LENGTH 64
27+
#define EXAMPLE_KV_KEY_LENGTH 32
28+
#define err_code(res) MBED_GET_ERROR_CODE(res)
29+
30+
void kv_store_global_api_example();
31+
32+
int main()
33+
{
34+
/* KV Store Static API Example */
35+
kv_store_global_api_example();
36+
}
37+
38+
void kv_store_global_api_example()
39+
{
40+
char kv_value_in[EXAMPLE_KV_VALUE_LENGTH] = {"kvstore_dummy_value_hello_world"};
41+
char kv_key_in[EXAMPLE_KV_KEY_LENGTH] = {"/kv/dummy_key1"};
42+
char kv_key_out[EXAMPLE_KV_KEY_LENGTH] = {0};
43+
size_t actual_size = 0;
44+
45+
/* key information container */
46+
kv_info_t info;
47+
48+
/* kv store iterator */
49+
kv_iterator_t kvstore_it;
50+
51+
int i_ind = 0;
52+
53+
printf("--- Mbed OS KVStore static API example ---\n");
54+
55+
int res = MBED_ERROR_NOT_READY;
56+
57+
/* Start By Resetting the KV Storage */
58+
printf("kv_reset\n");
59+
res = kv_reset("/kv/");
60+
printf("kv_reset -> %d\n", err_code(res));
61+
62+
/* Set First 'Dummy' Key/Value pair with unprotected clear value data */
63+
printf("kv_set first dummy key\n");
64+
res = kv_set(kv_key_in, kv_value_in, strlen(kv_value_in), 0);
65+
printf("kv_set -> %d\n", err_code(res));
66+
67+
/* Read the KV Pair you've just set */
68+
/* Start by getting key's information */
69+
printf("kv_get_info of first key\n");
70+
res = kv_get_info(kv_key_in, &info);
71+
printf("kv_get_info -> %d\n", err_code(res));
72+
printf("kv_get_info key: %s\n", kv_key_in);
73+
printf("kv_get_info info - size: %u, flags: %lu\n", info.size, info.flags);
74+
75+
/* Now that you know the data value size of this key,
76+
* allocate a buffer with matching size and get the value data */
77+
printf("kv_get first key\n");
78+
char *kv_first_value_out = new char[info.size+1];
79+
memset(kv_first_value_out, 0, info.size+1);
80+
res = kv_get(kv_key_in, kv_first_value_out, info.size, &actual_size);
81+
printf("kv_get -> %d\n", err_code(res));
82+
printf("kv_get key: %s\n", kv_key_in);
83+
printf("kv_get value: %s\n", kv_first_value_out);
84+
delete[] kv_first_value_out;
85+
86+
/* Lets set some more 'Dummy' and 'Real' KV pairs */
87+
/* Set 'Dummy' Key2 */
88+
printf("kv_set second dummy key \n");
89+
res = kv_set("/kv/dummy_key2", "dummy_value2", strlen("dummy_value2"), 0);
90+
printf("kv_set -> %d\n", err_code(res));
91+
92+
/* Set an authenticated-encrypted 'Dummy' key with Replay protection */
93+
printf("kv_set third key with Confidentiality, Integrity and Replay Protection flags\n");
94+
res = kv_set("/kv/dummy_auth_enc_key", "auth_enc_value", strlen("auth_enc_value"),
95+
KV_REQUIRE_CONFIDENTIALITY_FLAG|KV_REQUIRE_INTEGRITY_FLAG|KV_REQUIRE_REPLAY_PROTECTION_FLAG);
96+
printf("kv_set -> %d\n", err_code(res));
97+
98+
/* Set 2 non-dummy 'Real' KV pairs */
99+
/* Set 'Real' Key 1 */
100+
printf("kv_set Set 'Real' Key 1\n");
101+
res = kv_set("/kv/real_key1", "real_value1", strlen("real_value1"), 0);
102+
printf("kv_set -> %d\n", err_code(res));
103+
/* Set 'Real' Write-Once Key2 for a key that you do not want to be removed */
104+
printf("kv_set Set 'Real' Key 2 with flag write-once\n");
105+
res = kv_set("/kv/real_wo_key", "real_wo_value", strlen("real_wo_value"), KV_WRITE_ONCE_FLAG);
106+
printf("kv_set -> %d\n", err_code(res));
107+
108+
/* Now lets remove all of the 'Dummy' Keys and remain with the 'Real' ones */
109+
printf("Removing 'Dummy' Keys\n");
110+
/* Iterate and remove Keys that start with prefix 'dummy' */
111+
res = kv_iterator_open(&kvstore_it, "dummy");
112+
memset(kv_key_out, 0, EXAMPLE_KV_KEY_LENGTH);
113+
while (kv_iterator_next(kvstore_it, kv_key_out, EXAMPLE_KV_KEY_LENGTH) != MBED_ERROR_ITEM_NOT_FOUND) {
114+
i_ind++;
115+
printf("%d) Removing %s\n", i_ind, kv_key_out);
116+
kv_remove(kv_key_out);
117+
memset(kv_key_out, 0, EXAMPLE_KV_KEY_LENGTH);
118+
}
119+
res = kv_iterator_close(kvstore_it);
120+
printf("Remaining with 'Real' Keys:\n");
121+
/* Iterate on all remaining Keys */
122+
res = kv_iterator_open(&kvstore_it, NULL);
123+
memset(kv_key_out, 0, EXAMPLE_KV_KEY_LENGTH);
124+
i_ind = 0;
125+
while (kv_iterator_next(kvstore_it, kv_key_out, EXAMPLE_KV_KEY_LENGTH) != MBED_ERROR_ITEM_NOT_FOUND) {
126+
i_ind++;
127+
printf("%d) %s\n", i_ind, kv_key_out);
128+
memset(kv_key_out, 0, EXAMPLE_KV_KEY_LENGTH);
129+
}
130+
res = kv_iterator_close(kvstore_it);
131+
132+
/* Try to remove write-once Key - should fail */
133+
printf("kv_remove write-once file - should fail!\n");
134+
res = kv_remove("/kv/real_wo_key");
135+
printf("kv_remove -> %d\n", err_code(res));
136+
137+
/* Finally, reset will format kvstore and remove All Keys (including write-once keys) */
138+
printf("kv_reset format kvstore (including write-once)\n");
139+
res = kv_reset("/kv/");
140+
printf("kv_reset -> %d\n", err_code(res));
141+
142+
return;
143+
}

‎mbed-os.lib

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
https://github.com/davidsaada/mbed-os/#a6a5788d1add64282cd0b50dec8f5b9e2b831cd6

‎mbed_app.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"target_overrides": {
3+
"K64F": {
4+
"storage.storage_type": "TDB_INTERNAL"
5+
},
6+
"*": {
7+
"platform.stdio-baud-rate": 115200,
8+
"platform.default-serial-baud-rate": 115200,
9+
"platform.stdio-convert-newlines": 1
10+
}
11+
}
12+
}

0 commit comments

Comments
 (0)