XCORE SDK
XCORE Software Development Kit
Functions
rtos_qspi_flash_driver_core

Functions

void rtos_qspi_flash_lock (rtos_qspi_flash_t *ctx)
 
void rtos_qspi_flash_unlock (rtos_qspi_flash_t *ctx)
 
void rtos_qspi_flash_read (rtos_qspi_flash_t *ctx, uint8_t *data, unsigned address, size_t len)
 
int rtos_qspi_flash_read_ll (rtos_qspi_flash_t *ctx, uint8_t *data, unsigned address, size_t len)
 
void rtos_qspi_flash_write (rtos_qspi_flash_t *ctx, const uint8_t *data, unsigned address, size_t len)
 
void rtos_qspi_flash_erase (rtos_qspi_flash_t *ctx, unsigned address, size_t len)
 
size_t rtos_qspi_flash_size_get (rtos_qspi_flash_t *qspi_flash_ctx)
 
size_t rtos_qspi_flash_page_size_get (rtos_qspi_flash_t *qspi_flash_ctx)
 
size_t rtos_qspi_flash_page_count_get (rtos_qspi_flash_t *qspi_flash_ctx)
 
size_t rtos_qspi_flash_sector_size_get (rtos_qspi_flash_t *qspi_flash_ctx)
 

Detailed Description

The core functions for using an RTOS QSPI flash driver instance after it has been initialized and started. These functions may be used by both the host and any client tiles that RPC has been enabled for.

Function Documentation

◆ rtos_qspi_flash_erase()

void rtos_qspi_flash_erase ( rtos_qspi_flash_t ctx,
unsigned  address,
size_t  len 
)
inline

This erases data from the QSPI flash. If the address range to erase spans multiple sectors, then all of these sectors will be erased by issuing multiple erase commands.

The driver handles sending the write enable command, as well as waiting for the write to complete.

This function may return before the write operation is complete, as the actual erase operation is queued and executed by a thread created by the driver.

Note
The smallest amount of data that can be erased is a 4k sector. This means that data outside the address range specified by address and len will be erased if the address range does not both begin and end at 4k sector boundaries.
Parameters
ctxA pointer to the QSPI flash driver instance to use.
addressThe byte address to begin erasing. This does not need to begin at a sector boundary, but if it does not, note that the entire sector that contains this address will still be erased.
lenThe minimum number of bytes to erase. If address + len - 1 does not correspond to the last address within a sector, note that the entire sector that contains this address will still be erased.

◆ rtos_qspi_flash_lock()

void rtos_qspi_flash_lock ( rtos_qspi_flash_t ctx)
inline

Obtains a lock for exclusive access to the QSPI flash. This allows a thread to perform a sequence of operations (such as read, modify, erase, write) without the risk of another thread issuing a command in the middle of the sequence and corrupting the data in the flash.

If only a single atomic operation needs to be performed, such as a read, it is not necessary to call this to obtain the lock first. Each individual operation obtains and releases the lock automatically so that they cannot run while another thread has the lock.

The lock MUST be released when it is no longer needed by calling rtos_qspi_flash_unlock().

Parameters
ctxA pointer to the QSPI flash driver instance to lock.

◆ rtos_qspi_flash_page_count_get()

size_t rtos_qspi_flash_page_count_get ( rtos_qspi_flash_t qspi_flash_ctx)
inline

This gets the number of pages in the flash chip.

Parameters
Apointer to the QSPI flash driver instance to query.
Returns
the number of pages in the flash chip.

◆ rtos_qspi_flash_page_size_get()

size_t rtos_qspi_flash_page_size_get ( rtos_qspi_flash_t qspi_flash_ctx)
inline

This gets the size in bytes of each page in the flash chip.

Parameters
Apointer to the QSPI flash driver instance to query.
Returns
the size in bytes of the flash page.

◆ rtos_qspi_flash_read()

void rtos_qspi_flash_read ( rtos_qspi_flash_t ctx,
uint8_t *  data,
unsigned  address,
size_t  len 
)
inline

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
ctxA pointer to the QSPI flash driver instance to use.
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.

◆ rtos_qspi_flash_read_ll()

int rtos_qspi_flash_read_ll ( rtos_qspi_flash_t ctx,
uint8_t *  data,
unsigned  address,
size_t  len 
)

This is a lower level version of rtos_qspi_flash_read() that is safe to call from within ISRs. If a task currently own the flash lock, or if another core is actively doing a read with this function, then the read will not be performed and an error returned. It is up to the application to determine what it should do in this situation and to avoid a potential deadlock.

Note
It is not possible to call this from a task that currently owns the flash lock taken with rtos_qspi_flash_lock(). In general it is not advisable to call this from an RTOS task unless the small amount of overhead time that is introduced by rtos_qspi_flash_read() is unacceptable.
Parameters
ctxA pointer to the QSPI flash driver instance to use.
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.
Return values
0if the flash was available and the read operation was performed.
-1if the flash was unavailable and the read could not be performed.

◆ rtos_qspi_flash_sector_size_get()

size_t rtos_qspi_flash_sector_size_get ( rtos_qspi_flash_t qspi_flash_ctx)
inline

This gets the sector size of the flash chip

Parameters
Apointer to the QSPI flash driver instance to query.
Returns
the size in bytes of the smallest sector

◆ rtos_qspi_flash_size_get()

size_t rtos_qspi_flash_size_get ( rtos_qspi_flash_t qspi_flash_ctx)
inline

This gets the size in bytes of the flash chip.

Parameters
Apointer to the QSPI flash driver instance to query.
Returns
the size in bytes of the flash chip.

◆ rtos_qspi_flash_unlock()

void rtos_qspi_flash_unlock ( rtos_qspi_flash_t ctx)
inline

Releases a lock for exclusive access to the QSPI flash. The lock must have already been obtained by calling rtos_qspi_flash_lock().

Parameters
ctxA pointer to the QSPI flash driver instance to unlock.

◆ rtos_qspi_flash_write()

void rtos_qspi_flash_write ( rtos_qspi_flash_t ctx,
const uint8_t *  data,
unsigned  address,
size_t  len 
)
inline

This writes data to the QSPI flash. If the data spans multiple pages then multiple page program commands will be issued. 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.

The driver handles sending the write enable command, as well as waiting for the write to complete.

This function may return before the write operation is complete, as the actual write operation is queued and executed by a thread created by the driver.

Note
this function does NOT erase the flash first. Erase operations must be explicitly requested by the application.
Parameters
ctxA pointer to the QSPI flash driver instance to use.
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.