File ns_nvm.h

FileList > includes-api > ns_nvm.h

Go to the source code of this file

neuralSPOT NVM (external MSPI flash) helper API More...

• #include "ns_core.h"
• #include "am_mcu_apollo.h"
• #include <stdbool.h>
• #include <stdint.h>

Classes

Type	Name
struct	ns_nvm_config_t NVM configuration.

Public Types

Type	Name
enum	ns_nvm_interface_e

Public Attributes

Type	Name
const ns_core_api_t	ns_nvm_V0_0_1
const ns_core_api_t	ns_nvm_current_version
const ns_core_api_t	ns_nvm_oldest_supported_version

Public Functions

Type	Name
uint32_t	ns_nvm_disable_xip (void) Disable XIP on the MSPI instance configured during init.
uint32_t	ns_nvm_enable_xip (void) Enable XIP on the MSPI instance configured during init.
uint32_t	ns_nvm_init (ns_nvm_config_t * cfg) Initialize NVM per the configuration struct (timing scan + init).
uint32_t	ns_nvm_mass_erase (void) Full chip erase. Use with care.
uint32_t	ns_nvm_read (uint32_t addr, uint8_t * buf, uint32_t len, bool wait) Read from NVM into a buffer.
uint32_t	ns_nvm_sector_erase (uint32_t sector_addr) Erase a single sector containing the given address. Sector size for IS25WX064 is 128KB.
uint32_t	ns_nvm_write (uint32_t addr, const uint8_t * buf, uint32_t len, bool wait) Write to NVM from a buffer. Caller must ensure erase has been done.

Macros

Type	Name
define	NS_NVM_API_ID 0xCA000B
define	NS_NVM_CURRENT_VERSION NS\_NVM\_V1\_0\_0
define	NS_NVM_OLDEST_SUPPORTED_VERSION NS\_NVM\_V0\_0\_1
define	NS_NVM_V0_0_1 { .major = 0, .minor = 0, .revision = 1 }
define	NS_NVM_V1_0_0 { .major = 1, .minor = 0, .revision = 0 }

Detailed Description

Author:

Ambiq

Version:

0.1

Date:

2025-08-29

This API provides a thin, stable wrapper over AmbiqSuite MSPI flash HAL to support erase/read/write and XIP enable/disable, similar in spirit to ns_psram. It validates the ns_core API prefix and exposes a small config.

Typical flow: 1) Fill ns_nvm_config_t (module, CE, mode, freq). 2) Call ns_nvm_init(&cfg). This performs timing scan, init, and (optionally) XIP. 3) Use ns_nvm_read / ns_nvm_write / ns_nvm_sector_erase / ns_nvm_mass_erase. 4) Optionally toggle XIP via ns_nvm_enable_xip / ns_nvm_disable_xip.

The current implementation targets IS25WX064 (64 Mbit) by default.

Copyright (c) 2025 Ambiq

Public Types Documentation

enum ns_nvm_interface_e

enum ns_nvm_interface_e {
    NS_NVM_IF_OCTAL_DDR = 0,
    NS_NVM_IF_OCTAL_1_8_8 = 1
};

---

Public Attributes Documentation

variable ns_nvm_V0_0_1

const ns_core_api_t ns_nvm_V0_0_1;

---

variable ns_nvm_current_version

const ns_core_api_t ns_nvm_current_version;

---

variable ns_nvm_oldest_supported_version

const ns_core_api_t ns_nvm_oldest_supported_version;

---

Public Functions Documentation

function ns_nvm_disable_xip

Disable XIP on the MSPI instance configured during init.

uint32_t ns_nvm_disable_xip (
    void
) 

Returns:

HAL device status code.

---

function ns_nvm_enable_xip

Enable XIP on the MSPI instance configured during init.

uint32_t ns_nvm_enable_xip (
    void
) 

Returns:

HAL device status code.

---

function ns_nvm_init

Initialize NVM per the configuration struct (timing scan + init).

uint32_t ns_nvm_init (
    ns_nvm_config_t * cfg
) 

Parameters:

• cfg Config struct (must remain valid during operation).

Returns:

0 on success, ns_core error codes on validation errors, or HAL device status (AM_DEVICES_MSPI_IS25WX064_STATUS_*) on HAL error.

---

function ns_nvm_mass_erase

Full chip erase. Use with care.

uint32_t ns_nvm_mass_erase (
    void
) 

Returns:

HAL device status code.

---

function ns_nvm_read

Read from NVM into a buffer.

uint32_t ns_nvm_read (
    uint32_t addr,
    uint8_t * buf,
    uint32_t len,
    bool wait
) 

Parameters:

• addr Byte address in NVM.
• buf Destination buffer in SRAM.
• len Number of bytes to read.
• wait If true, block until completion.

Returns:

HAL device status code.

---

function ns_nvm_sector_erase

Erase a single sector containing the given address. Sector size for IS25WX064 is 128KB.

uint32_t ns_nvm_sector_erase (
    uint32_t sector_addr
) 

Parameters:

• sector_addr Sector-aligned (or any address within sector).

Returns:

HAL device status code.

---

function ns_nvm_write

Write to NVM from a buffer. Caller must ensure erase has been done.

uint32_t ns_nvm_write (
    uint32_t addr,
    const uint8_t * buf,
    uint32_t len,
    bool wait
) 

Parameters:

• addr Byte address in NVM (page boundaries handled by HAL).
• buf Source buffer in SRAM.
• len Number of bytes to write.
• wait If true, block until completion.

Returns:

HAL device status code.

---

Macro Definition Documentation

define NS_NVM_API_ID

#define NS_NVM_API_ID `0xCA000B`

---

define NS_NVM_CURRENT_VERSION

#define NS_NVM_CURRENT_VERSION `NS_NVM_V1_0_0`

---

define NS_NVM_OLDEST_SUPPORTED_VERSION

#define NS_NVM_OLDEST_SUPPORTED_VERSION `NS_NVM_V0_0_1`

---

define NS_NVM_V0_0_1

#define NS_NVM_V0_0_1 `{ .major = 0, .minor = 0, .revision = 1 }`

---

define NS_NVM_V1_0_0

#define NS_NVM_V1_0_0 `{ .major = 1, .minor = 0, .revision = 0 }`

---

---

The documentation for this class was generated from the following file neuralspot/neuralspot/ns-peripherals/includes-api/ns_nvm.h