Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/features/nvstore/README.md@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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