MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

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;

Part of The variables above is user configurable,

  1. 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;
    2. 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.
3. 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.

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

5. sd_driver_strength_t driverStrength
Choose a valid  card driver strength if application required and call  SD_SetDriverStrength in application.

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

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, 3U, 0U)) /*2.3.0*/
 Driver version. More...
 

Enumerations

enum  _sd_card_flag {
  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_HostReset (SDMMCHOST_CONFIG *host)
 reset the host. More...
 
void SD_PowerOnCard (SDMMCHOST_TYPE *base, const sdmmchost_pwr_card_t *pwr)
 power on card. More...
 
void SD_PowerOffCard (SDMMCHOST_TYPE *base, const sdmmchost_pwr_card_t *pwr)
 power off card. More...
 
void SD_SetCardPower (sd_card_t *card, bool enable)
 set card power. More...
 
status_t SD_WaitCardDetectStatus (SDMMCHOST_TYPE *hostBase, const sdmmchost_detect_card_t *cd, bool waitCardStatus)
 sd wait card detect function. 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...
 

Data Structure Documentation

struct sd_card_t

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

Data Fields

sdmmchost_thost
 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
 

Macro Definition Documentation

#define FSL_SD_DRIVER_VERSION   (MAKE_VERSION(2U, 3U, 0U)) /*2.3.0*/

Enumeration Type Documentation

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)
Deprecated:
Do not use this function. It has been superceded by SD_HostInit,SD_CardInit.

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.

Parameters
cardCard descriptor.
Return values
kStatus_SDMMC_HostNotReadyhost is not ready.
kStatus_SDMMC_GoIdleFailedGo idle failed.
kStatus_SDMMC_NotSupportYetCard not support.
kStatus_SDMMC_SendOperationConditionFailedSend operation condition failed.
kStatus_SDMMC_AllSendCidFailedSend CID failed.
kStatus_SDMMC_SendRelativeAddressFailedSend relative address failed.
kStatus_SDMMC_SendCsdFailedSend CSD failed.
kStatus_SDMMC_SelectCardFailedSend SELECT_CARD command failed.
kStatus_SDMMC_SendScrFailedSend SCR failed.
kStatus_SDMMC_SetBusWidthFailedSet bus width failed.
kStatus_SDMMC_SwitchHighSpeedFailedSwitch high speed failed.
kStatus_SDMMC_SetCardBlockSizeFailedSet card block size failed.
kStatus_SuccessOperate successfully.
void SD_Deinit ( sd_card_t card)
Deprecated:
Do not use this function. It has been superceded by SD_HostDeinit,SD_CardDeinit. This function deinitializes the specific card and host.
Parameters
cardCard 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.

Parameters
cardCard descriptor.
Return values
kStatus_SDMMC_HostNotReadyhost is not ready.
kStatus_SDMMC_GoIdleFailedGo idle failed.
kStatus_SDMMC_NotSupportYetCard not support.
kStatus_SDMMC_SendOperationConditionFailedSend operation condition failed.
kStatus_SDMMC_AllSendCidFailedSend CID failed.
kStatus_SDMMC_SendRelativeAddressFailedSend relative address failed.
kStatus_SDMMC_SendCsdFailedSend CSD failed.
kStatus_SDMMC_SelectCardFailedSend SELECT_CARD command failed.
kStatus_SDMMC_SendScrFailedSend SCR failed.
kStatus_SDMMC_SetBusWidthFailedSet bus width failed.
kStatus_SDMMC_SwitchHighSpeedFailedSwitch high speed failed.
kStatus_SDMMC_SetCardBlockSizeFailedSet card block size failed.
kStatus_SuccessOperate successfully.
void SD_CardDeinit ( sd_card_t card)

This function deinitializes the specific card.

Parameters
cardCard descriptor.
status_t SD_HostInit ( sd_card_t card)

This function deinitializes the specific host.

Parameters
cardCard descriptor.
void SD_HostDeinit ( sd_card_t card)

This function deinitializes the host.

Parameters
cardCard descriptor.
void SD_HostDoReset ( sd_card_t card)

This function reset the specific host.

Parameters
cardCard descriptor.
void SD_HostReset ( SDMMCHOST_CONFIG *  host)

This function reset the specific host.

Deprecated:
Do not use this function. It has been superceded by SD_HostDoReset.
Parameters
hosthost descriptor.
void SD_PowerOnCard ( SDMMCHOST_TYPE *  base,
const sdmmchost_pwr_card_t pwr 
)

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

Deprecated:
Do not use this function. It has been superceded by SD_SetCardPower.
Parameters
basehost base address.
pwruser define power control configuration
void SD_PowerOffCard ( SDMMCHOST_TYPE *  base,
const sdmmchost_pwr_card_t pwr 
)

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

Deprecated:
Do not use this function. It has been superceded by SD_SetCardPower.
Parameters
basehost base address.
pwruser define power control configuration
void SD_SetCardPower ( sd_card_t card,
bool  enable 
)

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

Parameters
cardcard descriptor.
enabletrue is power on, false is power off.
status_t SD_WaitCardDetectStatus ( SDMMCHOST_TYPE *  hostBase,
const sdmmchost_detect_card_t *  cd,
bool  waitCardStatus 
)

Detect card through GPIO, CD, DATA3.

Deprecated:
Do not use this function. It has been superceded by SD_PollingCardInsert.
Parameters
hostBasehost base address.
cdcard detect configuration
waitCardStatuswait card detect status
status_t SD_PollingCardInsert ( sd_card_t card,
uint32_t  status 
)

Detect card through GPIO, CD, DATA3.

Parameters
cardcard descriptor.
statusdetect status, kSD_Inserted or kSD_Removed.
bool SD_IsCardPresent ( sd_card_t card)
Parameters
cardcard descriptor.
bool SD_CheckReadOnly ( sd_card_t card)

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

Parameters
cardThe specific card.
Return values
trueCard is read only.
falseCard isn't read only.
status_t SD_SelectCard ( sd_card_t card,
bool  isSelected 
)
Parameters
cardCard descriptor.
isSelectedTrue to set the card into transfer state, false to disselect.
Return values
kStatus_SDMMC_TransferFailedTransfer failed.
kStatus_SuccessOperate successfully.
status_t SD_ReadStatus ( sd_card_t card)
Parameters
cardCard descriptor.
Return values
kStatus_SDMMC_TransferFailedTransfer failed.
kStatus_SDMMC_SendApplicationCommandFailedsend application command failed.
kStatus_SuccessOperate 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.

Parameters
cardCard descriptor.
bufferThe buffer to save the data read from card.
startBlockThe start block index.
blockCountThe number of blocks to read.
Return values
kStatus_InvalidArgumentInvalid argument.
kStatus_SDMMC_CardNotSupportCard not support.
kStatus_SDMMC_NotSupportYetNot support now.
kStatus_SDMMC_WaitWriteCompleteFailedSend status failed.
kStatus_SDMMC_TransferFailedTransfer failed.
kStatus_SDMMC_StopTransmissionFailedStop transmission failed.
kStatus_SuccessOperate 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.

Parameters
cardCard descriptor.
bufferThe buffer holding the data to be written to the card.
startBlockThe start block index.
blockCountThe number of blocks to write.
Return values
kStatus_InvalidArgumentInvalid argument.
kStatus_SDMMC_NotSupportYetNot support now.
kStatus_SDMMC_CardNotSupportCard not support.
kStatus_SDMMC_WaitWriteCompleteFailedSend status failed.
kStatus_SDMMC_TransferFailedTransfer failed.
kStatus_SDMMC_StopTransmissionFailedStop transmission failed.
kStatus_SuccessOperate 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.

Parameters
cardCard descriptor.
startBlockThe start block index.
blockCountThe number of blocks to erase.
Return values
kStatus_InvalidArgumentInvalid argument.
kStatus_SDMMC_WaitWriteCompleteFailedSend status failed.
kStatus_SDMMC_TransferFailedTransfer failed.
kStatus_SDMMC_WaitWriteCompleteFailedSend status failed.
kStatus_SuccessOperate successfully.
status_t SD_SetDriverStrength ( sd_card_t card,
sd_driver_strength_t  driverStrength 
)
Parameters
cardCard descriptor.
driverStrengthDriver strength
status_t SD_SetMaxCurrent ( sd_card_t card,
sd_max_current_t  maxCurrent 
)
Parameters
cardCard descriptor.
maxCurrentMax current