Files
file	ext-flash.c
	Implementation of a generic external SPI flash driver.

file	ext-flash.h
	Header file for the external SPI flash API.

Macros
#define	BLS_CODE_PROGRAM 0x02
	Page Program.

#define	BLS_CODE_READ 0x03
	Read Data.

#define	BLS_CODE_READ_STATUS 0x05
	Read Status Register.

#define	BLS_CODE_WRITE_ENABLE 0x06
	Write Enable.

#define	BLS_CODE_SECTOR_ERASE 0x20
	Sector Erase.

#define	BLS_CODE_MDID 0x90
	Manufacturer Device ID.

#define	BLS_CODE_PD 0xB9
	Power down.

#define	BLS_CODE_RPD 0xAB
	Release Power-Down.

#define	BLS_CODE_ERASE_4K 0x20
	Sector Erase.

#define	BLS_CODE_ERASE_ALL 0xC7
	Mass Erase.

#define	BLS_STATUS_BIT_BUSY 0x01
	Busy bit of the status register.

Functions
static const spi_device_t *	get_spi_conf (const spi_device_t *conf)
	Get spi configuration, return default configuration if NULL.

static bool	select_on_bus (const spi_device_t *flash_spi_configuration)
	Clear external flash CSN line.

static void	deselect (const spi_device_t *flash_spi_configuration)
	Set external flash CSN line.

static bool	wait_ready (const spi_device_t *flash_spi_configuration)
	Wait till previous erase/program operation completes.

static uint8_t	verify_part (const spi_device_t *flash_spi_configuration)
	Verify the flash part.

static bool	power_down (const spi_device_t *flash_spi_configuration)
	Put the device in power save mode.

static bool	power_standby (const spi_device_t *flash_spi_configuration)
	Take device out of power save mode and prepare it for normal operation.

static bool	write_enable (const spi_device_t *flash_spi_configuration)
	Enable write.

bool	ext_flash_open (const spi_device_t *conf)
	Initialize storage driver.

bool	ext_flash_close (const spi_device_t *conf)
	Close the storage driver.

bool	ext_flash_read (const spi_device_t conf, uint32_t offset, uint32_t length, uint8_t buf)
	Read storage content.

bool	ext_flash_write (const spi_device_t conf, uint32_t offset, uint32_t length, const uint8_t buf)
	Write to storage sectors.

bool	ext_flash_erase (const spi_device_t *conf, uint32_t offset, uint32_t length)
	Erase storage sectors corresponding to the range.

bool	ext_flash_init (const spi_device_t *conf)
	Initialise the external flash.

Detailed Description

This is a generic driver for external SPI flash memories. The driver has been tested and works with multiple external SPI flash parts. The list of parts the driver has been tested against is shown in the README in this directory.

If you successfully use this driver with a part that is not listed in the README, please let us know so we can update it.

Function Documentation

◆ ext_flash_close()

bool ext_flash_close ( const spi_device_t * conf )

Close the storage driver.

Parameters

conf	SPI bus configuration struct. NULL for default.

Returns: True when successful.

This call will put the device in its lower power mode (power down).

Definition at line 355 of file ext-flash.c.

References get_spi_conf(), power_down(), and spi_release().

Referenced by ext_flash_init(), xmem_erase(), xmem_pread(), and xmem_pwrite().

◆ ext_flash_erase()

bool ext_flash_erase	(	const spi_device_t *	conf,
		uint32_t	offset,
		uint32_t	length )

Erase storage sectors corresponding to the range.

Parameters

conf	SPI bus configuration struct. NULL for default.
offset	Address to start erasing
length	Number of bytes to erase

Returns: True when successful.

The erase operation will be sector-wise, therefore a call to this function will generally start the erase procedure at an address lower than offset

< Sector Erase

Definition at line 475 of file ext-flash.c.

References BLS_CODE_SECTOR_ERASE, deselect(), get_spi_conf(), select_on_bus(), spi_write(), wait_ready(), and write_enable().

Referenced by xmem_erase().

◆ ext_flash_init()

bool ext_flash_init ( const spi_device_t * conf )

Initialise the external flash.

Parameters

conf	SPI bus configuration struct. NULL for default.

This function will explicitly put the part in its lowest power mode (power-down).

In order to perform any operation, the caller must first wake the device up by calling ext_flash_open()

Definition at line 527 of file ext-flash.c.

References ext_flash_close(), and ext_flash_open().

Referenced by board_init(), and xmem_init().

◆ ext_flash_open()

bool ext_flash_open ( const spi_device_t * conf )

Initialize storage driver.

Parameters

conf	SPI bus configuration struct. NULL for default.

Returns: True when successful.

Definition at line 325 of file ext-flash.c.

References deselect(), get_spi_conf(), GPIO_HAL_PIN_UNKNOWN, power_standby(), spi_acquire(), spi_release(), and verify_part().

Referenced by ext_flash_init(), xmem_erase(), xmem_pread(), and xmem_pwrite().

◆ ext_flash_read()

bool ext_flash_read	(	const spi_device_t *	conf,
		uint32_t	offset,
		uint32_t	length,
		uint8_t *	buf )

Read storage content.

Parameters

conf	SPI bus configuration struct. NULL for default.
offset	Address to read from
length	Number of bytes to read
buf	Buffer where to store the read bytes

Returns: True when successful.

buf must be allocated by the caller

< Read Data

Definition at line 374 of file ext-flash.c.

References BLS_CODE_READ, deselect(), get_spi_conf(), select_on_bus(), spi_read(), spi_write(), and wait_ready().

Referenced by xmem_pread().

◆ ext_flash_write()

bool ext_flash_write	(	const spi_device_t *	conf,
		uint32_t	offset,
		uint32_t	length,
		const uint8_t *	buf )

Write to storage sectors.

Parameters

conf	SPI bus configuration struct. NULL for default.
offset	Address to write to
length	Number of bytes to write
buf	Buffer holding the bytes to be written

Returns: True when successful.

< Page Program

Definition at line 415 of file ext-flash.c.

References BLS_CODE_PROGRAM, deselect(), get_spi_conf(), select_on_bus(), spi_write(), wait_ready(), and write_enable().

Referenced by xmem_pwrite().

◆ power_down()

static bool power_down ( const spi_device_t * flash_spi_configuration )

static

Put the device in power save mode.

No access to data; only the status register is accessible.

< Power down

Definition at line 239 of file ext-flash.c.

References BLS_CODE_PD, deselect(), select_on_bus(), spi_write_byte(), verify_part(), and wait_ready().

Referenced by ext_flash_close().

◆ power_standby()

static bool power_standby ( const spi_device_t * flash_spi_configuration )

static

Take device out of power save mode and prepare it for normal operation.

Returns: True if the command was written successfully

< Release Power-Down

Definition at line 280 of file ext-flash.c.

References BLS_CODE_RPD, deselect(), select_on_bus(), spi_write(), and wait_ready().

Referenced by ext_flash_open().

◆ verify_part()

static uint8_t verify_part ( const spi_device_t * flash_spi_configuration )

static

Verify the flash part.

Return values

VERIFY_PART_OK	The part was identified successfully
VERIFY_PART_ERROR	There was an error communicating with the part
VERIFY_PART_POWERED_DOWN	Communication was successful, but the part was powered down

< Manufacturer Device ID

Definition at line 205 of file ext-flash.c.

References BLS_CODE_MDID, deselect(), select_on_bus(), spi_read(), and spi_write().

Referenced by ext_flash_open(), and power_down().