RA Flexible Software Package Documentation  Release v5.2.0

 
SPI Flash Interface

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_ctrlPointer to a driver handle
[in]p_cfgPointer 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_ctrlPointer to a driver handle
[in]p_srcPointer to raw data to write, must include any required command/address
[in]bytesNumber of bytes to write
[in]read_after_writeIf 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_ctrlPointer to a driver handle
[out]p_destPointer to read raw data into
[in]bytesNumber 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_ctrlPointer to a driver handle
[in]p_dataPointer to command, address and data values and lengths
[in]directionDirect 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_ctrlPointer to a driver handle
[in]spi_protocolDesired 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_ctrlPointer to a driver handle
[in]p_srcThe memory address of the data to write to the flash device
[in]p_destThe location in the flash device address space to write the data to
[in]byte_countThe 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_ctrlPointer to a driver handle
[in]p_device_addressThe location in the flash device address space to start the erase from
[in]byte_countThe 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_ctrlPointer to a driver handle
[out]p_statusCurrent 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_ctrlPointer 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_ctrlPointer 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_ctrlPointer to a driver handle
[in]bankThe 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_ctrlPointer 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_ctrlPointer 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

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

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

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

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

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

Direct Read and Write direction