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.

Data Structures
struct	lfs_sd_bd_config_t
	Configuration structure for the SD block device. More...

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

Functions
void	lfs_sd_bd_get_default_config (lfs_sd_bd_config_t *bd_cfg)
	Fetches the default configuration for the block device for use with the lfs_sd_bd_create() function. More...
cy_rslt_t	lfs_sd_bd_create (struct lfs_config *lfs_cfg, const lfs_sd_bd_config_t *bd_cfg)
	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...

---

Data Structure Documentation

lfs_sd_bd_config_t

struct lfs_sd_bd_config_t

Data Fields
cyhal_sdhc_t	sdhc_obj	Object for use with the SDHC HAL driver.
cyhal_sdhc_config_t	sdhc_config	Card configuration structure to be passed to the HAL driver.
cyhal_gpio_t	cmd	The pin connected to the command signal.
cyhal_gpio_t	clk	The pin connected to the clock signal.
cyhal_gpio_t	data0	The pin connected to the data0 signal.
cyhal_gpio_t	data1	The pin connected to the data1 signal.
cyhal_gpio_t	data2	The pin connected to the data2 signal.
cyhal_gpio_t	data3	The pin connected to the data3 signal.
cyhal_gpio_t	data4	The pin connected to the data4 signal; pass NC when unused.
cyhal_gpio_t	data5	The pin connected to the data5 signal; pass NC when unused.
cyhal_gpio_t	data6	The pin connected to the data6 signal; pass NC when unused.
cyhal_gpio_t	data7	The pin connected to the data7 signal; pass NC when unused.
cyhal_gpio_t	card_detect	The pin connected to the card detect signal.
cyhal_gpio_t	io_volt_sel	The pin connected to the voltage select signal.
cyhal_gpio_t	card_if_pwr_en	The pin connected to the card interface power enable signal.
cyhal_gpio_t	card_mech_write_prot	The pin connected to the write protect signal.
cyhal_gpio_t	led_ctrl	The pin connected to the LED control signal.
cyhal_gpio_t	card_emmc_reset	The pin connected to the eMMC card reset signal.
cyhal_clock_t *	block_clk	The clock to use can be shared, if not provided a new clock will be allocated.

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

void lfs_sd_bd_get_default_config

(

lfs_sd_bd_config_t *

bd_cfg

)

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

Default configuration: SD card (card mode) with 3.3V signalling.

Parameters

bd_cfg

Pointer to the block device configuration structure.

lfs_sd_bd_create()

cy_rslt_t lfs_sd_bd_create	(	struct lfs_config *	lfs_cfg,
		const lfs_sd_bd_config_t *	bd_cfg
	)

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.
bd_cfg	Pointer to the block device configuration structure.

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.