SPI Flash API

Collaboration diagram for SPI Flash API:

Classes
struct	SPIFlashInfo
	SPI Flash memory information block. Copied from bootloader header. See esp_image_header_t. More...
struct	STORE_TYPEDEF_ATTR
	SPI Flash memory information block. Stored at the beginning of flash memory. More...

Macros
#define	INTERNAL_FLASH_WRITE_UNIT_SIZE   4
	Flash memory access must be aligned and in multiples of 4-byte words. More...
#define	INTERNAL_FLASH_READ_UNIT_SIZE   4
#define	FLASH_TOTAL_SEC_COUNT   (flashmem_get_size_sectors())
#define	SYS_PARAM_SEC_COUNT   4
	Number of flash sectors reserved for system parameters at start. More...
#define	FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)
#define	INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE
#define	INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)
#define	INTERNAL_FLASH_WRITE_UNIT_SIZE   4
	Flash memory access must be aligned and in multiples of 4-byte words. More...
#define	INTERNAL_FLASH_READ_UNIT_SIZE   4
#define	FLASH_TOTAL_SEC_COUNT   (flashmem_get_size_sectors())
#define	SYS_PARAM_SEC_COUNT   4
	Number of flash sectors reserved for system parameters at start. More...
#define	FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)
#define	INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE
#define	INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)
#define	INTERNAL_FLASH_START_ADDRESS   0x40200000
#define	FLASH_TOTAL_SEC_COUNT   PICO_FLASH_SIZE_BYTES
#define	SYS_PARAM_SEC_COUNT   4
	Number of flash sectors reserved for system parameters at start. More...
#define	FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)
#define	INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE
#define	INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)
#define	INTERNAL_FLASH_START_ADDRESS   FLASH_BASE

Enumerations
enum	SPIFlashMode {   MODE_QIO = ESP_IMAGE_SPI_MODE_QIO , MODE_QOUT = ESP_IMAGE_SPI_MODE_QOUT , MODE_DIO = ESP_IMAGE_SPI_MODE_DIO , MODE_DOUT = ESP_IMAGE_SPI_MODE_DOUT ,   MODE_FAST_READ = ESP_IMAGE_SPI_MODE_FAST_READ , MODE_SLOW_READ = ESP_IMAGE_SPI_MODE_SLOW_READ , MODE_QIO = 0 , MODE_QOUT = 1 ,   MODE_DIO = 2 , MODE_DOUT = 15 , MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF ,   MODE_QIO = 0 , MODE_QOUT = 1 , MODE_DIO = 2 , MODE_DOUT = 15 ,   MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF }
enum	SPIFlashSpeed {   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 0x0f ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 }
enum	SPIFlashSize {   SIZE_1MBIT = ESP_IMAGE_FLASH_SIZE_1MB , SIZE_2MBIT = ESP_IMAGE_FLASH_SIZE_2MB , SIZE_4MBIT = ESP_IMAGE_FLASH_SIZE_4MB , SIZE_8MBIT = ESP_IMAGE_FLASH_SIZE_8MB ,   SIZE_16MBIT = ESP_IMAGE_FLASH_SIZE_16MB , SIZE_32MBIT = 0xFF , SIZE_4MBIT = 0 , SIZE_2MBIT = 1 ,   SIZE_8MBIT = 2 , SIZE_16MBIT = 3 , SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF ,   SIZE_4MBIT = 0 , SIZE_2MBIT = 1 , SIZE_8MBIT = 2 , SIZE_16MBIT = 3 ,   SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF }
enum	SPIFlashMode {   MODE_QIO = ESP_IMAGE_SPI_MODE_QIO , MODE_QOUT = ESP_IMAGE_SPI_MODE_QOUT , MODE_DIO = ESP_IMAGE_SPI_MODE_DIO , MODE_DOUT = ESP_IMAGE_SPI_MODE_DOUT ,   MODE_FAST_READ = ESP_IMAGE_SPI_MODE_FAST_READ , MODE_SLOW_READ = ESP_IMAGE_SPI_MODE_SLOW_READ , MODE_QIO = 0 , MODE_QOUT = 1 ,   MODE_DIO = 2 , MODE_DOUT = 15 , MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF ,   MODE_QIO = 0 , MODE_QOUT = 1 , MODE_DIO = 2 , MODE_DOUT = 15 ,   MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF }
enum	SPIFlashSpeed {   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 0x0f ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 }
enum	SPIFlashSize {   SIZE_1MBIT = ESP_IMAGE_FLASH_SIZE_1MB , SIZE_2MBIT = ESP_IMAGE_FLASH_SIZE_2MB , SIZE_4MBIT = ESP_IMAGE_FLASH_SIZE_4MB , SIZE_8MBIT = ESP_IMAGE_FLASH_SIZE_8MB ,   SIZE_16MBIT = ESP_IMAGE_FLASH_SIZE_16MB , SIZE_32MBIT = 0xFF , SIZE_4MBIT = 0 , SIZE_2MBIT = 1 ,   SIZE_8MBIT = 2 , SIZE_16MBIT = 3 , SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF ,   SIZE_4MBIT = 0 , SIZE_2MBIT = 1 , SIZE_8MBIT = 2 , SIZE_16MBIT = 3 ,   SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF }
enum	SPIFlashMode {   MODE_QIO = ESP_IMAGE_SPI_MODE_QIO , MODE_QOUT = ESP_IMAGE_SPI_MODE_QOUT , MODE_DIO = ESP_IMAGE_SPI_MODE_DIO , MODE_DOUT = ESP_IMAGE_SPI_MODE_DOUT ,   MODE_FAST_READ = ESP_IMAGE_SPI_MODE_FAST_READ , MODE_SLOW_READ = ESP_IMAGE_SPI_MODE_SLOW_READ , MODE_QIO = 0 , MODE_QOUT = 1 ,   MODE_DIO = 2 , MODE_DOUT = 15 , MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF ,   MODE_QIO = 0 , MODE_QOUT = 1 , MODE_DIO = 2 , MODE_DOUT = 15 ,   MODE_SLOW_READ = 0xFE , MODE_FAST_READ = 0xFF }
enum	SPIFlashSpeed {   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 0x0f ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 ,   SPEED_40MHZ = 0 , SPEED_26MHZ = 1 , SPEED_20MHZ = 2 , SPEED_80MHZ = 15 }
enum	SPIFlashSize {   SIZE_1MBIT = ESP_IMAGE_FLASH_SIZE_1MB , SIZE_2MBIT = ESP_IMAGE_FLASH_SIZE_2MB , SIZE_4MBIT = ESP_IMAGE_FLASH_SIZE_4MB , SIZE_8MBIT = ESP_IMAGE_FLASH_SIZE_8MB ,   SIZE_16MBIT = ESP_IMAGE_FLASH_SIZE_16MB , SIZE_32MBIT = 0xFF , SIZE_4MBIT = 0 , SIZE_2MBIT = 1 ,   SIZE_8MBIT = 2 , SIZE_16MBIT = 3 , SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF ,   SIZE_4MBIT = 0 , SIZE_2MBIT = 1 , SIZE_8MBIT = 2 , SIZE_16MBIT = 3 ,   SIZE_32MBIT = 4 , SIZE_1MBIT = 0xFF }

Functions
static uint32_t	flashmem_get_address (const void *memptr)
	Obtain the flash memory address for a memory pointer. More...
uint32_t	flashmem_write (const void *from, uint32_t toaddr, uint32_t size)
	Write a block of data to flash. More...
uint32_t	flashmem_read (void *to, uint32_t fromaddr, uint32_t size)
	Read a block of data from flash. More...
bool	flashmem_erase_sector (uint32_t sector_id)
	Erase a single flash sector. More...
SPIFlashInfo	flashmem_get_info ()
	Get flash memory information block. More...
uint8_t	flashmem_get_size_type ()
	Returns a number indicating the size of flash memory chip. More...
uint32_t	flashmem_get_size_bytes ()
	get the total flash memory size More...
uint16_t	flashmem_get_size_sectors ()
	Get the total number of flash sectors. More...
uint32_t	flashmem_find_sector (uint32_t address, uint32_t *pstart, uint32_t *pend)
	Helper function: find the flash sector in which an address resides. More...
uint32_t	flashmem_get_sector_of_address (uint32_t addr)
	Get sector number containing the given address. More...
uint32_t	spi_flash_get_id (void)
uint32_t	flashmem_write_internal (const void *from, uint32_t toaddr, uint32_t size)
	write to flash memory More...
uint32_t	flashmem_read_internal (void *to, uint32_t fromaddr, uint32_t size)
	Read from flash memory. More...
uint32_t	flashmem_get_first_free_block_address ()
void	flashmem_sfdp_read (uint32_t addr, void *buffer, size_t count)

Detailed Description

Macro Definition Documentation

FLASH_TOTAL_SEC_COUNT [1/3]

#define FLASH_TOTAL_SEC_COUNT   (flashmem_get_size_sectors())

FLASH_TOTAL_SEC_COUNT [2/3]

#define FLASH_TOTAL_SEC_COUNT   (flashmem_get_size_sectors())

FLASH_TOTAL_SEC_COUNT [3/3]

#define FLASH_TOTAL_SEC_COUNT   PICO_FLASH_SIZE_BYTES

FLASH_WORK_SEC_COUNT [1/3]

#define FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)

FLASH_WORK_SEC_COUNT [2/3]

#define FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)

FLASH_WORK_SEC_COUNT [3/3]

#define FLASH_WORK_SEC_COUNT   (FLASH_TOTAL_SEC_COUNT - SYS_PARAM_SEC_COUNT)

INTERNAL_FLASH_READ_UNIT_SIZE [1/2]

#define INTERNAL_FLASH_READ_UNIT_SIZE   4

INTERNAL_FLASH_READ_UNIT_SIZE [2/2]

#define INTERNAL_FLASH_READ_UNIT_SIZE   4

INTERNAL_FLASH_SECTOR_SIZE [1/3]

#define INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE

INTERNAL_FLASH_SECTOR_SIZE [2/3]

#define INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE

INTERNAL_FLASH_SECTOR_SIZE [3/3]

#define INTERNAL_FLASH_SECTOR_SIZE   SPI_FLASH_SEC_SIZE

INTERNAL_FLASH_SIZE [1/3]

#define INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)

INTERNAL_FLASH_SIZE [2/3]

#define INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)

INTERNAL_FLASH_SIZE [3/3]

#define INTERNAL_FLASH_SIZE   ((FLASH_WORK_SEC_COUNT)*INTERNAL_FLASH_SECTOR_SIZE)

INTERNAL_FLASH_START_ADDRESS [1/2]

#define INTERNAL_FLASH_START_ADDRESS   0x40200000

INTERNAL_FLASH_START_ADDRESS [2/2]

#define INTERNAL_FLASH_START_ADDRESS   FLASH_BASE

INTERNAL_FLASH_WRITE_UNIT_SIZE [1/2]

#define INTERNAL_FLASH_WRITE_UNIT_SIZE   4

Flash memory access must be aligned and in multiples of 4-byte words.

INTERNAL_FLASH_WRITE_UNIT_SIZE [2/2]

#define INTERNAL_FLASH_WRITE_UNIT_SIZE   4

Flash memory access must be aligned and in multiples of 4-byte words.

SYS_PARAM_SEC_COUNT [1/3]

#define SYS_PARAM_SEC_COUNT   4

Number of flash sectors reserved for system parameters at start.

SYS_PARAM_SEC_COUNT [2/3]

#define SYS_PARAM_SEC_COUNT   4

Number of flash sectors reserved for system parameters at start.

SYS_PARAM_SEC_COUNT [3/3]

#define SYS_PARAM_SEC_COUNT   4

Number of flash sectors reserved for system parameters at start.

Enumeration Type Documentation

SPIFlashMode [1/3]

enum SPIFlashMode

Enumerator
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_FAST_READ
MODE_SLOW_READ
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.

SPIFlashMode [2/3]

enum SPIFlashMode

Enumerator
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_FAST_READ
MODE_SLOW_READ
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.

SPIFlashMode [3/3]

enum SPIFlashMode

Enumerator
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_FAST_READ
MODE_SLOW_READ
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.
MODE_QIO
MODE_QOUT
MODE_DIO
MODE_DOUT
MODE_SLOW_READ	Not supported.
MODE_FAST_READ	Not supported.

SPIFlashSize [1/3]

enum SPIFlashSize

Enumerator
SIZE_1MBIT
SIZE_2MBIT
SIZE_4MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT	Not listed.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.

SPIFlashSize [2/3]

enum SPIFlashSize

Enumerator
SIZE_1MBIT
SIZE_2MBIT
SIZE_4MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT	Not listed.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.

SPIFlashSize [3/3]

enum SPIFlashSize

Enumerator
SIZE_1MBIT
SIZE_2MBIT
SIZE_4MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT	Not listed.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.
SIZE_4MBIT
SIZE_2MBIT
SIZE_8MBIT
SIZE_16MBIT
SIZE_32MBIT
SIZE_1MBIT	Not supported.

SPIFlashSpeed [1/3]

enum SPIFlashSpeed

Enumerator
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ

SPIFlashSpeed [2/3]

enum SPIFlashSpeed

Enumerator
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ

SPIFlashSpeed [3/3]

enum SPIFlashSpeed

Enumerator
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ
SPEED_40MHZ
SPEED_26MHZ
SPEED_20MHZ
SPEED_80MHZ

Function Documentation

flashmem_erase_sector()

bool flashmem_erase_sector

(

uint32_t

sector_id

)

Erase a single flash sector.

Parameters

sector_id

the sector to erase

Return values

true	on success

flashmem_find_sector()

uint32_t flashmem_find_sector	(	uint32_t	address,
		uint32_t *	pstart,
		uint32_t *	pend
	)

Helper function: find the flash sector in which an address resides.

Parameters

address
pstart	OUT/OPTIONAL: Start of sector containing the given address
pend	OUT/OPTIONAL: Last address in sector

Return values

uint32_t

Sector number for the given address

Note

Optional parameters may be null

flashmem_get_address()

static uint32_t flashmem_get_address ( const void *  memptr )

inlinestatic

Obtain the flash memory address for a memory pointer.

Parameters

memptr

Return values

uint32_t

Offset from start of flash memory

Note

If memptr is not in valid flash memory it will return an offset which exceeds the internal flash memory size.

The flash location is dependent on where rBoot has mapped the firmware.

flashmem_get_first_free_block_address()

uint32_t flashmem_get_first_free_block_address

(

)

flashmem_get_info()

SPIFlashInfo flashmem_get_info

(

)

Get flash memory information block.

Return values

SPIFlashInfo

Information block

flashmem_get_sector_of_address()

uint32_t flashmem_get_sector_of_address

(

uint32_t

addr

)

Get sector number containing the given address.

Parameters

addr

Return values

uint32_t

sector number

flashmem_get_size_bytes()

uint32_t flashmem_get_size_bytes

(

)

get the total flash memory size

Return values

uint32_t

Size in bytes

flashmem_get_size_sectors()

uint16_t flashmem_get_size_sectors

(

)

Get the total number of flash sectors.

Return values

uint16_t

Sector count

flashmem_get_size_type()

uint8_t flashmem_get_size_type

(

)

Returns a number indicating the size of flash memory chip.

Return values

uint8_t

See SpiFlashInfo.size field for possible values

flashmem_read()

uint32_t flashmem_read	(	void *	to,
		uint32_t	fromaddr,
		uint32_t	size
	)

Read a block of data from flash.

Parameters

to	Buffer to store data
fromaddr	Flash location to start reading
size	Number of bytes to read

Return values

uint32_t

Number of bytes written

Note

none of the parameters need to be aligned

flashmem_read_internal()

uint32_t flashmem_read_internal	(	void *	to,
		uint32_t	fromaddr,
		uint32_t	size
	)

Read from flash memory.

Parameters

to	Buffer to store data - MUST be word-aligned
fromaddr	Flash address (offset) to read from - MUST be word-aligned
size	Number of bytes to read - MUST be word-aligned

Return values

uint32_t

Number of bytes actually read

Note

All parameters MUST be aligned to 4-byte word boundaries, including the RAM pointer

flashmem_sfdp_read()

void flashmem_sfdp_read	(	uint32_t	addr,
		void *	buffer,
		size_t	count
	)

flashmem_write()

uint32_t flashmem_write	(	const void *	from,
		uint32_t	toaddr,
		uint32_t	size
	)

Write a block of data to flash.

Parameters

from	Buffer to obtain data from
toaddr	Flash location to start writing
size	Number of bytes to write

Return values

uint32_t

Number of bytes written

Note

None of the parameters need to be aligned

flashmem_write_internal()

uint32_t flashmem_write_internal	(	const void *	from,
		uint32_t	toaddr,
		uint32_t	size
	)

write to flash memory

Parameters

from	Buffer to read data from - MUST be word-aligned
toaddr	Flash address (offset) to write to - MUST be word-aligned
size	Number of bytes to write - MUST be word-aligned

Return values

uint32_t

Number of bytes actually written

Note

All parameters MUST be aligned to 4-byte word boundaries, including the RAM pointer

spi_flash_get_id()

uint32_t spi_flash_get_id

(

void

)