Overview

The SDCARD driver provide card initialization/read/write/erase interface.

SD CARD Operation

error log support

Lots of error log has been added to sd relate functions, if error occurs during initial/read/write, please enable the error log print functionality with #define SDMMC_ENABLE_LOG_PRINT 1 And rerun the project then user can check what kind of error happened.

User configurable

typedef struct _sd_card
{
    sdmmchost_t *host; 
    sd_usr_param_t usrParam; 
    bool isHostReady;        
    bool noInteralAlign;      
    uint32_t busClock_Hz;     
    uint32_t relativeAddress; 
    uint32_t version;         
    uint32_t flags;           
    uint8_t internalBuffer[FSL_SDMMC_CARD_INTERNAL_BUFFER_SIZE]; 
    uint32_t ocr;                                                
    sd_cid_t cid;                                                
    sd_csd_t csd;                                                
    sd_scr_t scr;                                                
    sd_status_t stat;                                            
    uint32_t blockCount;                                         
    uint32_t blockSize;                                          
    sd_timing_mode_t currentTiming;                              
    sd_driver_strength_t driverStrength;                         
    sd_max_current_t maxCurrent;                                 
    sdmmc_operation_voltage_t operationVoltage;                  
    sdmmc_osa_mutex_t lock;                                      
} sd_card_t;

Part of The variables above is user configurable,

host

Application need to provide host controller base address and the host's source clock frequency, etc. For example:

/* allocate dma descriptor buffer for host controller */

s_host.dmaDesBuffer = s_sdmmcHostDmaBuffer;

s_host.dmaDesBufferWordsNum = xxx;

/* */

((sd_card_t *)card)->host = &s_host;

((sd_card_t *)card)->host->hostController.base = BOARD_SDMMC_SD_HOST_BASEADDR;

((sd_card_t *)card)->host->hostController.sourceClock_Hz = BOARD_USDHC1ClockConfiguration();

/* allocate resource for sdmmc osa layer */

((sd_card_t *)card)->host->hostEvent = &s_event;
sdcard_usr_param_t usrParam

/* board layer configuration register */
((sd_card_t *)card)->usrParam.cd         = &s_cd;
((sd_card_t *)card)->usrParam.pwr        = BOARD_SDCardPowerControl;
((sd_card_t *)card)->usrParam.ioStrength = BOARD_SD_Pin_Config;
((sd_card_t *)card)->usrParam.ioVoltage  = &s_ioVoltage;
((sd_card_t *)card)->usrParam.maxFreq    = BOARD_SDMMC_SD_HOST_SUPPORT_SDR104_FREQ;
a. cd-which allow application define the card insert/remove callback function, redefine the card detect timeout ms and also allow application determine how to detect card.
b. pwr-which allow application redefine the card power on/off function.
c. ioStrength-which is used to switch the signal pin configurations include driver strength/speed mode dynamiclly for different timing(SDR/HS timing) mode, reference the function defined sdmmc_config.c
d. ioVoltage-which allow application register io voltage switch function instead of using the function host driver provided for SDR/HS200/HS400 timing.
e. maxFreq-which allow application set the maximum bus clock that the board support.

bool noInteralAlign

Sdmmc include an address align internal buffer(to use host controller internal DMA), to improve read/write performance while application cannot make sure the data address used to read/write is align, set it to true will achieve a better performance.
sd_timing_mode_t currentTiming

It is used to indicate the currentTiming the card is working on, however sdmmc also support preset timing mode, then sdmmc will try to switch to this timing first, if failed, a valid timing will switch to automatically. Generally, user may not set this variable if you don't know what kind of timing the card support, sdmmc will switch to the highest timing which the card support.
sd_driver_strength_t driverStrength

Choose a valid card driver strength if application required and call SD_SetDriverStrength in application.
sd_max_current_t maxCurrent

Choose a valid card current if application required and call SD_SetMaxCurrent in application.

Mutual exclusive access support for RTOS

SDCARD driver has added mutual exclusive access support for init/deinit/write/read/erase function. Please note that the card init function will create the mutex lock dynamically by default, so to avoid the mutex create redundantly, application must follow bellow sequence for card re-initialization

SD_Deinit(card);/* This function will destroy the created mutex */

SD_Init(card);

Typical use case

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/sdmmc_examples/

Data Structures
struct	sd_card_t
	SD card state. More...

Macros
#define	FSL_SD_DRIVER_VERSION (MAKE_VERSION(2U, 4U, 0U)) /2.4.0/
	Driver version. More...

Enumerations
enum	{ kSD_SupportHighCapacityFlag = (1U << 1U), kSD_Support4BitWidthFlag = (1U << 2U), kSD_SupportSdhcFlag = (1U << 3U), kSD_SupportSdxcFlag = (1U << 4U), kSD_SupportVoltage180v = (1U << 5U), kSD_SupportSetBlockCountCmd = (1U << 6U), kSD_SupportSpeedClassControlCmd = (1U << 7U) }
	SD card flags. More...

SDCARD Function
status_t	SD_Init (sd_card_t *card)
	Initializes the card on a specific host controller. More...

void	SD_Deinit (sd_card_t *card)
	Deinitializes the card. More...

status_t	SD_CardInit (sd_card_t *card)
	Initializes the card. More...

void	SD_CardDeinit (sd_card_t *card)
	Deinitializes the card. More...

status_t	SD_HostInit (sd_card_t *card)
	initialize the host. More...

void	SD_HostDeinit (sd_card_t *card)
	Deinitializes the host. More...

void	SD_HostDoReset (sd_card_t *card)
	reset the host. More...

void	SD_SetCardPower (sd_card_t *card, bool enable)
	set card power. More...

status_t	SD_PollingCardInsert (sd_card_t *card, uint32_t status)
	sd wait card detect function. More...

bool	SD_IsCardPresent (sd_card_t *card)
	sd card present check function. More...

bool	SD_CheckReadOnly (sd_card_t *card)
	Checks whether the card is write-protected. More...

status_t	SD_SelectCard (sd_card_t *card, bool isSelected)
	Send SELECT_CARD command to set the card to be transfer state or not. More...

status_t	SD_ReadStatus (sd_card_t *card)
	Send ACMD13 to get the card current status. More...

status_t	SD_ReadBlocks (sd_card_t card, uint8_t buffer, uint32_t startBlock, uint32_t blockCount)
	Reads blocks from the specific card. More...

status_t	SD_WriteBlocks (sd_card_t card, const uint8_t buffer, uint32_t startBlock, uint32_t blockCount)
	Writes blocks of data to the specific card. More...

status_t	SD_EraseBlocks (sd_card_t *card, uint32_t startBlock, uint32_t blockCount)
	Erases blocks of the specific card. More...

status_t	SD_SetDriverStrength (sd_card_t *card, sd_driver_strength_t driverStrength)
	select card driver strength select card driver strength More...

status_t	SD_SetMaxCurrent (sd_card_t *card, sd_max_current_t maxCurrent)
	select max current select max operation current More...

status_t	SD_PollingCardStatusBusy (sd_card_t *card, uint32_t timeoutMs)
	Polling card idle status. More...

Data Structure Documentation

struct sd_card_t

Define the card structure including the necessary fields to identify and describe the card.

Data Fields
sdmmchost_t *	host
	Host configuration.

sd_usr_param_t	usrParam
	user parameter

bool	isHostReady
	use this flag to indicate if need host re-init or not

bool	noInteralAlign
	used to enable/disable the functionality of the exchange buffer

uint32_t	busClock_Hz
	SD bus clock frequency united in Hz.

uint32_t	relativeAddress
	Relative address of the card.

uint32_t	version
	Card version.

uint32_t	flags
	Flags in _sd_card_flag.

uint8_t	internalBuffer [FSL_SDMMC_CARD_INTERNAL_BUFFER_SIZE]
	internal buffer

uint32_t	ocr
	Raw OCR content.

sd_cid_t	cid
	CID.

sd_csd_t	csd
	CSD.

sd_scr_t	scr
	SCR.

sd_status_t	stat
	sd 512 bit status

uint32_t	blockCount
	Card total block number.

uint32_t	blockSize
	Card block size.

sd_timing_mode_t	currentTiming
	current timing mode

sd_driver_strength_t	driverStrength
	driver strength

sd_max_current_t	maxCurrent
	card current limit

sdmmc_operation_voltage_t	operationVoltage
	card operation voltage

sdmmc_osa_mutex_t	lock
	card access lock

Macro Definition Documentation

#define FSL_SD_DRIVER_VERSION (MAKE_VERSION(2U, 4U, 0U)) /*2.4.0*/

Enumeration Type Documentation

anonymous enum

Enumerator
kSD_SupportHighCapacityFlag	Support high capacity.
kSD_Support4BitWidthFlag	Support 4-bit data width.
kSD_SupportSdhcFlag	Card is SDHC.
kSD_SupportSdxcFlag	Card is SDXC.
kSD_SupportVoltage180v	card support 1.8v voltage
kSD_SupportSetBlockCountCmd	card support cmd23 flag
kSD_SupportSpeedClassControlCmd	card support speed class control flag

Function Documentation

status_t SD_Init ( sd_card_t * card )

This function initializes the card on a specific host controller, it is consist of host init, card detect, card init function, however user can ignore this high level function, instead of use the low level function, such as SD_CardInit, SD_HostInit, SD_CardDetect.

Thread safe function, please note that the function will create the mutex lock dynamically by default, so to avoid the mutex create redundantly, application must follow bellow sequence for card re-initialization

* SD_Deinit(card);
* SD_Init(card);
* 

Parameters

card	Card descriptor.

Return values

kStatus_SDMMC_HostNotReady	host is not ready.
kStatus_SDMMC_GoIdleFailed	Go idle failed.
kStatus_SDMMC_NotSupportYet	Card not support.
kStatus_SDMMC_HandShakeOperationConditionFailed	Send operation condition failed.
kStatus_SDMMC_AllSendCidFailed	Send CID failed.
kStatus_SDMMC_SendRelativeAddressFailed	Send relative address failed.
kStatus_SDMMC_SendCsdFailed	Send CSD failed.
kStatus_SDMMC_SelectCardFailed	Send SELECT_CARD command failed.
kStatus_SDMMC_SendScrFailed	Send SCR failed.
kStatus_SDMMC_SetDataBusWidthFailed	Set bus width failed.
kStatus_SDMMC_SwitchBusTimingFailed	Switch high speed failed.
kStatus_SDMMC_SetCardBlockSizeFailed	Set card block size failed.
kStatus_Success	Operate successfully.

void SD_Deinit ( sd_card_t * card )

This function deinitializes the specific card and host. Please note it is a thread safe function.

Parameters

card	Card descriptor.

status_t SD_CardInit ( sd_card_t * card )

This function initializes the card only, make sure the host is ready when call this function, otherwise it will return kStatus_SDMMC_HostNotReady.

Thread safe function, please note that the function will create the mutex lock dynamically by default, so to avoid the mutex create redundantly, application must follow bellow sequence for card re-initialization

* SD_CardDeinit(card);
* SD_CardInit(card);
* 

Parameters

card	Card descriptor.

Return values

kStatus_SDMMC_HostNotReady	host is not ready.
kStatus_SDMMC_GoIdleFailed	Go idle failed.
kStatus_SDMMC_NotSupportYet	Card not support.
kStatus_SDMMC_HandShakeOperationConditionFailed	Send operation condition failed.
kStatus_SDMMC_AllSendCidFailed	Send CID failed.
kStatus_SDMMC_SendRelativeAddressFailed	Send relative address failed.
kStatus_SDMMC_SendCsdFailed	Send CSD failed.
kStatus_SDMMC_SelectCardFailed	Send SELECT_CARD command failed.
kStatus_SDMMC_SendScrFailed	Send SCR failed.
kStatus_SDMMC_SetDataBusWidthFailed	Set bus width failed.
kStatus_SDMMC_SwitchBusTimingFailed	Switch high speed failed.
kStatus_SDMMC_SetCardBlockSizeFailed	Set card block size failed.
kStatus_Success	Operate successfully.

void SD_CardDeinit ( sd_card_t * card )

This function deinitializes the specific card. Please note it is a thread safe function.

Parameters

card	Card descriptor.

status_t SD_HostInit ( sd_card_t * card )

This function deinitializes the specific host.

Parameters

card	Card descriptor.

void SD_HostDeinit ( sd_card_t * card )

This function deinitializes the host.

Parameters

card	Card descriptor.

void SD_HostDoReset ( sd_card_t * card )

This function reset the specific host.

Parameters

card	Card descriptor.

void SD_SetCardPower	(	sd_card_t *	card,
		bool	enable
	)

The power off operation depend on host or the user define power on function.

Parameters

card	card descriptor.
enable	true is power on, false is power off.

status_t SD_PollingCardInsert	(	sd_card_t *	card,
		uint32_t	status
	)

Detect card through GPIO, CD, DATA3.

Parameters

card	card descriptor.
status	detect status, kSD_Inserted or kSD_Removed.

bool SD_IsCardPresent ( sd_card_t * card )

Parameters

card	card descriptor.

bool SD_CheckReadOnly ( sd_card_t * card )

This function checks if the card is write-protected via the CSD register.

Parameters

card	The specific card.

Return values

true	Card is read only.
false	Card isn't read only.

status_t SD_SelectCard	(	sd_card_t *	card,
		bool	isSelected
	)

Parameters

card	Card descriptor.
isSelected	True to set the card into transfer state, false to disselect.

Return values

kStatus_SDMMC_TransferFailed	Transfer failed.
kStatus_Success	Operate successfully.

status_t SD_ReadStatus ( sd_card_t * card )

Parameters

card	Card descriptor.

Return values

kStatus_SDMMC_TransferFailed	Transfer failed.
kStatus_SDMMC_SendApplicationCommandFailed	send application command failed.
kStatus_Success	Operate successfully.

status_t SD_ReadBlocks	(	sd_card_t *	card,
		uint8_t *	buffer,
		uint32_t	startBlock,
		uint32_t	blockCount
	)

This function reads blocks from the specific card with default block size defined by the SDHC_CARD_DEFAULT_BLOCK_SIZE.

Please note it is a thread safe function.

Parameters

card	Card descriptor.
buffer	The buffer to save the data read from card.
startBlock	The start block index.
blockCount	The number of blocks to read.

Return values

kStatus_InvalidArgument	Invalid argument.
kStatus_SDMMC_CardNotSupport	Card not support.
kStatus_SDMMC_NotSupportYet	Not support now.
kStatus_SDMMC_WaitWriteCompleteFailed	Send status failed.
kStatus_SDMMC_TransferFailed	Transfer failed.
kStatus_SDMMC_StopTransmissionFailed	Stop transmission failed.
kStatus_Success	Operate successfully.

status_t SD_WriteBlocks	(	sd_card_t *	card,
		const uint8_t *	buffer,
		uint32_t	startBlock,
		uint32_t	blockCount
	)

This function writes blocks to the specific card with default block size 512 bytes.

Please note,

It is a thread safe function.
It is a async write function which means that the card status may still busy after the function return. Application can call function SD_PollingCardStatusBusy to wait card status idle after the write operation.

Parameters

card	Card descriptor.
buffer	The buffer holding the data to be written to the card.
startBlock	The start block index.
blockCount	The number of blocks to write.

Return values

kStatus_InvalidArgument	Invalid argument.
kStatus_SDMMC_NotSupportYet	Not support now.
kStatus_SDMMC_CardNotSupport	Card not support.
kStatus_SDMMC_WaitWriteCompleteFailed	Send status failed.
kStatus_SDMMC_TransferFailed	Transfer failed.
kStatus_SDMMC_StopTransmissionFailed	Stop transmission failed.
kStatus_Success	Operate successfully.

status_t SD_EraseBlocks	(	sd_card_t *	card,
		uint32_t	startBlock,
		uint32_t	blockCount
	)

This function erases blocks of the specific card with default block size 512 bytes.

Please note,

It is a thread safe function.
It is a async erase function which means that the card status may still busy after the function return. Application can call function SD_PollingCardStatusBusy to wait card status idle after the erase operation.

Parameters

card	Card descriptor.
startBlock	The start block index.
blockCount	The number of blocks to erase.

Return values

kStatus_InvalidArgument	Invalid argument.
kStatus_SDMMC_WaitWriteCompleteFailed	Send status failed.
kStatus_SDMMC_TransferFailed	Transfer failed.
kStatus_SDMMC_WaitWriteCompleteFailed	Send status failed.
kStatus_Success	Operate successfully.

status_t SD_SetDriverStrength	(	sd_card_t *	card,
		sd_driver_strength_t	driverStrength
	)

Parameters

card	Card descriptor.
driverStrength	Driver strength

status_t SD_SetMaxCurrent	(	sd_card_t *	card,
		sd_max_current_t	maxCurrent
	)

Parameters

card	Card descriptor.
maxCurrent	Max current

status_t SD_PollingCardStatusBusy	(	sd_card_t *	card,
		uint32_t	timeoutMs
	)

This function can be used to polling the status from busy to Idle, the function will return if the card status idle or timeout.

Parameters

card	Card descriptor.
timeoutMs	polling card status timeout value.

Return values

kStatus_Success	Operate successfully.
kStatus_SDMMC_WaitWriteCompleteFailed	CMD13 transfer failed.
kStatus_SDMMC_PollingCardIdleFailed,polling	card DAT0 idle failed.

Overview

SD CARD Operation

error log support

User configurable

Mutual exclusive access support for RTOS

Typical use case

Data Structures

Macros

Enumerations

SDCARD Function

Data Structure Documentation

Data Fields

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation