API Reference

group Group_board_libs

In addition to the APIs for reading and writting to memory at runtime, this library also provides support for informing programming tools about the external memory so it can be be written at the same time as internal flash.

This support can be enabled by defining CY_ENABLE_XIP_PROGRAM while building the application. With this define in place, code will be generated in the .cy_sflash_user_data & .cy_toc_part2 sections. These locations can be read by programming tools (eg: Cypress Programmer, OpenOCD, pyOCD) to know that there is a memory device attached and how to program it.

DMA Resource Usage

This library uses fixed DMA (Datawire or DW) resources and supports DMA only for the following devices. DMA is not supported for other devices and the functions cy_serial_flash_qspi_read_async() and cy_serial_flash_qspi_abort_read() will return CY_RSLT_SERIAL_FLASH_ERR_UNSUPPORTED error and cy_serial_flash_qspi_set_dma_interrupt_priority() will simply return doing nothing.

  • CY8C6xx4, CY8C6xx5, CY8C6xx8, CY8C6xxA, CYB06xx5, CYB06xxA, CYS06xxA: DW1, Channel 23

  • CY8C6xx6, CY8C6xx7, CYB06xx7: DW1, Channel 15

Defines

CY_RSLT_SERIAL_FLASH_ERR_UNSUPPORTED

The function or operation is not supported on the target or the memory.

CY_RSLT_SERIAL_FLASH_ERR_BAD_PARAM

Parameters passed to a function are invalid.

CY_RSLT_SERIAL_FLASH_ERR_READ_BUSY

A previously initiated read operation is not yet complete.

CY_RSLT_SERIAL_FLASH_ERR_DMA

A DMA error occurred during read transfer.

CY_RSLT_SERIAL_FLASH_ERR_QSPI_BUSY

Read abort failed.

QSPI block is busy.

CY_SERIAL_FLASH_QSPI_THREAD_SAFE

Enables thread-safety for use with multi-threaded RTOS environment.

Typedefs

typedef void (*cy_serial_flash_qspi_read_complete_callback_t)(cy_rslt_t operation_status, void *callback_arg)

Callback pointer to use with cy_serial_flash_qspi_read_async().

Parameters

  • peration_status: Status of the read operation

  • callback_arg: Pointer to be passed back to the callback function

Functions

cy_rslt_t cy_serial_flash_qspi_init(const cy_stc_smif_mem_config_t *mem_config, cyhal_gpio_t io0, cyhal_gpio_t io1, cyhal_gpio_t io2, cyhal_gpio_t io3, cyhal_gpio_t io4, cyhal_gpio_t io5, cyhal_gpio_t io6, cyhal_gpio_t io7, cyhal_gpio_t sclk, cyhal_gpio_t ssel, uint32_t hz)

Initializes the serial flash memory.

This function accepts up to 8 I/Os. Number of I/Os depend on the type of memory interface. Pass NC when an I/O is unused. Single SPI - (io0, io1) or (io2, io3) or (io4, io5) or (io6, io7) Dual SPI - (io0, io1) or (io2, io3) or (io4, io5) or (io6, io7) Quad SPI - (io0, io1, io2, io3) or (io4, io5, io6, io7) Octal SPI - All 8 I/Os are used.

Return

CY_RSLT_SUCCESS if the initialization was successful, an error code otherwise.

Parameters

  • mem_config: Memory configuration to be used for initializing

  • io0: Data/IO pin 0 connected to the memory, Pass NC when unused.

  • io1: Data/IO pin 1 connected to the memory, Pass NC when unused.

  • io2: Data/IO pin 2 connected to the memory, Pass NC when unused.

  • io3: Data/IO pin 3 connected to the memory, Pass NC when unused.

  • io4: Data/IO pin 4 connected to the memory, Pass NC when unused.

  • io5: Data/IO pin 5 connected to the memory, Pass NC when unused.

  • io6: Data/IO pin 6 connected to the memory, Pass NC when unused.

  • io7: Data/IO pin 7 connected to the memory, Pass NC when unused.

  • sclk: Clock pin connected to the memory

  • ssel: Slave select pin connected to the memory

  • hz: Clock frequency to be used with the memory.

void cy_serial_flash_qspi_deinit(void)

De-initializes the serial flash memory.

Before calling this function, ensure that an ongoing asynchronous read operation is either completed or successfully aborted. Async read is started by calling cy_serial_flash_qspi_read_async() and aborted by calling cy_serial_flash_qspi_abort_read().

size_t cy_serial_flash_qspi_get_size(void)

Returns the size of the serial flash memory in bytes.

Return

Memory size in bytes.

size_t cy_serial_flash_qspi_get_erase_size(uint32_t addr)

Returns the size of the erase sector to which the given address belongs.

Address is used only for a memory with hybrid sector size.

Return

Erase sector size in bytes.

Parameters

  • addr: Address that belongs to the sector for which size is returned.

size_t cy_serial_flash_qspi_get_prog_size(uint32_t addr)

Returns the page size for programming of the sector to which the given address belongs.

Address is used only for a memory with hybrid sector size.

Return

Page size in bytes.

Parameters

  • addr: Address that belongs to the sector for which size is returned.

__STATIC_INLINE uint32_t cy_serial_flash_get_sector_start_address (uint32_t addr)

Utility function to calculate the starting address of an erase sector to which the given address belongs.

Return

Starting address of the sector

Parameters

  • addr: Address in the sector for which the starting address is returned.

cy_rslt_t cy_serial_flash_qspi_read(uint32_t addr, size_t length, uint8_t *buf)

Reads data from the serial flash memory.

This is a blocking function. Returns error if (addr + length) exceeds the flash size.

Return

CY_RSLT_SUCCESS if the read was successful, an error code otherwise.

Parameters

  • addr: Starting address to read from

  • length: Number of data bytes to read

  • buf: Pointer to the buffer to store the data read from the memory

cy_rslt_t cy_serial_flash_qspi_read_async(uint32_t addr, size_t length, uint8_t *buf, cy_serial_flash_qspi_read_complete_callback_t callback, void *callback_arg)

Reads data from the serial flash memory.

This is a non-blocking function. Returns error if (addr + length) exceeds the flash size. Uses fixed DMA (DW) instance and channel for transferring the data from QSPI RX FIFO to the user-provided buffer.

Return

CY_RSLT_SUCCESS if the read was successful, an error code otherwise.

Parameters

  • addr: Starting address to read from

  • length: Number of data bytes to read

  • buf: Pointer to the buffer to store the data read from the memory

  • callback: Pointer to the callback function to be called after the read operation is complete. Callback is invoked from the DMA ISR.

  • callback_arg: Pointer to the argument to be passed to the callback function

cy_rslt_t cy_serial_flash_qspi_abort_read(void)

Aborts an ongoing asynchronous read initiated by calling cy_serial_flash_qspi_read_async().

Return

CY_RSLT_SUCCESS if the abort was successful, an error code if the QSPI block is still busy after a timeout.

cy_rslt_t cy_serial_flash_qspi_write(uint32_t addr, size_t length, const uint8_t *buf)

Writes the data to the serial flash memory.

The program area must have been erased prior to calling this API using cy_serial_flash_qspi_erase() This is a blocking function. Returns error if (addr + length) exceeds the flash size.

Return

CY_RSLT_SUCCESS if the write was successful, an error code otherwise.

Parameters

  • addr: Starting address to write to

  • length: Number of bytes to write

  • buf: Pointer to the buffer storing the data to be written

cy_rslt_t cy_serial_flash_qspi_erase(uint32_t addr, size_t length)

Erases the serial flash memory, uses chip erase command when addr = 0 and length = flash_size otherwise uses sector erase command.

This is a blocking function. Returns error if addr or (addr + length) is not aligned to the sector size or if (addr + length) exceeds the flash size. For memories with hybrid sectors, returns error if the end address (=addr + length) is not aligned to the size of the sector in which the end address is located. Call cy_serial_flash_qspi_get_size() to get the flash size and call cy_serial_flash_qspi_get_erase_size() to get the size of an erase sector.

Return

CY_RSLT_SUCCESS if the erase was successful, an error code otherwise.

Parameters

  • addr: Starting address to begin erasing

  • length: Number of bytes to erase

cy_rslt_t cy_serial_flash_qspi_enable_xip(bool enable)

Enables Execute-in-Place (memory mapped) mode on the MCU.

This function does not send any command to the serial flash. This may not be supported on all the targets in which case CY_RSLT_SERIAL_FLASH_ERR_UNSUPPORTED is returned.

Return

CY_RSLT_SUCCESS if the operation was successful. CY_RSLT_SERIAL_FLASH_ERR_UNSUPPORTED if the target does not support XIP.

Parameters

  • enable: true: XIP mode is set, false: normal mode is set

void cy_serial_flash_qspi_set_interrupt_priority(uint8_t priority)

Changes QSPI interrupt priority.

Parameters

  • priority: interrupt priority to be set

void cy_serial_flash_qspi_set_dma_interrupt_priority(uint8_t priority)

Changes the DMA interrupt priority.

Parameters

  • priority: interrupt priority to be set