Flash

External flash access. More...

Modules
	Low-level flash driver
	Interface implemented by each flash part driver.
	Flash internals
	Internal hooks of the flash API.
	QSPI flash
	Generic QSPI NOR flash driver, used by the part drivers to implement Low-level flash driver.
	QSPI flash device
	Board description of a QSPI flash device.
	QSPI flash parts
	Description of a QSPI NOR flash part: instructions, status bits and timings.

Data Structures
struct	FlashSecurityRegisters
	Security (OTP) registers of the flash part. More...

Typedefs
typedef void(*	FlashOperationCompleteCb) (void *context, status_t result)
	Flash operation completion callback.

Enumerations
enum	FlashModeType { FLASH_MODE_ASYNC = 0 , FLASH_MODE_SYNC_BURST , FLASH_MODE_NUM_MODES }
	Flash read mode. More...

Functions
void	flash_init (void)
	Initialize the flash driver and the flash part.
void	flash_stop (void)
	Stop flash activity.
void	flash_read_bytes (uint8_t *buffer, uint32_t start_addr, uint32_t buffer_size)
	Read from flash.
void	flash_write_bytes (const uint8_t *buffer, uint32_t start_addr, uint32_t buffer_size)
	Write to flash.
void	flash_erase_subsector (uint32_t subsector_addr, FlashOperationCompleteCb on_complete, void *context)
	Erase the subsector containing an address, asynchronously.
void	flash_erase_sector (uint32_t sector_addr, FlashOperationCompleteCb on_complete, void *context)
	Erase the sector containing an address, asynchronously.
void	flash_erase_subsector_blocking (uint32_t subsector_addr)
	Erase the subsector containing an address.
void	flash_erase_sector_blocking (uint32_t sector_addr)
	Erase the sector containing an address.
bool	flash_sector_is_erased (uint32_t sector_addr)
	Check whether the sector containing an address is erased.
bool	flash_subsector_is_erased (uint32_t sector_addr)
	Check whether the subsector containing an address is erased.
void	flash_erase_bulk (void)
	Erase the entire flash.
void	flash_erase_optimal_range (uint32_t min_start, uint32_t max_start, uint32_t min_end, uint32_t max_end, FlashOperationCompleteCb on_complete, void *context)
	Erase a range of flash asynchronously, using as few erase operations as possible.
void	flash_sleep_when_idle (bool enable)
	Let the flash enter deep sleep between commands.
bool	flash_get_sleep_when_idle (void)
	Check whether flash_sleep_when_idle() is in effect.
bool	flash_is_initialized (void)
	Check whether flash_init() has run.
void	flash_power_down_for_stop_mode (void)
	Put the flash in deep power-down before entering stop mode.
void	flash_power_up_after_stop_mode (void)
	Wake the flash after stop mode.
void	flash_switch_mode (FlashModeType mode)
	Switch the read mode.
uint32_t	flash_get_sector_base_address (uint32_t flash_addr)
	Get the base address of the sector containing an address.
uint32_t	flash_get_subsector_base_address (uint32_t flash_addr)
	Get the base address of the subsector containing an address.
void	flash_enable_write_protection (void)
	Enable write protection, if the part requires it to be enabled explicitly.
void	flash_prf_set_protection (bool do_protect)
	Write-protect the recovery firmware region, or remove all protection.
uint32_t	flash_crc32 (uint32_t flash_addr, uint32_t length)
	Compute the CRC-32 of a flash region.
uint32_t	flash_crc32_legacy (uint32_t flash_addr, uint32_t length)
	Compute the legacy checksum of a flash region.
void	flash_use (void)
	Take a reference keeping the flash peripheral powered.
void	flash_release_many (uint32_t num_locks)
	Drop several references taken with flash_use().
status_t	flash_read_security_register (uint32_t addr, uint8_t *val)
	Read a byte from a security register.
status_t	flash_security_register_is_locked (uint32_t addr, bool *locked)
	Check whether a security register is locked.
status_t	flash_erase_security_register (uint32_t addr)
	Erase a security register.
status_t	flash_write_security_register (uint32_t addr, uint8_t val)
	Write a byte to a security register.
const FlashSecurityRegisters *	flash_security_registers_info (void)
	Get the security register layout.

Variables
static const uint32_t	EXPECTED_SPI_FLASH_ID_32MBIT = 0x20bb16
	Expected ID of a 32 Mbit part.
static const uint32_t	EXPECTED_SPI_FLASH_ID_64MBIT = 0x20bb17
	Expected ID of a 64 Mbit part.

Detailed Description

External flash access.

Thread-safe API on top of a part-specific low-level driver (see Low-level flash driver). Reads and writes block; an in-progress erase is suspended while they run. Writes only clear bits, so the target range must be erased first. Erases work on subsectors and sectors, whose sizes depend on the part.

static void prv_erased(void *context, status_t result) {
  // Runs on a timer task: keep it short
}
 
flash_erase_subsector_blocking(addr);
flash_write_bytes(data, addr, sizeof(data));
flash_read_bytes(buf, addr, sizeof(buf));
 
flash_erase_sector(other_addr, prv_erased, NULL);

---

Data Structure Documentation

FlashSecurityRegisters

struct FlashSecurityRegisters

Security (OTP) registers of the flash part.

Data Fields
uint8_t	num_sec_regs	Number of security registers.
uint16_t	sec_reg_size	Size of each security register in bytes.
const uint32_t *	sec_regs	Base address of each security register.

Typedef Documentation

FlashOperationCompleteCb

typedef void(* FlashOperationCompleteCb) (void *context, status_t result)

Flash operation completion callback.

Parameters

context	User context.
result	S_SUCCESS, S_NO_ACTION_REQUIRED if the area was already erased, or an error.

Enumeration Type Documentation

FlashModeType

enum FlashModeType

Flash read mode.

Enumerator
FLASH_MODE_ASYNC	Asynchronous reads.
FLASH_MODE_SYNC_BURST	Synchronous burst reads.
FLASH_MODE_NUM_MODES	Number of modes.

Function Documentation

flash_crc32()

uint32_t flash_crc32	(	uint32_t	flash_addr,
		uint32_t	length
	)

Compute the CRC-32 of a flash region.

Parameters

flash_addr	Start address.
length	Length in bytes.

Returns

pbl_crc32() of the region.

flash_crc32_legacy()

uint32_t flash_crc32_legacy	(	uint32_t	flash_addr,
		uint32_t	length
	)

Compute the legacy checksum of a flash region.

Parameters

flash_addr	Start address.
length	Length in bytes.

Returns

pbl_crc32_legacy() of the region.

flash_enable_write_protection()

void flash_enable_write_protection

(

void

)

Enable write protection, if the part requires it to be enabled explicitly.

flash_erase_bulk()

void flash_erase_bulk

(

void

)

Erase the entire flash.

Blocks for up to a minute: make sure the watchdog does not fire.

flash_erase_optimal_range()

void flash_erase_optimal_range	(	uint32_t	min_start,
		uint32_t	max_start,
		uint32_t	min_end,
		uint32_t	max_end,
		FlashOperationCompleteCb	on_complete,
		void *	context
	)

Erase a range of flash asynchronously, using as few erase operations as possible.

Erases at least [max_start, min_end) and at most [min_start, max_end), using sector erases where possible and subsector erases elsewhere.

Parameters

min_start	Lowest address that may be erased, subsector aligned.
max_start	Highest address the erase may start at.
min_end	Lowest address the erase may end at (exclusive).
max_end	Highest address the erase may end at (exclusive), subsector aligned.
on_complete	Callback run once the whole range is erased or an erase failed.
context	User context passed to on_complete.

flash_erase_sector()

void flash_erase_sector	(	uint32_t	sector_addr,
		FlashOperationCompleteCb	on_complete,
		void *	context
	)

Erase the sector containing an address, asynchronously.

on_complete is called once the erase finishes, succeeded or not, from a timer task or directly from this function. It must return quickly.

Parameters

sector_addr	Address within the sector.
on_complete	Completion callback.
context	User context passed to on_complete.

flash_erase_sector_blocking()

void flash_erase_sector_blocking

(

uint32_t

sector_addr

)

Erase the sector containing an address.

Blocks until done, which takes 100 ms or more, and asserts on failure.

Parameters

sector_addr

Address within the sector.

flash_erase_security_register()

status_t flash_erase_security_register

(

uint32_t

addr

)

Erase a security register.

Parameters

addr	Security register address.

Returns

S_SUCCESS, E_INVALID_ARGUMENT if addr is not in a security register, or another error.

flash_erase_subsector()

void flash_erase_subsector	(	uint32_t	subsector_addr,
		FlashOperationCompleteCb	on_complete,
		void *	context
	)

Erase the subsector containing an address, asynchronously.

on_complete is called once the erase finishes, succeeded or not, from a timer task or directly from this function. It must return quickly.

Parameters

subsector_addr	Address within the subsector.
on_complete	Completion callback.
context	User context passed to on_complete.

flash_erase_subsector_blocking()

void flash_erase_subsector_blocking

(

uint32_t

subsector_addr

)

Erase the subsector containing an address.

Blocks until done and asserts on failure.

Parameters

subsector_addr

Address within the subsector.

flash_get_sector_base_address()

uint32_t flash_get_sector_base_address

(

uint32_t

flash_addr

)

Get the base address of the sector containing an address.

Parameters

flash_addr

Flash address.

Returns

Sector base address.

flash_get_sleep_when_idle()

bool flash_get_sleep_when_idle

(

void

)

Check whether flash_sleep_when_idle() is in effect.

Returns

true if enabled.

flash_get_subsector_base_address()

uint32_t flash_get_subsector_base_address

(

uint32_t

flash_addr

)

Get the base address of the subsector containing an address.

Parameters

flash_addr

Flash address.

Returns

Subsector base address.

flash_init()

void flash_init

(

void

)

Initialize the flash driver and the flash part.

flash_is_initialized()

bool flash_is_initialized

(

void

)

Check whether flash_init() has run.

Returns

true if initialized.

flash_power_down_for_stop_mode()

void flash_power_down_for_stop_mode

(

void

)

Put the flash in deep power-down before entering stop mode.

Takes no locks; call only with interrupts disabled. The part draws about 100 uA in standby and 10 uA in deep power-down, which only matters while the MCU is in stop mode.

flash_power_up_after_stop_mode()

void flash_power_up_after_stop_mode

(

void

)

Wake the flash after stop mode.

Counterpart of flash_power_down_for_stop_mode(), with the same constraints.

flash_prf_set_protection()

void flash_prf_set_protection

(

bool

do_protect

)

Write-protect the recovery firmware region, or remove all protection.

Parameters

do_protect

true to protect the region, false to unprotect the whole flash.

flash_read_bytes()

void flash_read_bytes	(	uint8_t *	buffer,
		uint32_t	start_addr,
		uint32_t	buffer_size
	)

Read from flash.

No range checking is done.

Parameters

[out]	buffer	Buffer receiving the data.
	start_addr	Flash address of the first byte.
	buffer_size	Number of bytes to read.

flash_read_security_register()

status_t flash_read_security_register	(	uint32_t	addr,
		uint8_t *	val
	)

Read a byte from a security register.

Parameters

	addr	Security register address.
[out]	val	Byte read.

Returns

S_SUCCESS, E_INVALID_ARGUMENT if addr is not in a security register, or another error.

flash_release_many()

void flash_release_many

(

uint32_t

num_locks

)

Drop several references taken with flash_use().

The peripheral is powered down when the count reaches zero.

Parameters

num_locks

Number of references to drop, usually 1.

flash_sector_is_erased()

bool flash_sector_is_erased

(

uint32_t

sector_addr

)

Check whether the sector containing an address is erased.

Parameters

sector_addr

Address within the sector.

Returns

true if erased.

flash_security_register_is_locked()

status_t flash_security_register_is_locked	(	uint32_t	addr,
		bool *	locked
	)

Check whether a security register is locked.

Parameters

	addr	Security register address.
[out]	locked	true if locked.

Returns

S_SUCCESS, E_INVALID_ARGUMENT if addr is not in a security register, or another error.

flash_security_registers_info()

const FlashSecurityRegisters * flash_security_registers_info

(

void

)

Get the security register layout.

Returns

Security register information.

flash_sleep_when_idle()

void flash_sleep_when_idle

(

bool

enable

)

Let the flash enter deep sleep between commands.

Parameters

enable

true to enable.

flash_stop()

void flash_stop

(

void

)

Stop flash activity.

Waits for an in-progress erase to finish. Does nothing before flash_init().

flash_subsector_is_erased()

bool flash_subsector_is_erased

(

uint32_t

sector_addr

)

Check whether the subsector containing an address is erased.

Parameters

sector_addr

Address within the subsector.

Returns

true if erased.

flash_switch_mode()

void flash_switch_mode

(

FlashModeType

mode

)

Switch the read mode.

Parameters

mode	New mode; burst mode is used only if the part supports it.

flash_use()

void flash_use

(

void

)

Take a reference keeping the flash peripheral powered.

Call before any flash access, including memory-mapped reads. Release with flash_release_many().

flash_write_bytes()

void flash_write_bytes	(	const uint8_t *	buffer,
		uint32_t	start_addr,
		uint32_t	buffer_size
	)

Write to flash.

Handles unaligned addresses and writes spanning several pages. Asserts on failure.

Parameters

buffer	Data to write.
start_addr	Flash address of the first byte.
buffer_size	Number of bytes to write.

flash_write_security_register()

status_t flash_write_security_register	(	uint32_t	addr,
		uint8_t	val
	)

Write a byte to a security register.

Parameters

addr	Security register address.
val	Byte to write.

Returns

S_SUCCESS, E_INVALID_ARGUMENT if addr is not in a security register, or another error.

Variable Documentation

EXPECTED_SPI_FLASH_ID_32MBIT

const uint32_t EXPECTED_SPI_FLASH_ID_32MBIT = 0x20bb16

static

Expected ID of a 32 Mbit part.

EXPECTED_SPI_FLASH_ID_64MBIT

const uint32_t EXPECTED_SPI_FLASH_ID_64MBIT = 0x20bb17

static

Expected ID of a 64 Mbit part.