Flash Memory Access API Reference (SiWx917 / Si91x Family)#

The SiWx917 (Si91x family) flash memory application programming interface (API) in the WiSeConnect Software Development Kit (SDK) provides functions to read, program, and erase the device Common Flash region. The Arm® Cortex®-M4 processor (M4) initiates flash commands, while the Network Wireless Processor (NWP) performs the low-level flash operations.

Applications use these APIs to:

Store configuration data
Maintain non-volatile application information
Update firmware or secondary images
Read metadata or verify stored data

All flash APIs are synchronous (blocking). Use them carefully in performance-critical or timing-sensitive application paths.

Flash Memory Overview#

SiWx917 devices include a shared Common Flash region accessible by both the M4 and NWP.

Flash characteristics:


Property	Value
Erase granularity	4 KB sector
Program granularity	Internally managed (page-aligned)
Erase state	0xFF
Access model	M4 initiates; NWP executes

Flash must be erased before writing.

Public Flash APIs#

A typical flash workflow:

Erase the target sectors.
Write new data.
Read or verify the programmed contents.

For the full API reference, see WiSeConnect Si91x peripherals: Flash.

Flash Read API#

sl_si91x_command_to_read_common_flash()#

Purpose#

Reads data from the Common Flash region into an M4 random-access memory (RAM) buffer.

Prototype#

sl_status_t sl_si91x_command_to_read_common_flash(uint32_t read_address,
                                                  uint16_t length,
                                                  uint8_t *output_buffer);sl_status_t sl_si91x_command_to_read_common_flash(uint32_t read_address,
                                                  uint16_t length,
                                                  uint8_t *output_buffer);

Parameters#


Parameter	Description
`read_address`	Start address in Common Flash. Must be within valid flash boundaries.
`length`	Number of bytes to read.
`output_buffer`	Pointer to RAM buffer receiving the read data.

Usage Guidelines#

For large reads, split the operation into sector- or page-aligned chunks.
Avoid reading reserved or protected regions.
This function is blocking.

Example#

uint8_t buffer[128];

sl_status_t status =
  sl_si91x_command_to_read_common_flash(FLASH_USER_CFG_ADDR,
                                        sizeof(buffer),
                                        buffer);

if (status == SL_STATUS_OK) {
    // Process retrieved data
} else {
    // Handle error
}uint8_t buffer[128];

sl_status_t status =
  sl_si91x_command_to_read_common_flash(FLASH_USER_CFG_ADDR,
                                        sizeof(buffer),
                                        buffer);

if (status == SL_STATUS_OK) {
    // Process retrieved data
} else {
    // Handle error
}

Flash Write API#

sl_si91x_command_to_write_common_flash()#

Purpose#

Programs data into the Common Flash region. The API can optionally erase the target sector before writing.

Prototype#

sl_status_t sl_si91x_command_to_write_common_flash(uint32_t write_address,
                                                   uint8_t *write_data,
                                                   uint16_t write_data_length,
                                                   uint8_t flash_sector_erase_enable);sl_status_t sl_si91x_command_to_write_common_flash(uint32_t write_address,
                                                   uint8_t *write_data,
                                                   uint16_t write_data_length,
                                                   uint8_t flash_sector_erase_enable);

Parameters#


Parameter	Description
`write_address`	Flash address to program. Must not overlap the active execute-in-place (XIP) region.
`write_data`	Pointer to the data buffer.
`write_data_length`	Number of bytes to program.
`flash_sector_erase_enable`	1 to erase before writing; 0 to write without erasing.

Usage Guidelines#

Always erase before writing unless the region is known to be blank (0xFF).
Perform a read-back verification after writing.
The function is blocking and may take several milliseconds.
Never write to a region from which code is executing.

Example#

uint8_t data_to_write[64] = { /* user data */ };

sl_status_t status =
  sl_si91x_command_to_write_common_flash(FLASH_USER_CFG_ADDR,
                                         data_to_write,
                                         sizeof(data_to_write),
                                         1); // erase enabled

if (status == SL_STATUS_OK) {
    // Write succeeded
} else {
    // Handle error
}uint8_t data_to_write[64] = { /* user data */ };

sl_status_t status =
  sl_si91x_command_to_write_common_flash(FLASH_USER_CFG_ADDR,
                                         data_to_write,
                                         sizeof(data_to_write),
                                         1); // erase enabled

if (status == SL_STATUS_OK) {
    // Write succeeded
} else {
    // Handle error
}

Flash Erase API#

sl_si91x_command_to_erase_common_flash()#

Purpose#

Erases one or more 4 KB sectors in Common Flash. All erased bytes are set to 0xFF.

Prototype#

sl_status_t sl_si91x_command_to_erase_common_flash(uint32_t erase_address,
                                                   uint32_t erase_length);sl_status_t sl_si91x_command_to_erase_common_flash(uint32_t erase_address,
                                                   uint32_t erase_length);

Parameters#


Parameter	Description
`erase_address`	Start address for erase operation. Must be 4 KB aligned.
`erase_length`	Length to erase. Must be a multiple of 4 KB.

Usage Guidelines#

Erase operations are destructive. Ensure important data is not overwritten.
Large erases should be split across multiple operations.
Erase time increases with the number of sectors.

Example#

sl_status_t status =
  sl_si91x_command_to_erase_common_flash(FLASH_USER_CFG_ADDR,
                                         4096); // one sector

if (status == SL_STATUS_OK) {
    // Erase complete
} else {
    // Handle error
}sl_status_t status =
  sl_si91x_command_to_erase_common_flash(FLASH_USER_CFG_ADDR,
                                         4096); // one sector

if (status == SL_STATUS_OK) {
    // Erase complete
} else {
    // Handle error
}

Integration Workflow#

void app_flash_update(void)
{
    uint8_t data[128] = { /* new data */ };
    uint8_t verify_buf[128];

    // Step 1: Erase target sector
    sl_si91x_command_to_erase_common_flash(FLASH_USER_CFG_ADDR, 4096);

    // Step 2: Write new data
    sl_si91x_command_to_write_common_flash(FLASH_USER_CFG_ADDR,
                                           data,
                                           sizeof(data),
                                           0); // already erased

    // Step 3: Verify stored content
    sl_si91x_command_to_read_common_flash(FLASH_USER_CFG_ADDR,
                                          sizeof(verify_buf),
                                          verify_buf);

    if (memcmp(data, verify_buf, sizeof(data)) == 0) {
        // Verified successfully
    } else {
        // Verification failed
    }
}void app_flash_update(void)
{
    uint8_t data[128] = { /* new data */ };
    uint8_t verify_buf[128];

    // Step 1: Erase target sector
    sl_si91x_command_to_erase_common_flash(FLASH_USER_CFG_ADDR, 4096);

    // Step 2: Write new data
    sl_si91x_command_to_write_common_flash(FLASH_USER_CFG_ADDR,
                                           data,
                                           sizeof(data),
                                           0); // already erased

    // Step 3: Verify stored content
    sl_si91x_command_to_read_common_flash(FLASH_USER_CFG_ADDR,
                                          sizeof(verify_buf),
                                          verify_buf);

    if (memcmp(data, verify_buf, sizeof(data)) == 0) {
        // Verified successfully
    } else {
        // Verification failed
    }
}

Best Practices#

Respect flash boundaries and protected regions.
Use sector-aligned sizes for erase and write operations.
Avoid modifying XIP-active regions.
Do not perform flash updates in time-critical code.
Always verify written data using a read-back comparison.

Summary#


Operation	API	Notes
Read	`sl_si91x_command_to_read_common_flash`	Blocking; safe for verification
Write	`sl_si91x_command_to_write_common_flash`	Optional erase; verify afterward
Erase	`sl_si91x_command_to_erase_common_flash`	4 KB sector erase