XCORE SDK
XCORE Software Development Kit
|
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 |
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) |
The public API for using HIL QSPI flash I/O.
#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.
#define QSPI_FLASH_STATUS_REG_WEL_BM 0x02 |
The bit mask for the status register's write enable latch bit.
#define QSPI_FLASH_STATUS_REG_WIP_BM 0x01 |
The bit mask for the status register's write in progress bit.
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.
void qspi_flash_deinit | ( | qspi_flash_ctx_t * | ctx | ) |
Deinitializes the QSPI I/O interface associated with the QSPI flash.
ctx | The QSPI flash context associated with the QSPI flash. This should have been previously initialized with qspi_flash_init(). |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
address | Any byte address within the data block to erase. |
erase_length | The data block size to erase. See qspi_flash_erase_length_t. If qspi_flash_erase_chip, then address is ignored. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
cmd | The command required for reading from the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI(). |
mask | The bitmask to apply to the received register value before comparing it to val ; |
val | The value that the register value, masked with mask , must match before returning. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
mask | The bitmask to apply to the received register value before comparing it to val ; |
val | The value that the register value, masked with mask , must match before returning. |
bool qspi_flash_quad_enable_write | ( | qspi_flash_ctx_t * | ctx, |
bool | set | ||
) |
Sets or clears the quad enable bit in the flash.
ctx | The QSPI flash context associated with the QSPI flash. |
set | When true, the quad enable bit is set. When false, the quad enable bit is cleared if possible. |
true | if the QE bit was already at the requested value, or if the write was successful. |
false | if the write did not complete successfully. This can happen when trying to clear the QE bit on parts where it is fixed to '1'. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
val | Pointer to the buffer to write the ID to. |
len | The number of ID bytes to read and save to val . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
cmd | The command required for reading from the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI(). |
val | Pointer to the buffer to store the data read from the register. |
len | The number of bytes to read from the register and save to val . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
val | Pointer to the buffer to store the data read from the register. |
len | The number of bytes to read from the register and save to val . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the data to write to the flash. |
address | The 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. |
len | The number of bytes to write to the flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
true | if there is a flash write in progress. |
false | if the flash is not writing and is ready to accept another read or write command. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the data to write to the flash. |
address | The 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. |
len | The number of bytes to write to the flash. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
cmd | The command required for writing to the desired register. Must be the value returned by QSPI_IO_BYTE_TO_MOSI(). |
val | Pointer to the data to write to the register. |
len | The number of bytes from val to write to the 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.
ctx | The QSPI flash context associated with the QSPI flash. |
val | Pointer to the data to write to the register. |
len | The number of bytes from val to write to the register. |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |
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.
ctx | The QSPI flash context associated with the QSPI flash. |
data | Pointer to the buffer to save the read data to. |
address | The 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. |
len | The number of bytes to read and save to data . |