XCORE SDK
XCORE Software Development Kit
Classes | Macros | Enumerations | Functions
hil_qspi_flash

Classes

struct  qspi_flash_ctx_t
 

Macros

#define QSPI_FLASH_SANITY_CHECKS   0
 
#define QSPI_FLASH_STATUS_REG_WIP_BM   0x01
 
#define QSPI_FLASH_STATUS_REG_WEL_BM   0x02
 

Enumerations

enum  qspi_flash_page_program_cmd_t { qspi_flash_page_program_1_1_1 , qspi_flash_page_program_1_1_4 , qspi_flash_page_program_1_4_4 }
 
enum  qspi_flash_erase_length_t {
  qspi_flash_erase_1 , qspi_flash_erase_2 , qspi_flash_erase_3 , qspi_flash_erase_4 ,
  qspi_flash_erase_chip
}
 

Functions

size_t qspi_flash_erase_type_size (qspi_flash_ctx_t *ctx, qspi_flash_erase_length_t erase_type)
 
uint32_t qspi_flash_erase_type_size_log2 (qspi_flash_ctx_t *ctx, qspi_flash_erase_length_t erase_type)
 
bool qspi_flash_quad_enable_write (qspi_flash_ctx_t *ctx, bool set)
 
void qspi_flash_write_enable (qspi_flash_ctx_t *ctx)
 
void qspi_flash_write_disable (qspi_flash_ctx_t *ctx)
 
bool qspi_flash_write_in_progress (qspi_flash_ctx_t *ctx)
 
void qspi_flash_wait_while_write_in_progress (qspi_flash_ctx_t *ctx)
 
void qspi_flash_erase (qspi_flash_ctx_t *ctx, uint32_t address, qspi_flash_erase_length_t erase_length)
 
void qspi_flash_write_register (qspi_flash_ctx_t *ctx, uint32_t cmd, const uint8_t *val, size_t len)
 
void qspi_flash_write_status_register (qspi_flash_ctx_t *ctx, const uint8_t *val, size_t len)
 
void qspi_flash_read_register (qspi_flash_ctx_t *ctx, uint32_t cmd, uint8_t *val, size_t len)
 
void qspi_flash_read_status_register (qspi_flash_ctx_t *ctx, uint8_t *val, size_t len)
 
void qspi_flash_read_id (qspi_flash_ctx_t *ctx, uint8_t *val, size_t len)
 
void qspi_flash_poll_register (qspi_flash_ctx_t *ctx, uint32_t cmd, const uint8_t mask, const uint8_t val)
 
void qspi_flash_poll_status_register (qspi_flash_ctx_t *ctx, const uint8_t mask, const uint8_t val)
 
void qspi_flash_fast_read (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_read (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_read_nibble_swapped (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_xip_read (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_xip_read_nibble_swapped (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_write (qspi_flash_ctx_t *ctx, const uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_write_nibble_swapped (qspi_flash_ctx_t *ctx, const uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_sfdp_read (qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
 
void qspi_flash_deinit (qspi_flash_ctx_t *ctx)
 
void qspi_flash_init (qspi_flash_ctx_t *ctx)
 

Detailed Description

The public API for using HIL QSPI flash I/O.

Macro Definition Documentation

◆ QSPI_FLASH_SANITY_CHECKS

#define QSPI_FLASH_SANITY_CHECKS   0

When QSPI_FLASH_SANITY_CHECKS is true then some run-time sanity checks are made at the expense of some extra overhead.

◆ QSPI_FLASH_STATUS_REG_WEL_BM

#define QSPI_FLASH_STATUS_REG_WEL_BM   0x02

The bit mask for the status register's write enable latch bit.

◆ QSPI_FLASH_STATUS_REG_WIP_BM

#define QSPI_FLASH_STATUS_REG_WIP_BM   0x01

The bit mask for the status register's write in progress bit.

Enumeration Type Documentation

◆ qspi_flash_erase_length_t

Most QSPI flashes allow data to be erased in 4k, 32k or 64k chunks, as well as the entire chip. However, these values are not always available on all chips. The erase info table in the qspi flash context structure defines the size of each erasable sector size. This is typically populated automatically by qspi_flash_init() from the SFDP data in the flash.

Enumerator
qspi_flash_erase_1 

Erase the first available sector size. This should always be available and will be the smallest available erasable sector size.

qspi_flash_erase_2 

Erase the second available sector size. This should be smaller than qspi_flash_erase_3 if both are available.

qspi_flash_erase_3 

Erase the third available sector size. This should be smaller than qspi_flash_erase_4 if both are available.

qspi_flash_erase_4 

Erase the fourth available sector size. This is typically not available, but will be the largest available erasable sector size if it is.

qspi_flash_erase_chip 

Erase the entire chip

◆ qspi_flash_page_program_cmd_t

Enumerator
qspi_flash_page_program_1_1_1 

Programs pages using only MOSI. Most, if not all, QSPI flashes support this command. Use this if in doubt.

qspi_flash_page_program_1_1_4 

Programs pages by sending the command and address over just SIO0, but the data over all four data lines. Many QSPI flashes support either this or qspi_flash_page_program_1_4_4, but not both. Check the datasheet. If the particular flash chip that will be used is unknown, then qspi_flash_page_program_1_1_1 should be used.

qspi_flash_page_program_1_4_4 

Programs pages by sending the command over just SIO0, but the address and data over all four data lines. Many QSPI flashes support either this or qspi_flash_page_program_1_1_4, but not both. Check the datasheet. If the particular flash chip that will be used is unknown, then qspi_flash_page_program_1_1_1 should be used.

Function Documentation

◆ qspi_flash_deinit()

void qspi_flash_deinit ( qspi_flash_ctx_t ctx)

Deinitializes the QSPI I/O interface associated with the QSPI flash.

Parameters
ctxThe QSPI flash context associated with the QSPI flash. This should have been previously initialized with qspi_flash_init().

◆ qspi_flash_erase()

void qspi_flash_erase ( qspi_flash_ctx_t ctx,
uint32_t  address,
qspi_flash_erase_length_t  erase_length 
)

This performs an erase operation. qspi_flash_write_enable() must be called prior to this.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
addressAny byte address within the data block to erase.
erase_lengthThe data block size to erase. See qspi_flash_erase_length_t. If qspi_flash_erase_chip, then address is ignored.

◆ qspi_flash_fast_read()

void qspi_flash_fast_read ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This reads data from the flash in fast mode. This is a normal SPI read, using only SIO0 (MOSI) and SIO1 (MOSI), but includes eight dummy cycles between the address and data.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the flash to begin reading at. Only bits 23:0 contain the address. The byte in bits 31:24 is not sent.
lenThe number of bytes to read and save to data.

◆ qspi_flash_init()

void qspi_flash_init ( qspi_flash_ctx_t ctx)

Initializes the QSPI I/O interface associated with the QSPI flash. The ports and clock block in the ctx->qspi_io_ctx must be set prior to calling this.

If ctx->custom_clock_setup is false, then the QSPI I/O clock configuration is set to safe default values that should work for all QSPI flashes. Otherwise, the clock configuration values must be supplied by the application.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.

◆ qspi_flash_poll_register()

void qspi_flash_poll_register ( qspi_flash_ctx_t ctx,
uint32_t  cmd,
const uint8_t  mask,
const uint8_t  val 
)

This polls a register in the QSPI flash. This allows an application to poll non-standard registers specific to its flash chip. The register must be one byte and repeatedly sent out over MISO following the read register command.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
cmdThe command required for reading from the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI().
maskThe bitmask to apply to the received register value before comparing it to val;
valThe value that the register value, masked with mask, must match before returning.

◆ qspi_flash_poll_status_register()

void qspi_flash_poll_status_register ( qspi_flash_ctx_t ctx,
const uint8_t  mask,
const uint8_t  val 
)

This polls the status register in the QSPI flash.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
maskThe bitmask to apply to the received register value before comparing it to val;
valThe value that the register value, masked with mask, must match before returning.

◆ qspi_flash_quad_enable_write()

bool qspi_flash_quad_enable_write ( qspi_flash_ctx_t ctx,
bool  set 
)

Sets or clears the quad enable bit in the flash.

Note
The quad enable bit is fixed to '1' in some QSPI flash chips, and cannot be cleared.
Parameters
ctxThe QSPI flash context associated with the QSPI flash.
setWhen true, the quad enable bit is set. When false, the quad enable bit is cleared if possible.
Return values
trueif the QE bit was already at the requested value, or if the write was successful.
falseif the write did not complete successfully. This can happen when trying to clear the QE bit on parts where it is fixed to '1'.

◆ qspi_flash_read()

void qspi_flash_read ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This reads data from the flash in quad I/O mode. All four lines are used to send the address and to read the data.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the flash to begin reading at. Only bits 23:0 contain the address. Bits 31:24 are actually transmitted to the flash during the first two dummy cycles following the three address bytes. Some flashes read the SIO lines during these first two dummy cycles to enable certain features, so this might be useful for some applications.
lenThe number of bytes to read and save to data.

◆ qspi_flash_read_id()

void qspi_flash_read_id ( qspi_flash_ctx_t ctx,
uint8_t *  val,
size_t  len 
)

This reads the JEDEC ID of the QSPI flash.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
valPointer to the buffer to write the ID to.
lenThe number of ID bytes to read and save to val.

◆ qspi_flash_read_nibble_swapped()

void qspi_flash_read_nibble_swapped ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This is the same as qspi_flash_read() except that the nibbles in each byte of the data returned are swapped.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the flash to begin reading at. Only bits 23:0 contain the address. Bits 31:24 are actually transmitted to the flash during the first two dummy cycles following the three address bytes. Some flashes read the SIO lines during these first two dummy cycles to enable certain features, so this might be useful for some applications.
lenThe number of bytes to read and save to data.

◆ qspi_flash_read_register()

void qspi_flash_read_register ( qspi_flash_ctx_t ctx,
uint32_t  cmd,
uint8_t *  val,
size_t  len 
)

This reads from a register in the QSPI flash. This allows an application to read from non-standard registers specific to its flash chip.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
cmdThe command required for reading from the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI().
valPointer to the buffer to store the data read from the register.
lenThe number of bytes to read from the register and save to val.

◆ qspi_flash_read_status_register()

void qspi_flash_read_status_register ( qspi_flash_ctx_t ctx,
uint8_t *  val,
size_t  len 
)

This reads from the status register in the QSPI flash.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
valPointer to the buffer to store the data read from the register.
lenThe number of bytes to read from the register and save to val.

◆ qspi_flash_sfdp_read()

void qspi_flash_sfdp_read ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This reads the SFDP data from the flash in 1-1-1 mode.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the SFDP area to begin reading at. Only bits 23:0 contain the address. The byte in bits 31:24 is not sent.
lenThe number of bytes to read and save to data.

◆ qspi_flash_wait_while_write_in_progress()

void qspi_flash_wait_while_write_in_progress ( qspi_flash_ctx_t ctx)

This waits while the QSPI flash has a write operation in progress. It returns when the write operation is complete, or immediately if there is not one in progress to begin with.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.

◆ qspi_flash_write()

void qspi_flash_write ( qspi_flash_ctx_t ctx,
const uint8_t *  data,
uint32_t  address,
size_t  len 
)

This writes data to a page in the QSPI flash. If ctx->quad_page_program_enable is true, then the command in ctx->quad_page_program_cmd is sent and all four SIO lines are used to send the address and data. Otherwise, the standard page program command is sent and only SIO0 (MOSI) is used to send the address and data.

qspi_flash_write_enable() must be called prior to this.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the data to write to the flash.
addressThe byte address in the flash to begin writing at. Only bits 23:0 contain the address. The byte in bits 31:24 is not sent.
lenThe number of bytes to write to the flash.

◆ qspi_flash_write_disable()

void qspi_flash_write_disable ( qspi_flash_ctx_t ctx)

This clears the write enable latch in the QSPI flash. This is cleared automatically at the end of write operations, so normally does not need to be called.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.

◆ qspi_flash_write_enable()

void qspi_flash_write_enable ( qspi_flash_ctx_t ctx)

Sets the write enable latch in the QSPI flash. This must be called prior to erasing, programming, or writing to a register.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.

◆ qspi_flash_write_in_progress()

bool qspi_flash_write_in_progress ( qspi_flash_ctx_t ctx)

This checks to see if the QSPI flash has a write operation in progress.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
Return values
trueif there is a flash write in progress.
falseif the flash is not writing and is ready to accept another read or write command.

◆ qspi_flash_write_nibble_swapped()

void qspi_flash_write_nibble_swapped ( qspi_flash_ctx_t ctx,
const uint8_t *  data,
uint32_t  address,
size_t  len 
)

This is the same as qspi_flash_write() except that the nibbles in each byte of the data written are swapped.

qspi_flash_write_enable() must be called prior to this.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the data to write to the flash.
addressThe byte address in the flash to begin writing at. Only bits 23:0 contain the address. The byte in bits 31:0 is not sent.
lenThe number of bytes to write to the flash.

◆ qspi_flash_write_register()

void qspi_flash_write_register ( qspi_flash_ctx_t ctx,
uint32_t  cmd,
const uint8_t *  val,
size_t  len 
)

This writes to a register in the QSPI flash. This allows an application to write to non-standard registers specific to its flash chip.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
cmdThe command required for writing to the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI().
valPointer to the data to write to the register.
lenThe number of bytes from val to write to the register.

◆ qspi_flash_write_status_register()

void qspi_flash_write_status_register ( qspi_flash_ctx_t ctx,
const uint8_t *  val,
size_t  len 
)

This writes to the status register in the QSPI flash. qspi_flash_write_enable() must be called prior to this.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
valPointer to the data to write to the register.
lenThe number of bytes from val to write to the register.

◆ qspi_flash_xip_read()

void qspi_flash_xip_read ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This reads data from the flash in quad I/O "eXecute In Place" mode. All four lines are used to send the address and to read the data. No command is sent. The flash must already have been put into "XIP" mode.

The method used to put the flash into XIP mode, as well as to take it out, is flash dependent. See your flash's datasheet.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the flash to begin reading at. Only bits 23:0 contain the address. Bits 31:24 are actually transmitted to the flash during the first two dummy cycles following the three address bytes. Some flashes read the SIO lines during these first two dummy cycles to enable certain features, so this might be useful for some applications.
lenThe number of bytes to read and save to data.

◆ qspi_flash_xip_read_nibble_swapped()

void qspi_flash_xip_read_nibble_swapped ( qspi_flash_ctx_t ctx,
uint8_t *  data,
uint32_t  address,
size_t  len 
)

This is the same as qspi_flash_xip_read() except that the nibbles in each byte of the data returned are swapped.

Parameters
ctxThe QSPI flash context associated with the QSPI flash.
dataPointer to the buffer to save the read data to.
addressThe byte address in the flash to begin reading at. Only bits 23:0 contain the address. Bits 31:24 are actually transmitted to the flash during the first two dummy cycles following the three address bytes. Some flashes read the SIO lines during these first two dummy cycles to enable certain features, so this might be useful for some applications.
lenThe number of bytes to read and save to data.