SD Card Block Device Driver

General Description

• Implements the block device driver functions for the SD card (card mode) for use with littlefs API.
• Makes use of the Secure Digital Host Controller (SDHC) HAL driver.
• Provides lfs_sd_bd_lock() and lfs_sd_bd_unlock() functions for use with lfs_config structure when LFS_THREADSAFE macro is defined.
• Thread safety is implemented using only one mutex instance. This means that a thread will get blocked while trying to perform an operation regardless of which SDHC hardware instance it is accessing until another thread completes that operation.

Note:

• Add DEFINE=LFS_THREADSAFE in the Makefile when thread-safety is required.
• Add COMPONENTS=RTOS_AWARE for enabling the RTOS-friendly features of the underlying SDHC HAL driver. An example of such feature is that the read function waits on a semaphore until read completion is indicated through an interrupt.

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

Functions
cy_rslt_t	lfs_sd_bd_create (struct lfs_config *lfs_cfg, const mtb_hal_sdhc_t *sdhc_obj)
	Initializes the SD card interface and populates the lfs_config structure with the default values. More...
void	lfs_sd_bd_destroy (const struct lfs_config *lfs_cfg)
	De-initializes the SD interface and frees the resources. More...
int	lfs_sd_bd_read (const struct lfs_config *lfs_cfg, lfs_block_t block, lfs_off_t off, void *buffer, lfs_size_t size)
	Reads data starting from a given block and offset. More...
int	lfs_sd_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_sd_bd_erase (const struct lfs_config *lfs_cfg, lfs_block_t block)
	Erases a given block. More...
int	lfs_sd_bd_sync (const struct lfs_config *lfs_cfg)
	Flushes the write cache when present. More...
int	lfs_sd_bd_lock (const struct lfs_config *lfs_cfg)
	Locks or gets the mutex associated with this block device. More...
int	lfs_sd_bd_unlock (const struct lfs_config *lfs_cfg)
	Unlocks or sets the mutex associated with this block device. More...

Macro Definition Documentation

LFS_SD_BD_TRACE

#define LFS_SD_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_sd_bd_create()

cy_rslt_t lfs_sd_bd_create	(	struct lfs_config *	lfs_cfg,
		const mtb_hal_sdhc_t *	sdhc_obj
	)

Initializes the SD card interface 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.
sdhc_obj	Pointer to the SDHC HAL object.

Returns

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

lfs_sd_bd_destroy()

void lfs_sd_bd_destroy

(

const struct lfs_config *

lfs_cfg

)

De-initializes the SD interface and frees the resources.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

lfs_sd_bd_read()

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

Reads data starting from a given block and offset.

This is a blocking 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_sd_bd_prog()

int lfs_sd_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_sd_bd_erase()

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

Erases a given block.

SD/MMC cards do not require explicit erase before programming since the card controllers perform erase internally during programming. Therefore, this API is not to be used with the erase() of lfs_config structure. However, user can directly call this API to erase specific blocks of a memory card.

Parameters

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

Returns

0 if the erase was successful; -1 otherwise.

lfs_sd_bd_sync()

int lfs_sd_bd_sync

(

const struct lfs_config *

lfs_cfg

)

Flushes the write cache when present.

Simply returns zero because the SDHC block does not have any write cache.

Parameters

lfs_cfg

Pointer to the lfs_config structure.

Returns

Always 0.

lfs_sd_bd_lock()

int lfs_sd_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_sd_bd_unlock()

int lfs_sd_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.