Detailed Description

Interface for accessing external SPI flash devices.

Summary

The SPI flash API provides an interface that configures, writes, and erases sectors in SPI flash devices.

Data Structures
struct	spi_flash_erase_command_t

struct	spi_flash_direct_transfer_t

struct	spi_flash_cfg_t

struct	spi_flash_status_t

struct	spi_flash_api_t

struct	spi_flash_instance_t

Typedefs
typedef void	spi_flash_ctrl_t

Enumerations
enum	spi_flash_read_mode_t

enum	spi_flash_protocol_t

enum	spi_flash_address_bytes_t

enum	spi_flash_data_lines_t

enum	spi_flash_dummy_clocks_t

enum	spi_flash_direct_transfer_dir_t

Data Structure Documentation

◆ spi_flash_erase_command_t

struct spi_flash_erase_command_t

Structure to define an erase command and associated erase size.

Data Fields
uint16_t	command	Erase command.
uint32_t	size	Size of erase for associated command, set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE for chip erase.

◆ spi_flash_direct_transfer_t

struct spi_flash_direct_transfer_t

Structure to define a direct transfer.

Data Fields
union spi_flash_direct_transfer_t	__unnamed__
uint32_t	address	Starting address.
uint16_t	command	Transfer command.
uint8_t	dummy_cycles	Number of dummy cycles.
uint8_t	command_length	Command length.
uint8_t	address_length	Address length.
uint8_t	data_length	Data length.

◆ spi_flash_cfg_t

struct spi_flash_cfg_t

User configuration structure used by the open function

Data Fields
spi_flash_protocol_t	spi_protocol	Initial SPI protocol. SPI protocol can be changed in spi_flash_api_t::spiProtocolSet.
spi_flash_read_mode_t	read_mode	Read mode.
spi_flash_address_bytes_t	address_bytes	Number of bytes used to represent the address.
spi_flash_dummy_clocks_t	dummy_clocks	Number of dummy clocks to use for fast read operations.
spi_flash_data_lines_t	page_program_address_lines	Number of lines used to send address for page program command. This should either be 1 or match the number of lines used in the selected read mode.
uint8_t	write_status_bit	Which bit determines write status.
uint8_t	write_enable_bit	Which bit determines write status.
uint32_t	page_size_bytes	Page size in bytes (maximum number of bytes for page program). Used to specify single continuous write size (bytes) in case of OSPI RAM.
uint8_t	page_program_command	Page program command.
uint8_t	write_enable_command	Command to enable write or erase, typically 0x06.
uint8_t	status_command	Command to read the write status.
uint8_t	read_command	Read command - OSPI SPI mode only.
uint8_t	xip_enter_command	Command to enter XIP mode.
uint8_t	xip_exit_command	Command to exit XIP mode.
uint8_t	erase_command_list_length	Length of erase command list.
spi_flash_erase_command_t const *	p_erase_command_list	List of all erase commands and associated sizes.
void const *	p_extend	Pointer to implementation specific extended configurations.

◆ spi_flash_status_t

struct spi_flash_status_t

Status.

Data Fields
bool	write_in_progress	Whether or not a write is in progress. This is determined by reading the spi_flash_cfg_t::write_status_bit from the spi_flash_cfg_t::status_command.

◆ spi_flash_api_t

struct spi_flash_api_t

SPI flash implementations follow this API.

Data Fields
fsp_err_t(*	open )(spi_flash_ctrl_t const p_ctrl, spi_flash_cfg_t const const p_cfg)

fsp_err_t(*	directWrite )(spi_flash_ctrl_t const p_ctrl, uint8_t const const p_src, uint32_t const bytes, bool const read_after_write)

fsp_err_t(*	directRead )(spi_flash_ctrl_t const p_ctrl, uint8_t const p_dest, uint32_t const bytes)

fsp_err_t(*	directTransfer )(spi_flash_ctrl_t const p_ctrl, spi_flash_direct_transfer_t const p_transfer, spi_flash_direct_transfer_dir_t direction)

fsp_err_t(*	spiProtocolSet )(spi_flash_ctrl_t *const p_ctrl, spi_flash_protocol_t spi_protocol)

fsp_err_t(*	write )(spi_flash_ctrl_t const p_ctrl, uint8_t const const p_src, uint8_t *const p_dest, uint32_t byte_count)

fsp_err_t(*	erase )(spi_flash_ctrl_t const p_ctrl, uint8_t const p_device_address, uint32_t byte_count)

fsp_err_t(*	statusGet )(spi_flash_ctrl_t const p_ctrl, spi_flash_status_t const p_status)

fsp_err_t(*	xipEnter )(spi_flash_ctrl_t *const p_ctrl)

fsp_err_t(*	xipExit )(spi_flash_ctrl_t *const p_ctrl)

fsp_err_t(*	bankSet )(spi_flash_ctrl_t *const p_ctrl, uint32_t bank)

fsp_err_t(*	autoCalibrate )(spi_flash_ctrl_t *const p_ctrl)

fsp_err_t(*	close )(spi_flash_ctrl_t *const p_ctrl)

Field Documentation

◆ open

fsp_err_t(* spi_flash_api_t::open) (spi_flash_ctrl_t *const p_ctrl, spi_flash_cfg_t const *const p_cfg)

Open the SPI flash driver module.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	p_cfg	Pointer to a configuration structure

◆ directWrite

fsp_err_t(* spi_flash_api_t::directWrite) (spi_flash_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint32_t const bytes, bool const read_after_write)

Write raw data to the SPI flash.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	p_src	Pointer to raw data to write, must include any required command/address
[in]	bytes	Number of bytes to write
[in]	read_after_write	If true, the slave select remains asserted and the peripheral does not return to direct communications mode. If false, the slave select is deasserted and memory mapped access is possible after this function returns if the device is not busy.

◆ directRead

fsp_err_t(* spi_flash_api_t::directRead) (spi_flash_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const bytes)

Read raw data from the SPI flash. Must follow a call to spi_flash_api_t::directWrite.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[out]	p_dest	Pointer to read raw data into
[in]	bytes	Number of bytes to read

◆ directTransfer

fsp_err_t(* spi_flash_api_t::directTransfer) (spi_flash_ctrl_t *const p_ctrl, spi_flash_direct_transfer_t *const p_transfer, spi_flash_direct_transfer_dir_t direction)

Direct Read/Write raw data to the SPI flash.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	p_data	Pointer to command, address and data values and lengths
[in]	direction	Direct Read/Write

◆ spiProtocolSet

fsp_err_t(* spi_flash_api_t::spiProtocolSet) (spi_flash_ctrl_t *const p_ctrl, spi_flash_protocol_t spi_protocol)

Change the SPI protocol in the driver. The application must change the SPI protocol on the device.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	spi_protocol	Desired SPI protocol

◆ write

fsp_err_t(* spi_flash_api_t::write) (spi_flash_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint8_t *const p_dest, uint32_t byte_count)

Program a page of data to the flash.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	p_src	The memory address of the data to write to the flash device
[in]	p_dest	The location in the flash device address space to write the data to
[in]	byte_count	The number of bytes to write

◆ erase

fsp_err_t(* spi_flash_api_t::erase) (spi_flash_ctrl_t *const p_ctrl, uint8_t *const p_device_address, uint32_t byte_count)

Erase a certain number of bytes of the flash.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	p_device_address	The location in the flash device address space to start the erase from
[in]	byte_count	The number of bytes to erase. Set to SPI_FLASH_ERASE_SIZE_CHIP_ERASE to erase entire chip.

◆ statusGet

fsp_err_t(* spi_flash_api_t::statusGet) (spi_flash_ctrl_t *const p_ctrl, spi_flash_status_t *const p_status)

Get the write or erase status of the flash.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[out]	p_status	Current status of the SPI flash device stored here.

◆ xipEnter

fsp_err_t(* spi_flash_api_t::xipEnter) (spi_flash_ctrl_t *const p_ctrl)

Enter XIP mode.

Parameters

[in] p_ctrl Pointer to a driver handle

◆ xipExit

fsp_err_t(* spi_flash_api_t::xipExit) (spi_flash_ctrl_t *const p_ctrl)

Exit XIP mode.

Parameters

[in] p_ctrl Pointer to a driver handle

◆ bankSet

fsp_err_t(* spi_flash_api_t::bankSet) (spi_flash_ctrl_t *const p_ctrl, uint32_t bank)

Select the bank to access. See implementation for details.

Parameters

[in]	p_ctrl	Pointer to a driver handle
[in]	bank	The bank number

◆ autoCalibrate

fsp_err_t(* spi_flash_api_t::autoCalibrate) (spi_flash_ctrl_t *const p_ctrl)

AutoCalibrate the SPI flash driver module. Expected to be used when auto-calibrating OSPI RAM device.

Parameters

[in] p_ctrl Pointer to a driver handle

◆ close

fsp_err_t(* spi_flash_api_t::close) (spi_flash_ctrl_t *const p_ctrl)

Close the SPI flash driver module.

Parameters

[in] p_ctrl Pointer to a driver handle

◆ spi_flash_instance_t

struct spi_flash_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
spi_flash_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
spi_flash_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
spi_flash_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

◆ spi_flash_ctrl_t

typedef void spi_flash_ctrl_t

SPI flash control block. Allocate an instance specific control block to pass into the SPI flash API calls.

Enumeration Type Documentation

◆ spi_flash_read_mode_t

enum spi_flash_read_mode_t

Read mode.

Enumerator
SPI_FLASH_READ_MODE_STANDARD	Standard Read Mode (no dummy cycles)
SPI_FLASH_READ_MODE_FAST_READ	Fast Read Mode (dummy cycles between address and data)
SPI_FLASH_READ_MODE_FAST_READ_DUAL_OUTPUT	Fast Read Dual Output Mode (data on 2 lines)
SPI_FLASH_READ_MODE_FAST_READ_DUAL_IO	Fast Read Dual I/O Mode (address and data on 2 lines)
SPI_FLASH_READ_MODE_FAST_READ_QUAD_OUTPUT	Fast Read Quad Output Mode (data on 4 lines)
SPI_FLASH_READ_MODE_FAST_READ_QUAD_IO	Fast Read Quad I/O Mode (address and data on 4 lines)

◆ spi_flash_protocol_t

enum spi_flash_protocol_t

SPI protocol.

Enumerator
SPI_FLASH_PROTOCOL_EXTENDED_SPI	Extended SPI mode (commands on 1 line)
SPI_FLASH_PROTOCOL_QPI	QPI mode (commands on 4 lines). Note that the application must ensure the device is in QPI mode.
SPI_FLASH_PROTOCOL_SOPI	SOPI mode (command and data on 8 lines). Note that the application must ensure the device is in SOPI mode.
SPI_FLASH_PROTOCOL_DOPI	DOPI mode (command and data on 8 lines, dual data rate). Note that the application must ensure the device is in DOPI mode.
SPI_FLASH_PROTOCOL_1S_1S_1S	1S-1S-1S protocol mode
SPI_FLASH_PROTOCOL_4S_4D_4D	4S-4D-4D protocol mode
SPI_FLASH_PROTOCOL_8D_8D_8D	8D-8D-8D protocol mode
SPI_FLASH_PROTOCOL_1S_2S_2S	1S-2S-2S protocol mode
SPI_FLASH_PROTOCOL_2S_2S_2S	2S-2S-2S protocol mode
SPI_FLASH_PROTOCOL_1S_4S_4S	1S-4S-4S protocol mode
SPI_FLASH_PROTOCOL_4S_4S_4S	4S-4S-4S protocol mode

◆ spi_flash_address_bytes_t

enum spi_flash_address_bytes_t

Number of bytes in the address.

Enumerator
SPI_FLASH_ADDRESS_BYTES_3	3 address bytes
SPI_FLASH_ADDRESS_BYTES_4	4 address bytes with standard commands. If this option is selected, the application must issue the EN4B command using spi_flash_api_t::directWrite() if required by the device.
SPI_FLASH_ADDRESS_BYTES_4_4BYTE_READ_CODE	4 address bytes using standard 4-byte command set.

◆ spi_flash_data_lines_t

enum spi_flash_data_lines_t

Number of data lines used.

Enumerator
SPI_FLASH_DATA_LINES_1	1 data line
SPI_FLASH_DATA_LINES_2	2 data lines
SPI_FLASH_DATA_LINES_4	4 data lines

◆ spi_flash_dummy_clocks_t

enum spi_flash_dummy_clocks_t

Number of dummy cycles for fast read operations.

Enumerator
SPI_FLASH_DUMMY_CLOCKS_0	0 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_1	1 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_2	2 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_3	3 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_4	4 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_5	5 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_6	6 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_7	7 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_8	8 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_9	9 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_10	10 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_11	11 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_12	12 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_13	13 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_14	14 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_15	15 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_16	16 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_17	17 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_18	18 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_19	19 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_20	20 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_21	21 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_22	22 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_23	23 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_24	24 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_25	25 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_26	26 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_27	27 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_28	28 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_29	29 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_30	30 dummy clocks
SPI_FLASH_DUMMY_CLOCKS_31	31 dummy clocks

◆ spi_flash_direct_transfer_dir_t

enum spi_flash_direct_transfer_dir_t

Direct Read and Write direction

Detailed Description

Summary

Data Structures

Typedefs

Enumerations

Data Structure Documentation

◆ spi_flash_erase_command_t

◆ spi_flash_direct_transfer_t

◆ spi_flash_cfg_t

◆ spi_flash_status_t

◆ spi_flash_api_t

Data Fields

Field Documentation

◆ open

◆ directWrite

◆ directRead

◆ directTransfer

◆ spiProtocolSet

◆ write

◆ erase

◆ statusGet

◆ xipEnter

◆ xipExit

◆ bankSet

◆ autoCalibrate

◆ close

◆ spi_flash_instance_t

Typedef Documentation

◆ spi_flash_ctrl_t

Enumeration Type Documentation

◆ spi_flash_read_mode_t

◆ spi_flash_protocol_t

◆ spi_flash_address_bytes_t

◆ spi_flash_data_lines_t

◆ spi_flash_dummy_clocks_t

◆ spi_flash_direct_transfer_dir_t