General Description

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 sections must be provided by the linker script for the application. One the application has been built, 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.

Note: This support is not compatible with the PSoC™ 64 series of devices.

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

Macros
#define	CY_RSLT_SERIAL_FLASH_ERR_UNSUPPORTED (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 1))
	The function or operation is not supported on the target or the memory.

#define	CY_RSLT_SERIAL_FLASH_ERR_BAD_PARAM (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 2))
	Parameters passed to a function are invalid.

#define	CY_RSLT_SERIAL_FLASH_ERR_READ_BUSY (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 3))
	A previously initiated read operation is not yet complete.

#define	CY_RSLT_SERIAL_FLASH_ERR_DMA (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 4))
	A DMA error occurred during read transfer.

#define	CY_RSLT_SERIAL_FLASH_ERR_QSPI_BUSY (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 5))
	Read abort failed. More...

#define	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(). More...

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. More...

void	cy_serial_flash_qspi_deinit (void)
	De-initializes the serial flash memory. More...

size_t	cy_serial_flash_qspi_get_size (void)
	Returns the size of the serial flash memory in bytes. More...

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. More...

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. More...

__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. More...

cy_rslt_t	cy_serial_flash_qspi_read (uint32_t addr, size_t length, uint8_t *buf)
	Reads data from the serial flash memory. More...

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. More...

cy_rslt_t	cy_serial_flash_qspi_abort_read (void)
	Aborts an ongoing asynchronous read initiated by calling cy_serial_flash_qspi_read_async(). More...

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. More...

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. More...

cy_rslt_t	cy_serial_flash_qspi_enable_xip (bool enable)
	Enables Execute-in-Place (memory mapped) mode on the MCU. More...

void	cy_serial_flash_qspi_set_interrupt_priority (uint8_t priority)
	Changes QSPI interrupt priority. More...

void	cy_serial_flash_qspi_set_dma_interrupt_priority (uint8_t priority)
	Changes the DMA interrupt priority. More...

Macro Definition Documentation

◆ CY_RSLT_SERIAL_FLASH_ERR_QSPI_BUSY

#define CY_RSLT_SERIAL_FLASH_ERR_QSPI_BUSY (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_FLASH, 5))

Read abort failed.

QSPI block is busy.

Typedef Documentation

◆ cy_serial_flash_qspi_read_complete_callback_t

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

operation_status	Status of the read operation
callback_arg	Pointer to be passed back to the callback function

Function Documentation

◆ cy_serial_flash_qspi_init()

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.

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.

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

◆ cy_serial_flash_qspi_deinit()

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().

◆ cy_serial_flash_qspi_get_size()

size_t cy_serial_flash_qspi_get_size ( void )

Returns the size of the serial flash memory in bytes.

Returns: Memory size in bytes.

◆ cy_serial_flash_qspi_get_erase_size()

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.

Parameters

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

Returns: Erase sector size in bytes.

◆ cy_serial_flash_qspi_get_prog_size()

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.

Parameters

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

Returns: Page size in bytes.

◆ cy_serial_flash_get_sector_start_address()

__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.

Parameters

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

Returns: Starting address of the sector

◆ cy_serial_flash_qspi_read()

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.

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

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

◆ cy_serial_flash_qspi_read_async()

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.

Note: If D-cache is enabled, this function cleans the D-cache of the DMA descriptor. The data Cache line is 32 bytes. The user needs to make sure that the buf pointer passed to the cy_serial_flash_qspi_read_async function points to a 32 byte aligned array of words that contains the buffer i.e. the size of buffer must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

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

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

◆ cy_serial_flash_qspi_abort_read()

cy_rslt_t cy_serial_flash_qspi_abort_read ( void )

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

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

◆ cy_serial_flash_qspi_write()

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.

Parameters

addr	Starting address to write to
length	Number of bytes to write
buf	Pointer to the buffer storing the data to be written

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

◆ cy_serial_flash_qspi_erase()

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.

Parameters

addr	Starting address to begin erasing
length	Number of bytes to erase

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

◆ cy_serial_flash_qspi_enable_xip()

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.

Parameters

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

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

◆ cy_serial_flash_qspi_set_interrupt_priority()

void cy_serial_flash_qspi_set_interrupt_priority ( uint8_t priority )

Changes QSPI interrupt priority.

Parameters

priority interrupt priority to be set

◆ cy_serial_flash_qspi_set_dma_interrupt_priority()

void cy_serial_flash_qspi_set_dma_interrupt_priority ( uint8_t priority )

Changes the DMA interrupt priority.

Parameters

priority interrupt priority to be set

General Description

DMA Resource Usage

Macros

Typedefs

Functions

Macro Definition Documentation

◆ CY_RSLT_SERIAL_FLASH_ERR_QSPI_BUSY

Typedef Documentation

◆ cy_serial_flash_qspi_read_complete_callback_t

Function Documentation

◆ cy_serial_flash_qspi_init()

◆ cy_serial_flash_qspi_deinit()

◆ cy_serial_flash_qspi_get_size()

◆ cy_serial_flash_qspi_get_erase_size()

◆ cy_serial_flash_qspi_get_prog_size()

◆ cy_serial_flash_get_sector_start_address()

◆ cy_serial_flash_qspi_read()

◆ cy_serial_flash_qspi_read_async()

◆ cy_serial_flash_qspi_abort_read()

◆ cy_serial_flash_qspi_write()

◆ cy_serial_flash_qspi_erase()

◆ cy_serial_flash_qspi_enable_xip()

◆ cy_serial_flash_qspi_set_interrupt_priority()

◆ cy_serial_flash_qspi_set_dma_interrupt_priority()