SPI Flash Block Device Driver

General Description

• Implements the block device driver functions for SPI NOR flash for use with the littlefs API.
• Makes use of the serial-flash library.
• Uses the SFDP protocol to automatically discover the flash parameters.
• Provides lfs_spi_flash_bd_lock() and lfs_spi_flash_bd_unlock() functions for use with lfs_config structure when LFS_THREADSAFE macro is defined.

Note:

• Add DEFINE=LFS_THREADSAFE in the Makefile when thread-safety is required.
• Add COMPONENTS=RTOS_AWARE for enabling the RTOS-friendly features such as waiting on a semaphore until the read completion is notified through a callback by serial-flash.
• XIP support in CAT1B devices: When the same memory is used for code execution (XIP) and storing data by Littlefs, macro ENABLE_XIP_LITTLEFS_ON_SAME_NOR_FLASH must be added to DEFINES variable in Makefile. When macro ENABLE_XIP_LITTLEFS_ON_SAME_NOR_FLASH is defined, the Littlefs does not use features of serial-flash not supported for this case, for example, asynchronous transfer. Also, the size of available for Littlefs memory must be restricted by the lfs_spi_flash_bd_configure_memory function.

  Note

  Disabling of the asynchronous transfer can impact the performance of RTOS environment.

• Littlefs can use the memory with blocks of the same size. For hybrid memory, it is compulsory to limit the size available for littlefs by the lfs_spi_flash_bd_configure_memory function to use only same-size blocks.

Data Structures
struct	lfs_spi_flash_bd_config_t
	Configuration structure for the SPI flash block device. More...

Macros
#define	LFS_SPI_FLASH_BD_TRACE(...)
	Enable trace for this driver by defining this macro. More...

Functions
void	lfs_spi_flash_bd_get_default_config (lfs_spi_flash_bd_config_t *bd_cfg)
	Fetches the default configuration for the block device for use with the lfs_spi_flash_bd_create() function. More...
void	lfs_spi_flash_bd_configure_memory (const struct lfs_config *lfs_cfg, uint32_t address, uint32_t region_size)
	Configures the memory region used by littlefs. More...
cy_rslt_t	lfs_spi_flash_bd_create (struct lfs_config *lfs_cfg, const lfs_spi_flash_bd_config_t *bd_cfg)
	Initializes the SPI flash and populates the lfs_config structure with the default values. More...
void	lfs_spi_flash_bd_destroy (const struct lfs_config *lfs_cfg)
	De-initializes the SPI flash and frees the resources. More...
int	lfs_spi_flash_bd_read (const struct lfs_config *lfs_cfg, lfs_block_t block, lfs_off_t off, void *buffer, lfs_size_t size)
	Reads the data starting from a given block and offset. More...
int	lfs_spi_flash_bd_prog (const struct lfs_config *lfs_cfg, lfs_block_t block, lfs_off_t off, const void *buffer, lfs_size_t size)
	Programs or writes the data starting from a given block and offset. More...
int	lfs_spi_flash_bd_erase (const struct lfs_config *lfs_cfg, lfs_block_t block)
	Erases a given block. More...
int	lfs_spi_flash_bd_sync (const struct lfs_config *lfs_cfg)
	Flushes the write cache when present. More...
int	lfs_spi_flash_bd_lock (const struct lfs_config *lfs_cfg)
	Locks or gets the mutex associated with this block device. More...
int	lfs_spi_flash_bd_unlock (const struct lfs_config *lfs_cfg)
	Unlocks or sets the mutex associated with this block device. More...

---

Data Structure Documentation

lfs_spi_flash_bd_config_t

struct lfs_spi_flash_bd_config_t

Data Fields
const cy_stc_smif_mem_config_t *	mem_config	Memory configuration structure that can be auto-generated using the QSPI Configurator tool.
cyhal_gpio_t	io0	Data/IO pin 0 connected to the memory; pass NC when unused.
cyhal_gpio_t	io1	Data/IO pin 1 connected to the memory; pass NC when unused.
cyhal_gpio_t	io2	Data/IO pin 2 connected to the memory; pass NC when unused.
cyhal_gpio_t	io3	Data/IO pin 3 connected to the memory; pass NC when unused.
cyhal_gpio_t	io4	Data/IO pin 4 connected to the memory; pass NC when unused.
cyhal_gpio_t	io5	Data/IO pin 5 connected to the memory; pass NC when unused.
cyhal_gpio_t	io6	Data/IO pin 6 connected to the memory; pass NC when unused.
cyhal_gpio_t	io7	Data/IO pin 7 connected to the memory; pass NC when unused.
cyhal_gpio_t	sclk	Clock pin connected to the memory.
cyhal_gpio_t	ssel	Slave select pin connected to the memory.
uint32_t	freq_hz	Clock frequency to be used with the memory.

Macro Definition Documentation

LFS_SPI_FLASH_BD_TRACE

#define LFS_SPI_FLASH_BD_TRACE

(

...

)

Enable trace for this driver by defining this macro.

You must also define the global trace enable macro LFS_YES_TRACE.

Function Documentation

lfs_spi_flash_bd_get_default_config()

void lfs_spi_flash_bd_get_default_config

(

lfs_spi_flash_bd_config_t *

bd_cfg

)

Fetches the default configuration for the block device for use with the lfs_spi_flash_bd_create() function.

Default configuration: SFDP enabled, QSPI (IO0 to IO3) mode, 50 MHz clock.

Parameters

bd_cfg

Pointer to the block device configuration structure.

lfs_spi_flash_bd_configure_memory()

void lfs_spi_flash_bd_configure_memory	(	const struct lfs_config *	lfs_cfg,
		uint32_t	address,
		uint32_t	region_size
	)

Configures the memory region used by littlefs.

If this function is not called, the littlefs will use the whole size of the memory module. The function must be called before lfs_spi_flash_bd_create(). After de-initialization of littlefs, the settings configured by this function are lost.

Parameters

lfs_cfg	The pointer to the block device configuration structure
address	The start of a memory region available for littlefs.
region_size	The size of a memory region available for littlefs.

lfs_spi_flash_bd_create()

cy_rslt_t lfs_spi_flash_bd_create	(	struct lfs_config *	lfs_cfg,
		const lfs_spi_flash_bd_config_t *	bd_cfg
	)

Initializes the SPI flash and populates the lfs_config structure with the default values.

Parameters

lfs_cfg	Pointer to the lfs_config structure that will be initialized with the default values.
bd_cfg	Pointer to the block device configuration structure.

Returns

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

lfs_spi_flash_bd_destroy()

void lfs_spi_flash_bd_destroy

(

const struct lfs_config *

lfs_cfg

)

De-initializes the SPI flash and frees the resources.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

lfs_spi_flash_bd_read()

int lfs_spi_flash_bd_read	(	const struct lfs_config *	lfs_cfg,
		lfs_block_t	block,
		lfs_off_t	off,
		void *	buffer,
		lfs_size_t	size
	)

Reads the data starting from a given block and offset.

Calls the non-blocking read API from serial-flash and waits on a semaphore until read completes if COMPONENTS=RTOS_AWARE is added in the makefile. Otherwise, calls the blocking read function.

Parameters

lfs_cfg	Pointer to the lfs_config structure.
block	Block number from which read should begin.
off	Offset in the block from which read should begin.
buffer	Pointer to the buffer to store the data read from the memory.
size	Number of bytes to read.

Returns

0 if the read was successful; -1 otherwise.

lfs_spi_flash_bd_prog()

int lfs_spi_flash_bd_prog	(	const struct lfs_config *	lfs_cfg,
		lfs_block_t	block,
		lfs_off_t	off,
		const void *	buffer,
		lfs_size_t	size
	)

Programs or writes the data starting from a given block and offset.

The block must have been previously erased. This is a blocking function.

Parameters

lfs_cfg	Pointer to the lfs_config structure.
block	Block number from which write should begin.
off	Offset in the block from which write should begin.
buffer	Pointer to the buffer that contains the data to be written.
size	Number of bytes to write.

Returns

0 if the write was successful; -1 otherwise.

lfs_spi_flash_bd_erase()

int lfs_spi_flash_bd_erase	(	const struct lfs_config *	lfs_cfg,
		lfs_block_t	block
	)

Erases a given block.

A block must be erased before being programmed. This is a blocking function.

Parameters

lfs_cfg	Pointer to the lfs_config structure.
block	Block number to be erased.

Returns

0 if the write was successful; -1 otherwise.

lfs_spi_flash_bd_sync()

int lfs_spi_flash_bd_sync

(

const struct lfs_config *

lfs_cfg

)

Flushes the write cache when present.

Simply returns zero because QSPI block does not have any write cache in MMIO mode.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

Returns

Always 0.

lfs_spi_flash_bd_lock()

int lfs_spi_flash_bd_lock

(

const struct lfs_config *

lfs_cfg

)

Locks or gets the mutex associated with this block device.

This function is internally called by the littlefs APIs when LFS_THREADSAFE is defined. User should call this function directly only if the other block device functions are directly called and thread-safety is required in that case.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

Returns

0 if locking was successful; -1 otherwise.

lfs_spi_flash_bd_unlock()

int lfs_spi_flash_bd_unlock

(

const struct lfs_config *

lfs_cfg

)

Unlocks or sets the mutex associated with this block device.

This function is internally called by the littlefs APIs when LFS_THREADSAFE is defined. User should call this function directly only if the other block device functions are directly called and thread-safety is required in that case.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

Returns

0 if unlocking was successful; -1 otherwise.