Coder Social home page Coder Social logo

mbed-os-example-kvstore's Introduction

Getting started with the Mbed OS Key Value Store Global API

This example demonstrates how to use the Mbed OS Key Value Storage Global API.

KVStore is a key-value storage based API over a block device. Mbed OS provides several KVStore implementation options, that can be optimized to the specific application requirements and target hardware:

  • 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.
  • FileSystemStore - Class that provides a key-value store API on top of a POSIX-like file system API.
  • 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.

KVStore Global APIs use Mbed OS KVStore configuration json file to define the selected KVStore implementation option of the above.

Note: The example is by default set to be used on K64F target with internal memory (see: mbed_app.json). If running in another target, make sure the target.json for the target includes the "components": ["FLASHIAP"] and device_has": ["FLASH"] or add this section to the example mbed_app.json.

You can find more information about Mbed OS Key Value Store Design and other related items in the kvstore design documentation.

Table of contents:

  1. Scenario
  2. Hardware Requirements
  3. License and contributions
  4. Usage
  5. Default Global KVStore Configuration

Scenario

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.

The example contains an mbed_app.json configuration file that demonstrates how to set KVStore configuration for a specific target (K64F) that may override the default configuration.

Hardware requirements

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.

  1. TDB_INTERNAL - may run on top of flash Block Device only (typically internal flash)
  2. TDB_EXTERNAL - requires external flash for the key/value storage and typically internal flash for its replay protection storage.
  3. TDB_EXTERNAL_NO_RBP - requires external flash for the key/value storage
  4. FILESYSTEM - may use either flash or SD card for the key/value storage and typically internal flash for its replay protection storage.
  5. FILESYSTEM_NO_RBP - may use either flash or SD card for the key/value storage

License and contributions

The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info.

This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide

Usage

Import the example

Make sure you have an Mbed development environment set up. Get started with Mbed OS to set everything up.

From the command-line, import the example:

mbed import mbed-os-example-kvstore
cd mbed-os-example-kvstore

Compile the example

Invoke mbed compile, and specify the name of your platform and your favorite toolchain (GCC_ARM, ARM, IAR). For example, for the ARM Compiler 5:

mbed compile -m K64F -t ARM

Your PC may take a few moments to compile your code. At the end, you'll see a result similar to:

[snip]
+--------------------------+-------+-------+-------+
| Module                   | .text | .data |  .bss |
+--------------------------+-------+-------+-------+
| [fill]                   |   235 |     4 |   345 |
| [lib]/c.a                | 31247 |  2472 |    89 |
| [lib]/gcc.a              |  3112 |     0 |     0 |
| [lib]/misc               |   204 |     4 |    28 |
| [lib]/nosys.a            |    32 |     0 |     0 |
| main.o                   |  1719 |     0 |     0 |
| mbed-os/cmsis            |  1029 |     0 |    84 |
| mbed-os/components       |  4161 |     0 |    48 |
| mbed-os/drivers          |  1487 |     0 |   100 |
| mbed-os/features         | 42061 |     4 |  1426 |
| mbed-os/hal              |  2043 |     4 |    68 |
| mbed-os/platform         |  3095 |   260 |   134 |
| mbed-os/rtos             |  7804 |   168 |  5969 |
| mbed-os/targets          | 15561 |    12 |   413 |
| Subtotals                |113790 |  2928 |  8704 |
+--------------------------+-------+-------+-------+
Total Static RAM memory (data + bss): 11632(+0) bytes
Total Flash memory (text + data): 116718(+0) bytes

Image: ./BUILD/K64F/ARM/mbed-os-example-kvstore.bin

Run the example

  1. Connect your Mbed Enabled device to the computer over USB.
  2. Copy the binary file to the Mbed Enabled device.
  3. Press the reset button to start the program.
  4. Open the UART of the board in your favorite UART viewing program. For example, screen /dev/ttyACM0.

Note: The default serial port baud rate is 9600 bit/s. You may open serial term with:

mbed sterm -b 9600 -r

Expected output:

--- Mbed OS KVStore static API example ---
kv_reset
kv_reset -> 0
kv_set first dummy key
kv_set -> 0
kv_get_info of first key
kv_get_info -> 0
kv_get_info key: /kv/dummy_key1
kv_get_info info - size: 31, flags: 0
kv_get first key
kv_get -> 0
kv_get key: /kv/dummy_key1
kv_get value: kvstore_dummy_value_hello_world
kv_set second dummy key
kv_set -> 0
kv_set third key with Confidentiality, Integrity and Replay Protection flags
kv_set -> 0
kv_set Set 'Real' Key 1
kv_set -> 0
kv_set Set 'Real' Key 2 with flag write-once
kv_set -> 0
Removing 'Dummy' Keys
1) Removing dummy_key1
2) Removing dummy_key2
3) Removing dummy_auth_enc_key
Remaining with 'Real' Keys:
1) real_wo_key
2) real_key1
kv_remove write-once file - should fail!
kv_remove -> 274
kv_reset format kvstore (including write-once)
kv_reset -> 0

Troubleshooting

If you have problems, you can review the documentation for suggestions on what could be wrong and how to fix it.

KVStore Configuration

The Global KVStore API options can be set up in the higher level Mbed OS KVSTore retargetting layer json configuration

mbed-os-example-kvstore's People

Contributors

0xc0170 avatar adbridge avatar evedon avatar gpsimenos avatar hugueskamba avatar ldong-arm avatar mbedmain avatar patater avatar rajkan01 avatar rwalton-arm avatar saheerb avatar urutva avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

mbed-os-example-kvstore's Issues

LPC55S69_NS hung on kv_reset

I am trying to test storage type TDB_EXTERNAL and FILESYSTEM, but the system just hung on kv_reset without any error message.
ex. TDB_INTERNAL working perfectly.

Example version: mbed-os-5.12.0-rc4 - 1722b9c
OS: Linux Mint 19.1
Board: LPC55S69_NS
Compiler: GCC_ARM (8-2018-q4-major)
Build command: mbed compile -t GCC_ARM -m LPC55S69_NS

Test output:
--- Mbed OS KVStore static API example ---
kv_reset

NRF52840_DK - Operator new[] out of memory

This example builds with storage type TDB_EXTERNAL without errors, but reboots in a loop due to a fatal error ("Operator new[] out of memory") when run.
Example version: mbed-os-5.11.0-rc2 - d9625811c9193ac3ab36a969bab93e28dac03776
OS: Windows 10
Compiler: GCC_ARM
Board: NRF52840_DK

Test output:

--- Mbed OS KVStore static API example ---
kv_reset
kv_reset -> 271
kv_set first dummy key
kv_set -> 271
kv_get_info of first key
kv_get_info -> 271
kv_get_info key: /kv/dummy_key1
kv_get_info info - size: 1879048192, flags: 536889856
kv_get first key


++ MbedOS Error Info ++
Error Status: 0x8001011F Code: 287 Module: 1
Error Message: Operator new[] out of memory

Location: 0x352C1
Error Value: 0x70000001
Current Thread: main  Id: 0x2000577C Entry: 0x35829 StackSize: 0x1000 StackMem: 0x200057C0 SP: 0x200066A8
For more info, visit: https://armmbed.github.io/mbedos-error/?error=0x8001011F
-- MbedOS Error Info --

== The system has been rebooted due to a fatal error. ==

[OoB 5.13] Improved steps in Run the example section in README.md

Hi, this issue is related to Mbed OS 5.13 OoB campaign.

In the current steps, run the program first by pushing the reset button, then connect serial port. With this order, user would miss the messages from serial port.

I suggest connecting serial port first, then run the program by pushing the reset button.

External TDB Requires Device ROT

Description of defect

Initially posted here: ARMmbed/mbed-os#13327

After testing, it seems that it is necessary to call DeviceKey::get_instance().device_inject_root_of_trust() before using kv store in external TBD mode (either with RBP or without). It would be helpful to update this example to include that.

Target(s) affected by this defect ?

N/A

Toolchain(s) (name and version) displaying this defect ?

N/A

What version of Mbed-os are you using (tag or sha) ?

N/A

What version(s) of tools are you using. List all that apply (E.g. mbed-cli)

N/A

How is this defect reproduced ?

Using kv store in external TBD mode

NRF52840_DK does not work by default

This example builds for the NRF52840 without errors but gets stuck in a loop removing files when run.
Example version: mbed-os-5.11.0-rc2 - 1bdc298
OS: Windows 10
Compiler: armcc
Board: NRF52840_DK

Test output:

> mbed compile -t ARM -m NRF52840_DK -f
...
> mbed sterm -b 115200 -r
[mbed] Detecting connected targets/boards to your system...
[mbed] Opening serial terminal to "NRF52840_DK"
--- Terminal on COM326 - 115200,8,N,1 ---
���j
9625) Re�--- Mbed OS KVStore static API example ---
kv_reset
kv_reset -> 265
kv_set first dummy key
kv_set -> 265
kv_get_info of first key
kv_get_info -> 265
kv_get_info key: /kv/dummy_key1
kv_get_info info - size: 0, flags: 139895
kv_get first key
kv_get -> 265
kv_get key: /kv/dummy_key1
kv_get value:
kv_set second dummy key
kv_set -> 265
kv_set third key with Confidentiality, Integrity and Replay Protection flags
kv_set -> 265
kv_set Set 'Real' Key 1
kv_set -> 265
kv_set Set 'Real' Key 2 with flag write-once
kv_set -> 265
Removing 'Dummy' Keys
1) Removing
2) Removing
3) Removing
4) Removing
5) Removing
6) Removing
7) Removing
8) Removing
9) Removing
...

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.