Low-level flash driver

Interface implemented by each flash part driver. More...

Typedefs
typedef uint32_t	FlashAddress
	Flash address.

Functions
status_t	flash_impl_init (bool coredump_mode)
	Initialize the driver and bring the part to a state ready to accept commands.
status_t	flash_impl_set_burst_mode (bool enable)
	Enable or disable synchronous burst mode, if supported.
FlashAddress	flash_impl_get_sector_base_address (FlashAddress addr)
	Get the base address of the sector containing an address.
FlashAddress	flash_impl_get_subsector_base_address (FlashAddress addr)
	Get the base address of the subsector containing an address.
size_t	flash_impl_get_capacity (void)
	Get the flash capacity.
status_t	flash_impl_enter_low_power_mode (void)
	Enter a low-power state.
status_t	flash_impl_exit_low_power_mode (void)
	Leave the low-power state.
status_t	flash_impl_read_sync (void *buffer, FlashAddress addr, size_t len)
	Read data.
void	flash_impl_enable_write_protection (void)
	Enable write protection, if the part requires it to be enabled explicitly.
status_t	flash_impl_write_protect (FlashAddress start_sector, FlashAddress end_sector)
	Write-protect a range of sectors.
status_t	flash_impl_unprotect (void)
	Remove write protection.
int	flash_impl_write_page_begin (const void *buffer, FlashAddress addr, size_t len)
	Start writing up to a page.
status_t	flash_impl_get_write_status (void)
	Poll the status of a page write.
status_t	flash_impl_write_suspend (FlashAddress addr)
	Suspend an in-progress write so reads and erases are permitted.
status_t	flash_impl_write_resume (FlashAddress addr)
	Resume a suspended write.
status_t	flash_impl_erase_subsector_begin (FlashAddress subsector_addr)
	Start erasing the subsector containing an address.
status_t	flash_impl_erase_sector_begin (FlashAddress sector_addr)
	Start erasing the sector containing an address.
status_t	flash_impl_erase_bulk_begin (void)
	Start erasing the entire flash.
status_t	flash_impl_get_erase_status (void)
	Poll the status of an erase.
uint32_t	flash_impl_get_typical_subsector_erase_duration_ms (void)
	Get the typical subsector erase duration.
uint32_t	flash_impl_get_typical_sector_erase_duration_ms (void)
	Get the typical sector erase duration.
status_t	flash_impl_erase_suspend (FlashAddress addr)
	Suspend an in-progress erase so reads and writes are permitted.
status_t	flash_impl_erase_resume (FlashAddress addr)
	Resume a suspended erase.
status_t	flash_impl_blank_check_subsector (FlashAddress addr)
	Check whether the subsector containing an address is blank (all ones).
status_t	flash_impl_blank_check_sector (FlashAddress addr)
	Check whether the sector containing an address is blank (all ones).
void	flash_impl_use (void)
	Take a reference keeping the flash peripheral powered.
void	flash_impl_release (void)
	Drop one reference taken with flash_impl_use().
void	flash_impl_release_many (uint32_t num_locks)
	Drop several references taken with flash_impl_use().
status_t	flash_impl_read_security_register (uint32_t addr, uint8_t *val)
	Read a byte from a security register.
status_t	flash_impl_security_register_is_locked (uint32_t address, bool *locked)
	Check whether a security register is locked.
status_t	flash_impl_erase_security_register (uint32_t addr)
	Erase a security register.
status_t	flash_impl_write_security_register (uint32_t addr, uint8_t val)
	Write a byte to a security register.
const FlashSecurityRegisters *	flash_impl_security_registers_info (void)
	Get the security register layout.

Detailed Description

Interface implemented by each flash part driver.

Used by the flash API and by the core dump flash driver. Implementations do not rely on OS services, except where noted.

Unless otherwise specified, functions are not reentrant: do not call one while another runs in a different thread, nor from within a flash_impl callback.

Typedef Documentation

FlashAddress

typedef uint32_t FlashAddress

Flash address.

Function Documentation

flash_impl_blank_check_sector()

status_t flash_impl_blank_check_sector

(

FlashAddress

addr

)

Check whether the sector containing an address is blank (all ones).

Hardware accelerated where possible. Must not be called while any read, write or erase is in progress or suspended, cannot be suspended, and no other operation may start until it returns.

Warning

A sector whose erase was interrupted may read as blank while not being fully erased; writing it may then fail or lose data.

Parameters

addr	Address within the sector.

Return values

S_TRUE	Blank.
S_FALSE	At least one bit is programmed.
E_BUSY	Another operation is in progress.

flash_impl_blank_check_subsector()

status_t flash_impl_blank_check_subsector

(

FlashAddress

addr

)

Check whether the subsector containing an address is blank (all ones).

Hardware accelerated where possible. Must not be called while any read, write or erase is in progress or suspended, cannot be suspended, and no other operation may start until it returns.

Warning

A subsector whose erase was interrupted may read as blank while not being fully erased; writing it may then fail or lose data.

Parameters

addr	Address within the subsector.

Return values

S_TRUE	Blank.
S_FALSE	At least one bit is programmed.
E_BUSY	Another operation is in progress.

flash_impl_enable_write_protection()

void flash_impl_enable_write_protection

(

void

)

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

flash_impl_enter_low_power_mode()

status_t flash_impl_enter_low_power_mode

(

void

)

Enter a low-power state.

Operations may fail until flash_impl_exit_low_power_mode() is called. Idempotent.

Returns

S_SUCCESS or an error.

flash_impl_erase_bulk_begin()

status_t flash_impl_erase_bulk_begin

(

void

)

Start erasing the entire flash.

The result is undefined if a read or write is in progress. It is an error to call this while an erase is suspended.

Returns

S_SUCCESS or an error.

flash_impl_erase_resume()

status_t flash_impl_erase_resume

(

FlashAddress

addr

)

Resume a suspended erase.

The result is undefined if a read or write is in progress.

Parameters

addr	Address passed to flash_impl_erase_suspend().

Returns

S_SUCCESS or an error.

flash_impl_erase_sector_begin()

status_t flash_impl_erase_sector_begin

(

FlashAddress

sector_addr

)

Start erasing the sector containing an address.

The result is undefined if a read or write is in progress. It is an error to call this while an erase is suspended.

Parameters

sector_addr

Address within the sector.

Returns

S_SUCCESS or an error.

flash_impl_erase_security_register()

status_t flash_impl_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_impl_erase_subsector_begin()

status_t flash_impl_erase_subsector_begin

(

FlashAddress

subsector_addr

)

Start erasing the subsector containing an address.

The result is undefined if a read or write is in progress. It is an error to call this while an erase is suspended.

Parameters

subsector_addr

Address within the subsector.

Returns

S_SUCCESS or an error.

flash_impl_erase_suspend()

status_t flash_impl_erase_suspend

(

FlashAddress

addr

)

Suspend an in-progress erase so reads and writes are permitted.

Parameters

addr	Address passed to the flash_impl_erase_subsector_begin() or flash_impl_erase_sector_begin() call that started the erase.

Return values

S_SUCCESS	The erase is suspended.
S_NO_ACTION_REQUIRED	No erase was in progress.

Returns

Otherwise an error.

flash_impl_exit_low_power_mode()

status_t flash_impl_exit_low_power_mode

(

void

)

Leave the low-power state.

May take a while. Idempotent.

Returns

S_SUCCESS or an error.

flash_impl_get_capacity()

size_t flash_impl_get_capacity

(

void

)

Get the flash capacity.

Returns

Capacity in bytes.

flash_impl_get_erase_status()

status_t flash_impl_get_erase_status

(

void

)

Poll the status of an erase.

Return values

S_SUCCESS	The erase succeeded.
E_ERROR	The erase failed.
E_BUSY	The erase is in progress.
E_AGAIN	The erase is suspended.

flash_impl_get_sector_base_address()

FlashAddress flash_impl_get_sector_base_address

(

FlashAddress

addr

)

Get the base address of the sector containing an address.

Reentrant.

Parameters

addr	Flash address.

Returns

Sector base address.

flash_impl_get_subsector_base_address()

FlashAddress flash_impl_get_subsector_base_address

(

FlashAddress

addr

)

Get the base address of the subsector containing an address.

Reentrant.

Parameters

addr	Flash address.

Returns

Subsector base address.

flash_impl_get_typical_sector_erase_duration_ms()

uint32_t flash_impl_get_typical_sector_erase_duration_ms

(

void

)

Get the typical sector erase duration.

Reentrant.

Returns

Duration in milliseconds.

flash_impl_get_typical_subsector_erase_duration_ms()

uint32_t flash_impl_get_typical_subsector_erase_duration_ms

(

void

)

Get the typical subsector erase duration.

Reentrant.

Returns

Duration in milliseconds.

flash_impl_get_write_status()

status_t flash_impl_get_write_status

(

void

)

Poll the status of a page write.

Return values

S_SUCCESS	The write succeeded.
E_ERROR	The write failed.
E_BUSY	The write is in progress.
E_AGAIN	The write is suspended.

flash_impl_init()

status_t flash_impl_init

(

bool

coredump_mode

)

Initialize the driver and bring the part to a state ready to accept commands.

Parameters

coredump_mode

Do not rely on any OS service, because a core dump is in progress. Operations may be slower.

Returns

S_SUCCESS or an error.

flash_impl_read_security_register()

status_t flash_impl_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_impl_read_sync()

status_t flash_impl_read_sync	(	void *	buffer,
		FlashAddress	addr,
		size_t	len
	)

Read data.

The result is undefined if a write or erase is in progress.

Parameters

[out]	buffer	Buffer receiving the data.
	addr	Flash address.
	len	Number of bytes to read.

Returns

S_SUCCESS or an error.

flash_impl_release()

void flash_impl_release

(

void

)

Drop one reference taken with flash_impl_use().

flash_impl_release_many()

void flash_impl_release_many

(

uint32_t

num_locks

)

Drop several references taken with flash_impl_use().

Parameters

num_locks

Number of references to drop.

flash_impl_security_register_is_locked()

status_t flash_impl_security_register_is_locked	(	uint32_t	address,
		bool *	locked
	)

Check whether a security register is locked.

Parameters

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

Returns

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

flash_impl_security_registers_info()

const FlashSecurityRegisters * flash_impl_security_registers_info

(

void

)

Get the security register layout.

Returns

Security register information.

flash_impl_set_burst_mode()

status_t flash_impl_set_burst_mode

(

bool

enable

)

Enable or disable synchronous burst mode, if supported.

Burst mode is disabled by flash_impl_init(). The result is undefined if another operation is in progress.

Parameters

enable

true to enable burst mode.

Returns

S_SUCCESS or an error.

flash_impl_unprotect()

status_t flash_impl_unprotect

(

void

)

Remove write protection.

The result is undefined if a write or erase is in progress.

Returns

S_SUCCESS or an error.

flash_impl_use()

void flash_impl_use

(

void

)

Take a reference keeping the flash peripheral powered.

flash_impl_write_page_begin()

int flash_impl_write_page_begin	(	const void *	buffer,
		FlashAddress	addr,
		size_t	len
	)

Start writing up to a page.

Starts a single program operation with as much data as the part accepts at once; writing a whole buffer may take several calls:

while (len) {
  int written = flash_impl_write_page_begin(buffer, addr, len);
  if (written < 0) {
    // Handle error
  }
  status_t status;
  while ((status = flash_impl_get_write_status()) == E_BUSY) {
    continue;
  }
  if (status != S_SUCCESS) {
    // Handle error
  }
  buffer += written;
  addr += written;
  len -= written;
}

The result is undefined if a read or erase is in progress. It is an error to call this while a write is in progress or suspended.

Parameters

buffer	Data to write.
addr	Flash address.
len	Number of bytes available in buffer.

Returns

Number of bytes that will be written if the write completes, or a negative StatusCode if the write could not be started.

flash_impl_write_protect()

status_t flash_impl_write_protect	(	FlashAddress	start_sector,
		FlashAddress	end_sector
	)

Write-protect a range of sectors.

Only one range may be protected at a time. The result is undefined if a write or erase is in progress.

Parameters

start_sector	Address of the first protected sector.
end_sector	Address of the last protected sector.

Returns

S_SUCCESS or an error.

flash_impl_write_resume()

status_t flash_impl_write_resume

(

FlashAddress

addr

)

Resume a suspended write.

The result is undefined if a read or write is in progress.

Parameters

addr	Address passed to flash_impl_write_suspend().

Returns

S_SUCCESS or an error.

flash_impl_write_security_register()

status_t flash_impl_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.

flash_impl_write_suspend()

status_t flash_impl_write_suspend

(

FlashAddress

addr

)

Suspend an in-progress write so reads and erases are permitted.

Parameters

addr	Address passed to the flash_impl_write_page_begin() call that started the write.

Returns

S_SUCCESS or an error.