Non-Volatile Memory Version 3 (NVM3) Initialization and Configuration#

The Non-Volatile Memory Version 3 (NVM3) library provides a reliable, wear-leveled storage mechanism for saving key–value data in flash memory.
This section explains how to initialize and configure NVM3 for SiWx917 devices by using Simplicity Studio and the WiSeConnect Software Development Kit (SDK).

Startup Sequence#

The startup sequence outlines the required steps to set up NVM3 on SiWx917, including project creation, component configuration, code generation, and testing.

Step-by-step NVM3 Initialization and Configuration in Simplicity Studio#

Follow these steps to configure and enable NVM3 for your SiWx917 project in Simplicity Studio.

Step 1. Create or Open Your Project#

1. Launch Simplicity Studio.

2. Create a new project for your SiWx917 device or open an existing one.

3. For demonstration, select an NVM3 example project from the WiSeConnect SDK.

4. Connect your SiWx917 evaluation board; the IDE automatically detects it.

   
   Figure: SiWx917 board detection in Simplicity Studio.

5. Open an NVM3 example from Example Projects and Demos.

   
   Figure: Selecting an NVM3 example project.

6. Click Create to add the project to your workspace.

   Review the project documentation to understand its structure and usage.

After project setup, Simplicity Studio generates a standard directory structure.
Most examples automatically open the readme.md file.

Typical project structure:

• autogen/ – Auto-generated headers and linker scripts.

• config/ – Platform-specific configuration headers.

• resources/ – Documentation resources and images.

• simplicity_sdk_*/ – Gecko SDK platform layer and libraries.

• platform/ - Hardware Abstraction Layer (HAL), Cortex Microcontroller Software Interface Standard (CMSIS) RTOS, and common libraries.

• wiseconnect3_sdk_*/ – WiSeConnect SDK components.

• app.c, app.h, main.c – Application code and entry point.

• readme.md – Example usage instructions.

• sl_si91x_nvm3_common_flash.slcp – Project configuration file.

• sl_si91x_nvm3_common_flash.slps – Solution file for project management.

Step 2. Add the NVM3 Component#

The NVM3 component is available in the Project Configurator (Component Editor) in Simplicity Studio.

Note: Example projects already include the NVM3 component by default.

To add NVM3 manually:

1. Open your project’s .slcp file.

2. Select the Software Components tab.

3. Search for NVM3 or navigate to:
   WiSeConnect 3 SDK → Device → Si91x → MCU → Service

4. Click Install to add the NVM3 component.

   

Step 3. Configure NVM3 by Using Universal Configurator (UC)#

Use the Universal Configurator (UC) graphical interface to adjust NVM3 settings.

• Click Settings next to the NVM3 component.

  
  

Key Parameters#

Example Configuration#

nvm3_Init_t nvm3_defaultInitData =
{
  (nvm3_HalPtr_t)NVM3_BASE,
  NVM3_DEFAULT_NVM_SIZE,
#if (NVM3_DEFAULT_CACHE_SIZE != 0)
  defaultCache,
#else
  NULL,
#endif
  NVM3_DEFAULT_CACHE_SIZE,
  NVM3_DEFAULT_MAX_OBJECT_SIZE,
  NVM3_DEFAULT_REPACK_HEADROOM,
  &nvm3_halFlashHandle,
#if defined(NVM3_SECURITY)
  &nvm3_halCryptoHandle,
  NVM3_DEFAULT_SECURITY_TYPE,
#endif
};

// Initialization
nvm3_Init_t *nvm3_defaultInit = &nvm3_defaultInitData;

// Open Call
nvm3_open(nvm3_defaultHandle, nvm3_defaultInit);

Step 4. Generate Initialization Code#

When you add or modify NVM3 components, Simplicity Studio automatically generates the required driver and configuration files.

• Click View Source in the Universal Configurator (UC) interface to review the generated initialization and configuration code.

  
  Figure: Auto-generated NVM3 initialization code in Simplicity Studio.

Step 5. Build, Flash, and Test#

Before testing, ensure your Network Wireless Processor (NWP) firmware is updated to the latest version for full compatibility.
Download the latest firmware from the WiSeConnect GitHub repository and follow the SiWx91x Connectivity Firmware Upgrade Guide.

To do so:

1. Build the project in Simplicity Studio.

   
   Figure: Building the NVM3 project.

2. Flash the firmware to the SiWx917 device.

   
   
   Figure: Flashing and programming the NVM3 firmware.

3. Verify operation by using a serial console or debugger.

   
   Figure: NVM3 console output verifying successful operation.

API to Initialize#

This section describes how to define and initialize the NVM3 storage area in your application code, including how to configure object storage, retrieval, and error handling.

Defining the NVM3 Area#

• Define a dedicated memory section in the linker script for NVM3 storage.
  The size must be a multiple of the flash page size to ensure proper alignment.

• Define the NVM3_MAX_OBJECT_SIZE macro in your IDE or project settings to specify the maximum size of a single object.

Tip: Ensure the NVM3 region does not overlap with other flash memory sections, such as bootloader or OTA partitions.

Initialization#

To initialize NVM3:

1. Declare an nvm3_Init_t structure and populate it with configuration parameters, such as base address, memory size, and cache size.

2. Call nvm3_open() with this structure to initialize the instance.
   The function automatically recovers from incomplete transactions (such as, power failures).

// Define NVM3 initialization structure
static nvm3_Init_t nvm3_init_struct = {
    .nvmAdr = NVM3_DEFAULT_NVM_START,
    .nvmSize = NVM3_DEFAULT_NVM_SIZE,
    .cacheSize = NVM3_DEFAULT_CACHE_SIZE,
    .maxObjectSize = NVM3_DEFAULT_MAX_OBJECT_SIZE,
    .repackHeadroom = NVM3_DEFAULT_REPACK_HEADROOM,
    .halHandle = NULL
};

// Initialize NVM3 instance
err = nvm3_init(nvm3_defaultHandle, &nvm3_init_struct);
if (err != ECODE_NVM3_OK) {
  // Handle initialization error
    return SL_STATUS_FAIL;
}

// Perform open operation
err = nvm3_open(nvm3_defaultHandle, &nvm3_init_struct);
if (err != ECODE_NVM3_OK) {
  // Handle open error
  return SL_STATUS_FAIL;
}

Storing and Retrieving Data#

The NVM3 driver uses a key–value pair structure for storing persistent data.
Each stored object is uniquely identified by a 20-bit key, allowing efficient retrieval and update of data objects.

• Use nvm3_writeData() to store or update data in flash.

• Use nvm3_readData() to read data back into RAM.

• NVM3 automatically performs wear-leveling internally to extend flash lifetime.

// Write data
status = nvm3_writeData(nvm3_defaultHandle, MY_NVM3_KEY_2, &complex_data, sizeof(complex_data));
if (status != SL_STATUS_OK) {
  return status;
}

// Read data back
uint32_t read_simple_data;
size_t bytes_read;
    
status = nvm3_readData(nvm3_defaultHandle, MY_NVM3_KEY_1, &read_simple_data, sizeof(read_simple_data),&bytes_read);
if (status != SL_STATUS_OK) {
  return status;
}

Error Handling#

• Most NVM3 functions return error codes to indicate success or failure.

• The nvm3_open() function attempts to recover from power failures or incomplete operations. If it fails, the error usually indicates insufficient NVM space or a severe issue.