Mistake on this page?
Report an issue in GitHub or email us


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.


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_init before the initialization of the QSPI.


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_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_XXX for pins connected to onboard flash memory.
  • QSPIn_XXX for pins routed out to external connector.

n is the interface index, typically 1 if single QSPI interface available.



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:

   "device_has": ["QSPI"]


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
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.