Flash

On-chip / external flash memory access.

Provides erase and write access to the device's program-flash or an attached external flash. Reads on memory-mapped flash are performed by simply dereferencing pointers into the flash region — there is no flash_read().

Programming model

• Flash must be erased before it can be written. Erase always happens at sector granularity; use flash_info to obtain the sector layout.
• Writes happen in multiples of flash_info_t::writeSize bytes. Passing an unaligned address or a length that is not a multiple of writeSize yields an error.
• Erased bytes read back as 0xFF. A given byte can only be programmed from 1-bits to 0-bits; flipping bits back to 1 requires another erase.

Sysprops

The flash driver has no required sysprops; the layout is reported at runtime by the driver via flash_info.

Example

Erase one sector and write a payload into it.

#include <flash.h>
#include <string.h>

int store_blob(uint32_t offset, const uint8_t* payload, size_t len) {
    int h = open("flash0");
    if (h < 0) return -1;

    flash_info_t info;
    if (flash_info(h, &info) != 0) { close(h); return -1; }

    // round target address down to the start of its sector
    uint32_t sect_size = info.sectorLayouts[0].sectorSize;
    uint32_t addr      = info.startAddress + offset;
    uint32_t sect_addr = addr & ~(sect_size - 1);

    if (flash_erase(h, sect_addr) != 0) { close(h); return -1; }
    if (flash_write(h, addr, (unsigned char*)payload, len) != 0) {
        close(h);
        return -1;
    }

    close(h);
    return 0;
}

Types

	Name
struct	flash_sector_layout_t Describes one contiguous region of the flash with uniform sector size.
struct	flash_info_t Static description of the flash device backing a flash0/flash1/... handle.

Functions Overview

	Name
cw_driver_return_t	flash_info(int hDev, flash_info_t * info) Retrieves the geometry and capabilities of the flash device.
CW_NODISCARD cw_driver_return_t	flash_erase(int hDev, uint32_t sector_address) Erases the sector that contains sector_address.
CW_NODISCARD cw_driver_return_t	flash_write(int hDev, uint32_t address, unsigned char * data, size_t len) Writes a contiguous buffer to flash.

Function Details

function flash_info

cw_driver_return_t flash_info(
    int hDev,
    flash_info_t * info
)

Retrieves the geometry and capabilities of the flash device.

Parameters:

• hDev device handle as returned by open(const char*).
• info Caller-provided buffer that receives the description.

Return: 0 on success, negative on error.

function flash_erase

CW_NODISCARD cw_driver_return_t flash_erase(
    int hDev,
    uint32_t sector_address
)

Erases the sector that contains sector_address.

Parameters:

• hDev device handle as returned by open(const char*).
• sector_address Absolute start address of the sector to erase.

Return: 0 on success, negative on error (e.g. unaligned address, hardware fault).

sector_address must be the absolute start address of a sector as reported by flash_info. Erasing returns the entire sector to the all-0xFF state. The call blocks until the erase completes.

function flash_write

CW_NODISCARD cw_driver_return_t flash_write(
    int hDev,
    uint32_t address,
    unsigned char * data,
    size_t len
)

Writes a contiguous buffer to flash.

Parameters:

• hDev device handle as returned by open(const char*).
• address Absolute target address inside the flash region.
• data Source buffer with the bytes to be programmed.
• len Number of bytes to write.

Return: 0 on success, negative on error.

The target region must have been erased beforehand (see flash_erase). Both address and len must be a multiple of flash_info_t::writeSize; otherwise the call fails. The destination range must not span the end of the flash region.