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 operationcallback_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 initializingio0
: 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 memoryssel
: Slave select pin connected to the memoryhz
: 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 fromlength
: Number of data bytes to readbuf
: 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 fromlength
: Number of data bytes to readbuf
: Pointer to the buffer to store the data read from the memorycallback
: 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 tolength
: Number of bytes to writebuf
: 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 erasinglength
: 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