High level interface for interacting with the Quad-SPI interface.
QSPI is an SPI-based communication interface, often used with external memory devices. The QSPI driver supports sending and receiving commands to/from from another device via a single, dual, quad, or octal SPI interface.
The following code snip demonstrates an example for initializing the cyhal_qspi_command_t structure for any given flash command. The cyhal_qspi_command_t.mode_bits structure has several other components which should be set as per the command. Mode bits are not required for single SPI read command, hence, mode_bits.disabled is set to TRUE in the below example code.
This example function demonstrates the initialization of the QSPI component and use of the cyhal_qspi_read() function to complete the read operation and receive the read data in a buffer.
The following code snippet demonstrates the use of cyhal_qspi_transfer() API for sending single byte instruction that may or may not need any address or data bytes. It also shows the usage of status register read command within a while loop to poll the WIP bit status.
This code snippet demonstrates the usage cyhal_qspi_write() API for executing program operation on flash memory.
This code snippet demonstrates the usage cyhal_qspi_slave_configure() and cyhal_qspi_select_active_ssel() API for for initialization environment for additional (additional to one, that was initialized in scope of cyhal_qspi_init()) QSPI memory and switching between memories.
API Reference | |
QSPI HAL Results | |
QSPI specific return codes. | |
Data Structures | |
struct | cyhal_qspi_command_t |
QSPI command settings. More... | |
struct | cyhal_qspi_slave_pin_config_t |
QSPI slave pin set. More... | |
struct | cyhal_qspi_command_t.instruction |
struct | cyhal_qspi_command_t.address |
struct | cyhal_qspi_command_t.mode_bits |
struct | cyhal_qspi_command_t.dummy_cycles |
struct | cyhal_qspi_command_t.data |
Typedefs | |
typedef void(* | cyhal_qspi_event_callback_t) (void *callback_arg, cyhal_qspi_event_t event) |
Handler for QSPI callbacks. | |
Enumerations | |
enum | cyhal_qspi_bus_width_t { CYHAL_QSPI_CFG_BUS_SINGLE = 1 , CYHAL_QSPI_CFG_BUS_DUAL = 2 , CYHAL_QSPI_CFG_BUS_QUAD = 4 , CYHAL_QSPI_CFG_BUS_OCTAL = 8 } |
QSPI Bus width. More... | |
enum | cyhal_qspi_size_t { CYHAL_QSPI_CFG_SIZE_8 = 8 , CYHAL_QSPI_CFG_SIZE_16 = 16 , CYHAL_QSPI_CFG_SIZE_24 = 24 , CYHAL_QSPI_CFG_SIZE_32 = 32 } |
Address size in bits. More... | |
enum | cyhal_qspi_event_t { CYHAL_QSPI_EVENT_NONE = 0 , CYHAL_QSPI_IRQ_TRANSMIT_DONE = 1 << 0 , CYHAL_QSPI_IRQ_RECEIVE_DONE = 1 << 1 } |
QSPI interrupt triggers. More... | |
enum | cyhal_qspi_datarate_t { CYHAL_QSPI_DATARATE_SDR = 0 , CYHAL_QSPI_DATARATE_DDR = 1 } |
QSPI data rate. More... | |
Functions | |
cy_rslt_t | cyhal_qspi_init (cyhal_qspi_t *obj, cyhal_gpio_t sclk, const cyhal_qspi_slave_pin_config_t *pin_set, uint32_t hz, uint8_t mode, cyhal_clock_t *clk) |
Initialize QSPI peripheral. More... | |
cy_rslt_t | cyhal_qspi_init_cfg (cyhal_qspi_t *obj, const cyhal_qspi_configurator_t *cfg) |
Initialize the QSPI peripheral using a configurator generated configuration struct. More... | |
void | cyhal_qspi_free (cyhal_qspi_t *obj) |
Deinitilize QSPI peripheral. More... | |
cy_rslt_t | cyhal_qspi_set_frequency (cyhal_qspi_t *obj, uint32_t hz) |
Set the QSPI baud rate. More... | |
uint32_t | cyhal_qspi_get_frequency (cyhal_qspi_t *obj) |
Get the actual frequency that QSPI is configured for. More... | |
cy_rslt_t | cyhal_qspi_slave_configure (cyhal_qspi_t *obj, const cyhal_qspi_slave_pin_config_t *pin_set) |
Configure provided set of pins to service additional slave memory. More... | |
cy_rslt_t | cyhal_qspi_select_active_ssel (cyhal_qspi_t *obj, cyhal_gpio_t ssel) |
Selects an active slave select (SSEL) line from one of available and previously configured. More... | |
cy_rslt_t | cyhal_qspi_read (cyhal_qspi_t *obj, const cyhal_qspi_command_t *command, uint32_t address, void *data, size_t *length) |
Receive a command and block of data, synchronously. More... | |
cy_rslt_t | cyhal_qspi_read_async (cyhal_qspi_t *obj, const cyhal_qspi_command_t *command, uint32_t address, void *data, size_t *length) |
Receive a command and block of data in asynchronous mode. More... | |
cy_rslt_t | cyhal_qspi_write (cyhal_qspi_t *obj, const cyhal_qspi_command_t *command, uint32_t address, const void *data, size_t *length) |
Send a command and block of data, synchronously. More... | |
cy_rslt_t | cyhal_qspi_write_async (cyhal_qspi_t *obj, const cyhal_qspi_command_t *command, uint32_t address, const void *data, size_t *length) |
Send a command and block of data in asynchronous mode. More... | |
cy_rslt_t | cyhal_qspi_transfer (cyhal_qspi_t *obj, const cyhal_qspi_command_t *command, uint32_t address, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size) |
Send a command (and optionally data) and get the response. More... | |
void | cyhal_qspi_register_callback (cyhal_qspi_t *obj, cyhal_qspi_event_callback_t callback, void *callback_arg) |
Register a QSPI event handler. More... | |
void | cyhal_qspi_enable_event (cyhal_qspi_t *obj, cyhal_qspi_event_t event, uint8_t intr_priority, bool enable) |
Configure QSPI interrupt enablement. More... | |
struct cyhal_qspi_command_t |
Data Fields | ||
---|---|---|
struct cyhal_qspi_command_t.instruction | instruction | Instruction structure. |
struct cyhal_qspi_command_t.address | address | Address structure. |
struct cyhal_qspi_command_t.mode_bits | mode_bits | Mode bits structure. |
struct cyhal_qspi_command_t.dummy_cycles | dummy_cycles | Dummy cycles structure. |
struct cyhal_qspi_command_t.data | data | Data structure. |
struct cyhal_qspi_slave_pin_config_t |
Data Fields | ||
---|---|---|
cyhal_gpio_t | io[8] | IOx lines of connected memory. |
cyhal_gpio_t | ssel | Slave Select line of connected memory. |
struct cyhal_qspi_command_t.instruction |
Data Fields | ||
---|---|---|
cyhal_qspi_bus_width_t | bus_width | Bus width for the instruction. |
cyhal_qspi_datarate_t | data_rate | Data rate SDR/DDR. |
bool | two_byte_cmd | Defines whether cmd is 2-byte value, or 1-byte (if false) |
uint16_t | value | Instruction value. |
bool | disabled | Instruction phase skipped if disabled is set to true. |
struct cyhal_qspi_command_t.address |
Data Fields | ||
---|---|---|
cyhal_qspi_bus_width_t | bus_width | Bus width for the address. |
cyhal_qspi_datarate_t | data_rate | Data rate SDR/DDR. |
cyhal_qspi_size_t | size | Address size. |
bool | disabled | Address phase skipped if disabled is set to true. |
struct cyhal_qspi_command_t.mode_bits |
Data Fields | ||
---|---|---|
cyhal_qspi_bus_width_t | bus_width |
Bus width for mode bits |
cyhal_qspi_datarate_t | data_rate | Data rate SDR/DDR. |
cyhal_qspi_size_t | size | Mode bits size. |
uint32_t | value | Mode bits value. |
bool | disabled | Mode bits phase skipped if disabled is set to true. |
struct cyhal_qspi_command_t.dummy_cycles |
Data Fields | ||
---|---|---|
cyhal_qspi_bus_width_t | bus_width |
Bus width for mode bits |
cyhal_qspi_datarate_t | data_rate | Data rate SDR/DDR. |
uint32_t | dummy_count | Dummy cycles count. |
struct cyhal_qspi_command_t.data |
Data Fields | ||
---|---|---|
cyhal_qspi_bus_width_t | bus_width | Bus width for data. |
cyhal_qspi_datarate_t | data_rate | Data rate SDR/DDR. |
enum cyhal_qspi_size_t |
enum cyhal_qspi_event_t |
cy_rslt_t cyhal_qspi_init | ( | cyhal_qspi_t * | obj, |
cyhal_gpio_t | sclk, | ||
const cyhal_qspi_slave_pin_config_t * | pin_set, | ||
uint32_t | hz, | ||
uint8_t | mode, | ||
cyhal_clock_t * | clk | ||
) |
Initialize QSPI peripheral.
It should initialize QSPI pins (io0-io7, sclk and ssel), set frequency, clock polarity and phase mode. The clock for the peripheral should be enabled
[out] | obj | Pointer to a QSPI object. The caller must allocate the memory for this object but the init function will initialize its contents. |
[in] | sclk | The clock pin |
[in] | pin_set | Set of pins, that will primarily be used for communication with memory. Depends on device, QSPI HAL can service multiple memories which can be registered and controlled using cyhal_qspi_slave_configure and cyhal_qspi_select_active_ssel functions. There is no need to call cyhal_qspi_select_active_ssel after this function - provided ssel pin as part of pin_set parameter become active. |
[in] | hz | The bus frequency |
[in] | mode | Clock polarity and phase mode (0 - 3) |
[in] | clk | The clock to use can be shared, if not provided a new clock will be allocated |
cy_rslt_t cyhal_qspi_init_cfg | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_configurator_t * | cfg | ||
) |
Initialize the QSPI peripheral using a configurator generated configuration struct.
This function may not support all features, that can be configured via configurator. For limitations list please refer to Configurator-generated features limitations section.
[in] | obj | The QSPI peripheral to configure |
[in] | cfg | Configuration structure generated by a configurator. |
void cyhal_qspi_free | ( | cyhal_qspi_t * | obj | ) |
Deinitilize QSPI peripheral.
It should release pins that are associated with the QSPI object, and disable clocks for QSPI peripheral module that was associated with the object
[in,out] | obj | QSPI object |
cy_rslt_t cyhal_qspi_set_frequency | ( | cyhal_qspi_t * | obj, |
uint32_t | hz | ||
) |
Set the QSPI baud rate.
Actual frequency may differ from the desired frequency due to available dividers and the bus clock. Function will apply achieved frequency only if it is in +0% /-10% deviation bounds from desired. Use cyhal_qspi_get_frequency function to get actual frequency value that was achieved and set.
[in] | obj | The QSPI object to configure |
[in] | hz | The baud rate in Hz |
uint32_t cyhal_qspi_get_frequency | ( | cyhal_qspi_t * | obj | ) |
Get the actual frequency that QSPI is configured for.
[in] | obj | The QSPI object |
cy_rslt_t cyhal_qspi_slave_configure | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_slave_pin_config_t * | pin_set | ||
) |
Configure provided set of pins to service additional slave memory.
Multiple pins can be configured as QSPI slave select pins as well as IO pins may be (or may not be) shared and used to service multiple connected slave memories. This function can be called multiple times - each call for each additional slave memory. Please refer to device datasheet for details. Switching between configured slave select pins is done by cyhal_qspi_select_active_ssel function. Unless modified with this function, the SSEL pin provided as part of cyhal_qspi_init is the default. Please refer to Code Snippet 5: Configuring multiple memories for example of configuration multiple memory devices and switching between them.
[in] | obj | The QSPI object to configure |
[in] | pin_set | Set of pins, that will be used to service additional slave memory. |
cy_rslt_t cyhal_qspi_select_active_ssel | ( | cyhal_qspi_t * | obj, |
cyhal_gpio_t | ssel | ||
) |
Selects an active slave select (SSEL) line from one of available and previously configured.
Slave memories (in addition to one, that was configured in scope of cyhal_qspi_init) can be added with help of cyhal_qspi_slave_configure function.
[in] | obj | The QSPI object to configure |
[in] | ssel | SSEL pin to be set as active |
cy_rslt_t cyhal_qspi_read | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_command_t * | command, | ||
uint32_t | address, | ||
void * | data, | ||
size_t * | length | ||
) |
Receive a command and block of data, synchronously.
This will read either length
bytes or the number of bytes that are currently available in the receive buffer, whichever is less, then return. The value pointed to by length
will be updated to reflect the number of bytes that were actually read.
[in] | obj | QSPI object |
[in] | command | QSPI command |
[in] | address | Address to access to |
[out] | data | RX buffer |
[in] | length | RX buffer length in bytes |
cy_rslt_t cyhal_qspi_read_async | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_command_t * | command, | ||
uint32_t | address, | ||
void * | data, | ||
size_t * | length | ||
) |
Receive a command and block of data in asynchronous mode.
This will transfer length
bytes into the buffer pointed to by data
in the background. When the requested quantity of data has been read, the CYHAL_QSPI_IRQ_RECEIVE_DONE event will be raised. See cyhal_qspi_register_callback and cyhal_qspi_enable_event.
[in] | obj | QSPI object |
[in] | command | QSPI command |
[in] | address | Address to access to |
[out] | data | RX buffer |
[in] | length | RX buffer length in bytes |
cy_rslt_t cyhal_qspi_write | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_command_t * | command, | ||
uint32_t | address, | ||
const void * | data, | ||
size_t * | length | ||
) |
Send a command and block of data, synchronously.
This will write either length
bytes or until the write buffer is full, whichever is less, then return. The value pointed to by length
will be updated to reflect the number of bytes that were actually written.
[in] | obj | QSPI object |
[in] | command | QSPI command |
[in] | address | Address to access to |
[in] | data | TX buffer |
[in] | length | TX buffer length in bytes |
cy_rslt_t cyhal_qspi_write_async | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_command_t * | command, | ||
uint32_t | address, | ||
const void * | data, | ||
size_t * | length | ||
) |
Send a command and block of data in asynchronous mode.
This will transfer length
bytes into the tx buffer in the background. When the requested quantity of data has been queued in the transmit buffer, the CYHAL_QSPI_IRQ_TRANSMIT_DONE event will be raised. See cyhal_qspi_register_callback and cyhal_qspi_enable_event.
[in] | obj | QSPI object |
[in] | command | QSPI command |
[in] | address | Address to access to |
[in] | data | TX buffer |
[in] | length | TX buffer length in bytes |
cy_rslt_t cyhal_qspi_transfer | ( | cyhal_qspi_t * | obj, |
const cyhal_qspi_command_t * | command, | ||
uint32_t | address, | ||
const void * | tx_data, | ||
size_t | tx_size, | ||
void * | rx_data, | ||
size_t | rx_size | ||
) |
Send a command (and optionally data) and get the response.
Can be used to send/receive device specific commands
[in] | obj | QSPI object |
[in] | command | QSPI command |
[in] | address | Address to access to |
[in] | tx_data | TX buffer |
[in] | tx_size | TX buffer length in bytes |
[out] | rx_data | RX buffer |
[in] | rx_size | RX buffer length in bytes |
void cyhal_qspi_register_callback | ( | cyhal_qspi_t * | obj, |
cyhal_qspi_event_callback_t | callback, | ||
void * | callback_arg | ||
) |
Register a QSPI event handler.
This function will be called when one of the events enabled by cyhal_qspi_enable_event occurs.
[in] | obj | The QSPI object |
[in] | callback | The callback handler which will be invoked when the interrupt fires |
[in] | callback_arg | Generic argument that will be provided to the handler when called |
void cyhal_qspi_enable_event | ( | cyhal_qspi_t * | obj, |
cyhal_qspi_event_t | event, | ||
uint8_t | intr_priority, | ||
bool | enable | ||
) |
Configure QSPI interrupt enablement.
When an enabled event occurs, the function specified by cyhal_qspi_register_callback will be called.
[in] | obj | The QSPI object |
[in] | event | The QSPI event type |
[in] | intr_priority | The priority for NVIC interrupt events |
[in] | enable | True to turn on interrupts, False to turn off |