Mistake on this page?
Report an issue in GitHub or email us

NVStore

NVStore class hierarchy

NVStore is a lightweight module that stores data by keys in the internal flash for security purposes. For each item key, the NVStore module provides the ability to set the item data or get it. Newly added values are added to the end of the existing data, superseding the previous value that was there for the same key. The NVStore module ensures that power failures don't harm existing data during any operation.

Flash structure

NVStore uses two Flash areas, active and nonactive. Each area must consist of at least one erasable unit (sector). Data is written to the active area until it becomes full. When it does, garbage collection is invoked. This compacts items from the active area to the nonactive one and switches activity between areas. Each item is kept in an entry containing a header and data, where the header holds the item key, size and CRC.

Unless specifically configured by the user, NVStore selects the last two flash sectors as its areas, with the minimum size of 4KBs. This means that if the sectors are smaller, NVStore uses a few continuous ones for each area. If the automatically selected sectors do not fit your flash configuration, you can override this by setting the addresses and sizes of both areas in mbed_app.json for each board.

NVStore class reference

Public Member Functions
uint16_t get_max_keys () const
 Returns number of keys. More...
void set_max_keys (uint16_t num_keys)
 Set number of keys. More...
uint16_t get_max_possible_keys ()
 Return maximal possible number of keys (in this flash configuration). More...
int get (uint16_t key, uint16_t buf_size, void *buf, uint16_t &actual_size)
 Returns one item of data programmed on Flash, given key. More...
int get_item_size (uint16_t key, uint16_t &actual_size)
 Returns size of the data programmed on Flash, given key. More...
int set (uint16_t key, uint16_t buf_size, const void *buf)
 Programs one item of data on Flash, given key. More...
int allocate_key (uint16_t &key, uint8_t owner=NVSTORE_UNSPECIFIED_OWNER)
 Allocate a free key (to be used later in a set operation). More...
int free_all_keys_by_owner (uint8_t owner)
 Free all allocated keys that belong to a specific owner. More...
int set_once (uint16_t key, uint16_t buf_size, const void *buf)
 Programs one item of data on Flash, given key, allowing no consequent sets to this key. More...
int remove (uint16_t key)
 Remove an item from flash. More...
int init ()
 Initializes NVStore component. More...
int deinit ()
 Deinitializes NVStore component. Warning: This function is not thread safe and should not be called concurrently with other NVStore functions. More...
int reset ()
 Reset Flash NVStore areas. Warning: This function is not thread safe and should not be called concurrently with other NVStore functions. More...
size_t size ()
 Return NVStore size (area size). More...
int get_area_params (uint8_t area, uint32_t &address, size_t &size)
 Return address and size of an NVStore area. More...
Static Public Member Functions
static NVStoreget_instance ()
 As a singleton, return the single instance of the class. Reason for this class being a singleton is the following: More...

NVStore example

/*
* Copyright (c) 2018 ARM Limited. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
* Licensed under the Apache License, Version 2.0 (the License); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#include "mbed.h"
#include "nvstore.h"
#include <string.h>
#include <stdlib.h>
#include <stdio.h>

// Entry point for the example
int main() {
    printf("\n--- Mbed OS NVStore example ---\n");
#if NVSTORE_ENABLED

    uint16_t actual_len_bytes = 0;

    // NVStore is a sigleton, get its instance
    NVStore &nvstore = NVStore::get_instance();

    int rc;
    uint16_t key;

    // Values read or written by NVStore need to be aligned to a uint32_t address (even if their sizes
    // aren't)
    uint32_t value;

    // Initialize NVstore. Note that it can be skipped, as it is lazily called by all other APIs
    rc = nvstore.init();
    printf("Init NVStore. ");
    printf("Return code is %d\n", rc);

    // Show NVStore size, maximum number of keys and area addresses and sizes
    printf("NVStore size is %d\n", nvstore.size());
    printf("NVStore max number of keys is %d (out of %d possible ones in this flash configuration)\n",
            nvstore.get_max_keys(), nvstore.get_max_possible_keys());
    printf("NVStore areas:\n");
    for (uint8_t area = 0; area < NVSTORE_NUM_AREAS; area++) {
        uint32_t area_address;
        size_t area_size;
        nvstore.get_area_params(area, area_address, area_size);
        printf("Area %d: address 0x%08lx, size %d (0x%x)\n", area, area_address, area_size, area_size);
    }

    // Clear NVStore data. Should only be done once at factory configuration
    rc = nvstore.reset();
    printf("Reset NVStore. ");
    printf("Return code is %d\n", rc);

    // Now set some values to the same key
    key = 1;

    value = 1000;
    rc = nvstore.set(key, sizeof(value), &value);
    printf("Set key %d to value %ld. ", key, value);
    printf("Return code is %d\n", rc);

    value = 2000;
    rc = nvstore.set(key, sizeof(value), &value);
    printf("Set key %d to value %ld. ", key, value);
    printf("Return code is %d\n", rc);

    value = 3000;
    rc = nvstore.set(key, sizeof(value), &value);
    printf("Set key %d to value %ld. ", key, value);
    printf("Return code is %d\n", rc);

    // Get the value of this key (should be 3000)
    rc = nvstore.get(key, sizeof(value), &value, actual_len_bytes);
    printf("Get key %d. Value is %ld. ", key, value);
    printf("Return code is %d\n", rc);

    // Now remove the key
    rc = nvstore.remove(key);
    printf("Delete key %d. ", key);
    printf("Return code is %d\n", rc);

    // Get the key again, now it should not exist
    rc = nvstore.get(key, sizeof(value), &value, actual_len_bytes);
    printf("Get key %d. ", key);
    printf("Return code is %d\n", rc);

    key = 12;

    // Now set another key once (it can't be set again)
    value = 50;
    rc = nvstore.set_once(key, sizeof(value), &value);
    printf("Set key %d once to value %ld. ", key, value);
    printf("Return code is %d\n", rc);

    // This should fail on key already existing
    value = 100;
    rc = nvstore.set(key, sizeof(value), &value);
    printf("Set key %d to value %ld. ", key, value);
    printf("Return code is %d\n", rc);

    // Get the value of this key (should be 50)
    rc = nvstore.get(key, sizeof(value), &value, actual_len_bytes);
    printf("Get key %d. Value is %ld. ", key, value);
    printf("Return code is %d\n", rc);

    // Get the data size for this key (should be 4)
    rc = nvstore.get_item_size(key, actual_len_bytes);
    printf("Data size for key %d is %d. ", key, actual_len_bytes);
    printf("Return code is %d\n", rc);
#else
    printf("NVStore is disabled for this board\n");
#endif

    printf("\n--- Mbed OS NVStore example done. ---\n");
}

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.