Non-Volatile Memory Version 3 (NVM3) Architecture#

The SiWx917 NVM3 architecture uses a layered design that separates application logic, API interfaces, and hardware-level flash operations.

This modular approach allows developers to store and retrieve persistent data reliably without directly managing flash memory.

Layers#

1. Application Layer#

This top layer represents user applications that interact with NVM3 through APIs.

• User NVM3 application:
  Implements persistent storage for configuration data, credentials, and runtime states.

• NVM3 examples: Example projects in the WiSeConnect SDK demonstrate initialization, configuration, and data storage operations that use the NVM3 API.

2. API Layer#

This layer defines the interface between application code and the underlying driver.

• NVM3 APIs (nvm3.h):
  Provide functions for initialization, object read and write, repacking, and maintenance.

  The API layer abstracts flash-specific implementation details to enable portable and reusable code.

3. Peripheral Driver Layer#

This layer connects NVM3 to the physical flash interface through the SiWx917’s high-performance domain.

• QSPI instance (HP domain):
  Serves as the bridge between the NVM3 driver and the QSPI hardware.

  Handles command sequencing, timing, and reliable access to on-chip or external flash.

4. Hardware Layer#

The hardware layer manages low-level flash operations such as read, write, and erase.

• QSPI controller:
  A dedicated peripheral that manages serial communication with internal or external flash memory.

  Executes flash access commands and manages timing, chip select, and signaling.

• Flash memory (internal and external):

  • Internal flash: Up to 8 MB of embedded storage.

  • External QSPI flash: Up to 16 MB, connected via the QSPI controller.

Key Concepts in NVM3#

The following sections describe fundamental NVM3 concepts for SiWx917, explaining how data is stored, maintained, and protected to ensure long-term reliability.

Objects#

An NVM3 object is a persistent data unit stored in flash memory as a key–value pair.

• Each key uniquely identifies an object within the NVM region.

• Objects can be updated dynamically, and the driver maintains data consistency by using metadata such as versioning and status flags.

Object Types#

• Regular data objects:
  Store variable-length application data (such as, configuration parameters or sensor calibration).
  Maximum size: NVM3_MAX_OBJECT_SIZE (typically 4 KB).

• Counter objects:
  Store 32-bit integers used for atomic increment operations (ideal for event counters and usage tracking).

Object Handling#

On SiWx917, objects can reside in:

• Internal embedded flash (up to 8 MB), or

• External QSPI flash (up to 16 MB), accessed via the integrated QSPI controller.

Each write operation is atomic — incomplete writes due to power loss or reset are automatically discarded.

Invalid or replaced objects are later reclaimed during repacking to free space and reduce flash wear.

Repacking#

Repacking is the process of reclaiming storage space by consolidating valid objects and removing invalid or outdated data.

• Triggered automatically when free space is low.

• Can also be triggered manually using:

  nvm3_repack(handle);

During repacking, valid objects are copied to a new flash page, and old pages are erased. This process reclaims space by discarding outdated or invalid data.

Execution time depends on:

• Flash page erase duration

• The time required to write the largest configured object

Note: On SiWx917, repacking occurs in the flash region managed by the QSPI controller.
Background repacking can be scheduled during idle periods to minimize system latency.

Caching#

NVM3 uses a software cache to accelerate object lookups and reduce flash access latency.

• The cache stores object metadata, not the actual data.

• The recommended cache size should equal or exceed the total number of active and recently deleted objects.

• The cache significantly reduces access time, especially when using external QSPI flash.

Memory Placement#

Applications must allocate the NVM3 region carefully in flash memory.

Requirements#

• Start address must align to a flash page boundary.

• Total NVM region size must be a multiple of the flash page size.

• NVM3 pages must not overlap with application code or OTA partitions.

Note: When using external QSPI flash, ensure the NVM3 region does not overlap with OTA update or file system storage.

Bad Page Handling#

NVM3 continuously monitors flash health to ensure reliability.

If an erase or write operation fails:

1. Valid data is copied to a new page.

2. The damaged page is marked BAD and excluded from future use.

3. The write operation resumes safely on the new page.

This self-recovery mechanism ensures that SiWx917 applications remain reliable even as flash memory wears over time.

Core Components#

NVM3 on SiWx917 consists of two key components:

NVM3 Core#

• Manages object read, write, delete, and repack operations.

• Handles page allocation, wear leveling, and atomic updates.

• Maintains data integrity across resets and power cycles.

• Operates seamlessly with both internal flash and external flash via the QSPI controller.

NVM3 Default Instance#

• Provides a preconfigured setup defining:

  • Cache size

  • Maximum object size (NVM3_MAX_OBJECT_SIZE)

  • Flash region boundaries

  • Automatic repack and cleanup behavior

The default instance simplifies integration for most SiWx917 applications, with options to customize memory layout and cache performance.

Note: Add NVM3 through the Software Components interface in Simplicity Studio.
Configuration details are available in the Initialization and Configuration section.

Directory Structure#

The following structure shows where NVM3 components are located in a typical WiSeConnect SDK project for SiWx917:

wiseconnect/
├── examples/
│   └── si91x_soc/
│       └── service/
│           └── sl_si91x_nvm3_common_flash
simplicity/
├── platform/
│   └── emdrv/
│       └── nvm3/
|           ├── inc/
|           |   └── nvm3.h
│           └── src/     
│               └── nvm3.c

Dependencies#

Before using NVM3, ensure the following software and hardware components are available and configured:

• WiSeConnect Software Development Kit (SDK): Installed and configured in Simplicity Studio.

• Simplicity Studio Configuration: Used to manage project and SDK settings.

• UC (Universal Configurator): Sets NVM3 parameters.

• Clock source and divider settings: Managed through the microcontroller unit (MCU) clock architecture for the Quad Serial Peripheral Interface (QSPI).

• QSPI Controller: Provides the interface to flash memory.

• Non-Volatile Memory (Flash): Stores persistent NVM3 data.