QuadSPI (QSPI)
Implementing QSPI enables Mbed OS to communicate with compliant external SPI devices much faster than with standalone SPI due to the inclusion of up to four data lines between the host and a device.
The most common use case is for external memory to use as additional data storage.
Assumptions
Defined behavior
- A target implementation covers most of the QSPI frame format (some targets might not provide the flexibility for setting all frame parameters).
- Command transfer - A target might provide additional functions for sending device-specific commands. If it does not, you can implement it using read and write functions. (This is target or driver dependent.)
Undefined behavior
- Calling any function other than
qspi_initbefore the initialization of the QSPI.
Dependency
QSPI peripheral
Implementing QSPI
You can implement your own QSPI by pulling in the following API header file:
| Public Member Functions | |
| QSPI (PinName io0, PinName io1, PinName io2, PinName io3, PinName sclk, PinName ssel=NC, int mode=0) | |
| Create a QSPI master connected to the specified pins. More... | |
| QSPI (const qspi_pinmap_t &pinmap, int mode=0) | |
| Create a QSPI master connected to the specified pins. More... | |
| qspi_status_t | configure_format (qspi_bus_width_t inst_width, qspi_bus_width_t address_width, qspi_address_size_t address_size, qspi_bus_width_t alt_width, qspi_alt_size_t alt_size, qspi_bus_width_t data_width, int dummy_cycles) |
| Configure the data transmission format. More... | |
| qspi_status_t | set_frequency (int hz=1000000) |
| Set the qspi bus clock frequency. More... | |
| qspi_status_t | read (int address, char *rx_buffer, size_t *rx_length) |
| Read from QSPI peripheral with the preset read_instruction and alt_value. More... | |
| qspi_status_t | write (int address, const char *tx_buffer, size_t *tx_length) |
| Write to QSPI peripheral using custom write instruction. More... | |
| qspi_status_t | read (qspi_inst_t instruction, int alt, int address, char *rx_buffer, size_t *rx_length) |
| Read from QSPI peripheral using custom read instruction, alt values. More... | |
| qspi_status_t | write (qspi_inst_t instruction, int alt, int address, const char *tx_buffer, size_t *tx_length) |
| Write to QSPI peripheral using custom write instruction, alt values. More... | |
| qspi_status_t | command_transfer (qspi_inst_t instruction, int address, const char *tx_buffer, size_t tx_length, const char *rx_buffer, size_t rx_length) |
| Perform a transaction to write to an address(a control register) and get the status results. More... | |
The target needs to define the qspi_s structure - target specific QSPI object.
The target needs to define the QSPI interface pin names:
QSPI_FLASHn_XXXfor pins connected to onboard flash memory.QSPIn_XXXfor pins routed out to external connector.
n is the interface index, typically 1 if single QSPI interface available.
QSPIn_IO0
QSPIn_IO1
QSPIn_IO2
QSPIn_IO3
QSPIn_SCK
QSPIn_CSN
QSPI_FLASHn_IO0
QSPI_FLASHn_IO1
QSPI_FLASHn_IO2
QSPI_FLASHn_IO3
QSPI_FLASHn_SCK
QSPI_FLASHn_CSN
Functions to implement:
qspi_status_t qspi_init(qspi_t *obj, PinName io0, PinName io1, PinName io2, PinName io3, PinName sclk, PinName ssel, uint32_t hz, uint8_t mode);
qspi_status_t qspi_free(qspi_t *obj);
qspi_status_t qspi_frequency(qspi_t *obj, int hz);
qspi_status_t qspi_write(qspi_t *obj, const qspi_command_t *command, const void *data, size_t *length);
qspi_status_t qspi_command_transfer(qspi_t *obj, const qspi_command_t *command, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size);
qspi_status_t qspi_read(qspi_t *obj, const qspi_command_t *command, void *data, size_t *length);
Use qspi_write and qspi_read for data transfers. To communicate with a device, use qspi_command_transfer.
To enable the QSPI HAL, define QSPI in the targets.json file inside device_has:
"TARGET_NAME": {
"device_has": ["QSPI"]
}
Testing
The Mbed OS HAL provides a set of conformance tests for the QSPI interface.
Note: QSPI HAL tests require QSPI Flash pins to be defined.
You can use these tests to validate the correctness of your implementation. To run the QSPI HAL tests, use the following command:
mbed test -t <toolchain> -m <target> -n tests-mbed_hal-qspi