NVDM

This section introduces the NVDM APIs including terms and acronyms, supported features, software architecture, details on how to use the NVDM, enums, structures, typedefs and functions. More...

Overview

This section introduces the NVDM APIs including terms and acronyms, supported features, software architecture, details on how to use the NVDM, enums, structures, typedefs and functions.

Terms and acronyms

Terms	Details
NVDM	Non-volatile Data Management is a middleware used to store user data.

Supported features

• Support retaining data after power is off.
  NVDM stores user data in a flash memory, so the data is preserved even after the power is off.
  
• Support grouping data items.
  The NVDM stores data items based on group names. The user can define different data items with different group names. This enables the data item classification and keeps them in order.

How to use the NVDM APIs

• To use the NVDM services follow the steps, as shown below.
  
  • Step 1. Call nvdm_init() to initialize the NVDM module.
  • Step 2. Call nvdm_write_data_item() to write or update data item to the flash.
  • Step 3. Call nvdm_read_data_item() to read data item from the flash.
  • Step 4. Call nvdm_query_begin() to start the query request.
  • Step 5. Call nvdm_query_next_group_name() to query the next available data item group.
  • Step 6. Call nvdm_query_next_data_item_name() to query the next available data item from the group queried in Step 5.
  • Step 7. Call nvdm_query_end() to end the query.
  • Step 8. Call nvdm_delete_data_item() to delete a specific data item in flash.
  • sample code:

    #define STA_IPADDR_DEFAULT_VALUE "192.168.0.1"
    
    void nvdm_application(void)
    {
        nvdm_status_t status;
        uint32_t size;
        uint8_t buffer[16];
        char group_name[64];
        char data_item_name[64];
    
        status = nvdm_init();
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
    
        status = nvdm_write_data_item("STA", "IpAddr", DATA_ITEM_TYPE_STRING, (uint8_t *)STA_IPADDR_DEFAULT_VALUE, sizeof(STA_IPADDR_DEFAULT_VALUE));
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
    
        size = sizeof(buffer);
        status = nvdm_read_data_item("STA", "IpAddr", buffer, &size);
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
    
        status = nvdm_query_begin();
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
        status = nvdm_query_next_group_name(group_name);
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
        status = nvdm_query_next_data_item_name(data_item_name);
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
        status = nvdm_query_end();
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
    
        status = nvdm_delete_data_item(group_name, data_item_name);
        if (status != NVDM_STATUS_OK) {
            //Error handler;
        }
    }

How to adjust the NVDM region

• There is a special flash region assigned to the NVDM to store user defined data. For more information on the NVDM memory layout, please refer to the Memory Layout Developer's Guide.
• To modify start address and size of the NVDM region, apply the following steps.
  • Step 1. Follow chapters "Memory layout adjustment with a linker script" and "Memory layout adjustment with a scatter file" in Memory Layout Developer's Guide to modify the start address and size of the NVDM.
  • Step 2. Modify flash_map.h or memory_map.h header files under /project/<board>/apps/<project>/inc/ according to the adjustments in Step 1.
    • For LinkIt 7687 module and LinkIt 7697 module, user needs to modify flash_map.h under /project/<board>/apps/<project>/inc/. Modify the CM4_FLASH_USR_CONF_ADDR to adjust the start address of the NVDM region. Modify the FLASH_USR_CONF_SIZE to adjust the size of the NVDM region.
    • For other LinkIt modules, modify the memory_map.h header file under /project/<board>/apps/<project>/inc/. Modify the ROM_NVDM_BASE to adjust the start address of the NVDM region. Modify the ROM_NVDM_LENGTH to adjust the size of the NVDM region.

Functions
nvdm_status_t	nvdm_init (void)
	This function initializes the NVDM module to enable the NVDM services. More...
nvdm_status_t	nvdm_write_data_item (const char *group_name, const char *data_item_name, nvdm_data_item_type_t type, const uint8_t *buffer, uint32_t size)
	This function is used to write or update a data item to flash. More...
nvdm_status_t	nvdm_read_data_item (const char *group_name, const char *data_item_name, uint8_t *buffer, uint32_t *size)
	This function is used to read the data item from flash. More...
nvdm_status_t	nvdm_delete_data_item (const char *group_name, const char *data_item_name)
nvdm_status_t	nvdm_delete_group (const char *group_name)
nvdm_status_t	nvdm_delete_all (void)
nvdm_status_t	nvdm_query_begin (void)
nvdm_status_t	nvdm_query_end (void)
nvdm_status_t	nvdm_query_next_group_name (char *group_name)
	This function is used to enumerate all available group names. More...
nvdm_status_t	nvdm_query_next_data_item_name (char *data_item_name)
	This function is used to enumerate all available data item names from the group returned by nvdm_query_next_group_name(). More...

Modules
	Enum

Function Documentation

nvdm_status_t nvdm_init

(

void

)

This function initializes the NVDM module to enable the NVDM services.

User should not call nvdm_read_data_item() or nvdm_write_data_item() before nvdm_init(). Call nvdm_init() only once during the initialization.

Returns

NVDM_STATUS_OK, if the operation completed successfully.
NVDM_STATUS_ERROR, if an unknown error occurred.

nvdm_status_t nvdm_query_next_data_item_name

(

char *

data_item_name

)

This function is used to enumerate all available data item names from the group returned by nvdm_query_next_group_name().

The next available data item name is returned each time user calls this API. If the user calls the API after all available data item names are returned, the return value will be NVDM_STATUS_ITEM_NOT_FOUND.

Parameters

[out]

data_item_name

return the name of next data item belonging the specifc group.

Returns

NVDM_STATUS_OK, if the operation completed successfully.
NVDM_STATUS_ERROR, if an unknown error occurred.
NVDM_STATUS_INVALID_PARAMETER, if the parameter is invalid.
NVDM_STATUS_ITEM_NOT_FOUND, if the data item group is not found.

nvdm_status_t nvdm_query_next_group_name

(

char *

group_name

)

This function is used to enumerate all available group names.

The next available group name is returned each time user calls this API. If the user calls the API after all available group names are returned, the return value will be NVDM_STATUS_ITEM_NOT_FOUND.

Parameters

[out]

group_name

return the name of the next group available.

Returns

NVDM_STATUS_OK, if the operation completed successfully.
NVDM_STATUS_ERROR, if an unknown error occurred.
NVDM_STATUS_INVALID_PARAMETER, if the parameter is invalid.
NVDM_STATUS_ITEM_NOT_FOUND, if the data item group is not found.

nvdm_status_t nvdm_read_data_item	(	const char *	group_name,
		const char *	data_item_name,
		uint8_t *	buffer,
		uint32_t *	size
	)

This function is used to read the data item from flash.

If there is no such data item, it returns NVDM_STATUS_ITEM_NOT_FOUND. User should check the return status to verify whether the data read from the flash is correct.

Parameters

[in]	group_name	is the group name of the data item, such as "Bluetooth".
[in]	data_item_name	is the name of the data item, such as an "address" of "Bluetooth".
[out]	buffer	is a pointer to the user buffer, that stores the data item content read from the flash.
[in,out]	size	is the user buffer size when used as an input and is the size of actual data item's content read out when used as an output.

Returns

NVDM_STATUS_OK, if the operation completed successfully.
NVDM_STATUS_ERROR, if an unknown error occurred.
NVDM_STATUS_INVALID_PARAMETER, if the parameter is invalid.
NVDM_STATUS_ITEM_NOT_FOUND, if the data item is not found.
NVDM_STATUS_INCORRECT_CHECKSUM, if the checksum of data item is invalid.

Note

Call this API in tasks or function callbacks, but not in the interrupt handlers.

nvdm_status_t nvdm_write_data_item	(	const char *	group_name,
		const char *	data_item_name,
		nvdm_data_item_type_t	type,
		const uint8_t *	buffer,
		uint32_t	size
	)

This function is used to write or update a data item to flash.

If there are existing data items on the flash, the NVDM invalidates old values and replaces with new ones. No other operation is performed while the data is being written to the flash. This function returns after the data is completely written to the flash. User should check the return status to verify whether the data is written to flash successfully.

Parameters

[in]	type	is the data item type, which defines how the value is displayed.
[in]	group_name	is the group name of the data item, such as "Bluetooth".
[in]	data_item_name	is the name of the data item, such as "address" of the "Bluetooth".
[in]	buffer	is a pointer to the data item's content.
[in]	size	is the size of the data item's content.

Returns

NVDM_STATUS_OK, if the operation completed successfully.
NVDM_STATUS_ERROR, if an unknown error occurred.
NVDM_STATUS_INVALID_PARAMETER, if the parameter is invalid.
NVDM_STATUS_INSUFFICIENT_SPACE, if the storage space is not enough.

Note

Call this API in tasks or function callbacks, but not in the interrupt handlers.