BA / SerialCom

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of OmniWheels by Gustav Atmel

mbed-os/features/nvstore/README.md@2:798925c9e4a8, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:55:34 2018 +0000
Revision:
2:798925c9e4a8
Parent:
1:9c5af431a1f1 
bluetooth

Who changed what in which revision?

UserRevisionLine numberNew contents of line
gustavatmel 1:9c5af431a1f1 1 # NVStore
gustavatmel 1:9c5af431a1f1 2
gustavatmel 1:9c5af431a1f1 3 NVStore is a lightweight module that stores data by keys in the internal flash for security purposes.
gustavatmel 1:9c5af431a1f1 4
gustavatmel 1:9c5af431a1f1 5 ## Description
gustavatmel 1:9c5af431a1f1 6
gustavatmel 1:9c5af431a1f1 7 NVStore provides the ability to store a minimal set of system critical items in the internal flash.
gustavatmel 1:9c5af431a1f1 8 For each item key, the NVStore module provides the ability to set the item data or get it.
gustavatmel 1:9c5af431a1f1 9 Newly added values are added to the end of the existing data, superseding the previous value that was there for the same key.
gustavatmel 1:9c5af431a1f1 10 The NVStore module ensures that power failures don't harm existing data during any operation.
gustavatmel 1:9c5af431a1f1 11 The full interface can be found under `nvstore.h`.
gustavatmel 1:9c5af431a1f1 12
gustavatmel 1:9c5af431a1f1 13 ### Flash structure
gustavatmel 1:9c5af431a1f1 14 NVStore uses two Flash areas, active and nonactive. Each area must consist of at least one erasable unit (sector).
gustavatmel 1:9c5af431a1f1 15 Data is written to the active area until it becomes full. When it does, garbage collection is invoked.
gustavatmel 1:9c5af431a1f1 16 This compacts items from the active area to the nonactive one and switches activity between areas.
gustavatmel 1:9c5af431a1f1 17 Each item is kept in an entry containing a header and data, where the header holds the item key, size and CRC.
gustavatmel 1:9c5af431a1f1 18
gustavatmel 1:9c5af431a1f1 19 ### APIs
gustavatmel 1:9c5af431a1f1 20 - init: Initialize NVStore (also lazily called by get, set, set_once and remove APIs).
gustavatmel 1:9c5af431a1f1 21 - deinit: Deinitialize NVStore.
gustavatmel 1:9c5af431a1f1 22 - get: Get the value of an item, given key.
gustavatmel 1:9c5af431a1f1 23 - set: Set the value of an item, given key and value.
gustavatmel 1:9c5af431a1f1 24 - set_once: Like set, but allows only a one time setting of this item (and disables deleting of this item).
gustavatmel 1:9c5af431a1f1 25 - set_alloc_key: Like set, but allocates a free key (from the non predefined keys).
gustavatmel 1:9c5af431a1f1 26 - remove: Remove an item, given key.
gustavatmel 1:9c5af431a1f1 27 - get_item_size: Get the item value size (in bytes).
gustavatmel 1:9c5af431a1f1 28 - set_max_keys: Set maximal value of unique keys. Overriding the default of NVSTORE_MAX_KEYS. This affects RAM consumption,
gustavatmel 1:9c5af431a1f1 29 as NVStore consumes 4 bytes per unique key. Reinitializes the module.
gustavatmel 1:9c5af431a1f1 30
gustavatmel 1:9c5af431a1f1 31
gustavatmel 1:9c5af431a1f1 32 ## Usage
gustavatmel 1:9c5af431a1f1 33
gustavatmel 1:9c5af431a1f1 34 ### Enabling NVStore and configuring it for your board
gustavatmel 1:9c5af431a1f1 35 NVStore is enabled by default for all devices with the internal flash driver (have "FLASH" in the device_has attribute).
gustavatmel 1:9c5af431a1f1 36 One can disable it by setting its "enabled" attribute to false.
gustavatmel 1:9c5af431a1f1 37 Unless specifically configured by the user, NVStore selects the last two flash sectors as its areas, with the minimum size of 4KBs,
gustavatmel 1:9c5af431a1f1 38 meaning that if the sectors are smaller, few continuous ones will be used for each area.
gustavatmel 1:9c5af431a1f1 39 The user can override this by setting the addresses and sizes of both areas in` mbed_lib.json` on a per board basis.
gustavatmel 1:9c5af431a1f1 40 In this case, all following four attributes need to be set:
gustavatmel 1:9c5af431a1f1 41 - area_1_address
gustavatmel 1:9c5af431a1f1 42 - area_1_size
gustavatmel 1:9c5af431a1f1 43 - area_2_address
gustavatmel 1:9c5af431a1f1 44 - area_2_size
gustavatmel 1:9c5af431a1f1 45
gustavatmel 1:9c5af431a1f1 46 In addition, the `num_keys` value should be modified to change the default number of different keys.
gustavatmel 1:9c5af431a1f1 47
gustavatmel 1:9c5af431a1f1 48 ### Using NVStore
gustavatmel 1:9c5af431a1f1 49 NVStore is a singleton class, meaning that the system can have only a single instance of it.
gustavatmel 1:9c5af431a1f1 50 To instantiate NVStore, one needs to call its get_instance member function as following:
gustavatmel 1:9c5af431a1f1 51 ``` c++
gustavatmel 1:9c5af431a1f1 52 NVStore &nvstore = NVStore::get_instance();
gustavatmel 1:9c5af431a1f1 53 ```
gustavatmel 1:9c5af431a1f1 54 After the NVStore instantiation, one can call the init API, but it is not necessary because all
gustavatmel 1:9c5af431a1f1 55 NVStore APIs (get, set and so on) perform a "lazy initialization".
gustavatmel 1:9c5af431a1f1 56
gustavatmel 1:9c5af431a1f1 57 ### Testing NVStore
gustavatmel 1:9c5af431a1f1 58 Run the NVStore functionality test with the `mbed` command as following:
gustavatmel 1:9c5af431a1f1 59 ```mbed test -n features-nvstore-tests-nvstore-functionality```