SD Host

Supported ICs[ RTL8730E ][ RTL8721F ][RTL8735C]

Introduction

SD Host provides a hardware communication interface to access SD cards, MMC cards, and SDIO cards, implementing data storage and device expansion features.

Characteristics of SD Host are as follows:

  • Protocol support: Supports SD, MMC, and SDIO protocols, offering high compatibility.

  • Data width: Supports both 1-bit and 4-bit data bus width, accommodating different transmission rate requirements.

  • High-speed operation: Supports both default mode and high-speed mode, with data transfer clock up to 50MHz.

  • Block transfer: Supports both single block and multiple block transfers, making best of bus bandwidth.

  • DMA support: Realizes data transfer automatically with an internal DMA controller, reducing CPU load.

  • SDIO expansion: Supports access to SDIO devices, e.g. wireless communication modules and Bluetooth modules, enhancing system functionality.

RTL8730E:

Note

Communication with SDIO cards is currently not supported.

Application

SD Host provides basic support for Virtual File System (VFS) application and USB Mass Storage Class (MSC) application.

VFS

VFS provides a convenient interface for interacting with multiple underlying file systems, facilitating multi-platform development.

The hierarchical architecture and main related drivers of VFS application based on SD Host are shown in the figure:

../../_images/vfs_fatfs_sdh.svg

VFS Architecture Based on SD Host

Users can refer to VFS on SD card to learn how VFS performs file-level operations on SD cards or MMC cards based on SD Host.

Note

Memory capacity of SD cards or MMC cards supported in VFS is up to 32GByte.

USB MSC

Devices plugged into the SD Host slot by USB MSC, e.g. SD cards, are treated as an USB storage devices, which enhances the flexibility of data management.

For more details, please refer to Mass Storage Device Solution .

Raw API

SDHOST Exported Types

struct SDIOHCFG_TypeDef

SDHOST CFG Structure Definition.

Public Members

u8 sdioh_bus_speed

Specifies SD Host bus speed, which should be SD_SPEED_DS or SD_SPEED_HS.

u8 sdioh_bus_width

Specifies SD Host bus width, which should be a value of SDHOST Bus Width.

u32 sdioh_cd_pin

Specifies the card detect pin, which should be _PNC if not used, or an available GPIO pad.

u32 sdioh_wp_pin

Specifies the write protection pin, which should be _PNC if not used, or an available GPIO pad.

enum SD_RESULT

SD operation result type.

Values:

/* Operation completed successfully. */
SD_OK = 0

/* No SD card detected. */
SD_NODISK

/* SD card has been inserted. */
SD_INSERT

/* SD card initialization failed. */
SD_INITERR

/* SD card is write-protected. */
SD_PROTECTED

/* General SD operation error. */
SD_ERROR
RTL8730E:
struct SDIOH_CmdTypeDef

SDHOST Command Parameters Structure Definition.

Public Members

u32 arg

Specify the argument to be transfered with command.

u8 idx

Specify the command to be transfered.

u8 rsp_type

Specify the response type. Should be a value of SDHOST Card Response Classification.

u8 rsp_crc_chk

Specify CRC7 check enable or not. Should be ENABLE or DISABLE.

u8 data_present

Specify whether there is data transfer on the data line after getting response from the card. Should be a value of SDHOST Data Present

struct SDIOH_DmaCtl

SDHOST DMA Control Structure Definition.

Public Members

u32 start_addr

Specify the DMA start address. Unit: 8 Bytes.

u16 blk_cnt

Specify the DMA transfer length. Unit: 512 Bytes).

u8 op

Specify the data move direction. Should be a value of SDHOST DMA Operation.

u8 type

Specify the transfer type. Shold be a value of SDHOST DMA Transfer Type.

struct SDIOH_InitTypeDef

SDHOST Init Structure Definition.

Public Members

u8 SDIOH_idle_level

Indicate the idle pin level mask. When operate in 1-Bit bus width, this value is 0x03. When operate in 4-Bit bus width, this value is 0x1F.

enum SD_COMMAND

SD command index enumeration.

Values:

/* CMD0: Go Idle State. */
SD_CMD_GoIdleSte = 0

/* CMD1: Send operating condition (eMMC only). */
EMMC_CMD_SendOpCond = 1

/* CMD2: Send all CID numbers. */
SD_CMD_AllSendCid = 2

/* CMD3: Ask card to publish new RCA. */
SD_CMD_SendRelAddr = 3

/* CMD4: Set DSR register. */
SD_CMD_SetDsr = 4

/* CMD6: Check/switch card function. */
SD_CMD_SwitchFunc = 6

/* ACMD6: Set bus width. */
SD_CMD_SetBusWidth = 6

/* CMD7: Select/deselect card. */
SD_CMD_SelDeselCard = 7

/* CMD8: Send interface condition (SD only). */
SD_CMD_SendIfCond = 8

/* CMD8: Send extended CSD register (eMMC only). */
EMMC_CMD_SendExtCsd = 8

/* CMD9: Send card-specific data. */
SD_CMD_SendCsd = 9

/* CMD10: Send card identification. */
SD_CMD_SendCid = 10

/* CMD11: Switch signaling voltage to 1.8V (SD only). */
SD_CMD_VolSwitch = 11

/* CMD12: Stop transmission. */
SD_CMD_StopXsmission = 12

/* CMD13: Send card status. */
SD_CMD_SendSts = 13

/* CMD16: Set block length in bytes. */
SD_CMD_SetBlklen = 16

/* CMD17: Read single block. */
SD_CMD_RdSingleBlk = 17

/* CMD18: Read multiple blocks. */
SD_CMD_RdMulBlk = 18

/* CMD19: Send tuning block for sampling clock tuning (SD only). */
SD_CMD_SendTuningBlk = 19

/* ACMD22: Get the number of successfully written blocks. */
SD_CMD_SendNumWrBlks = 22

/* CMD23: Set block count for transfer. */
SD_CMD_SetBlkCnt = 23

/* ACMD23: Set number of write blocks to pre-erase before writing. */
SD_CMD_SetWrBlkEraseCnt = 23

/* CMD24: Write single block. */
SD_CMD_WrBlk = 24

/* CMD25: Write multiple blocks. */
SD_CMD_WrMulBlk = 25

/* CMD27: Program CSD register. */
SD_CMD_ProgCsd = 27

/* CMD32: Set first write block address to be erased (SD only). */
SD_CMD_EraseBlkSt = 32

/* CMD33: Set last write block address to be erased (SD only). */
SD_CMD_EraseBlkEd = 33

/* CMD35: Set first erase group start address (eMMC only). */
EMMC_CMD_EraseAddrSt = 35

/* CMD36: Set last erase group end address (eMMC only). */
EMMC_CMD_EraseAddrEd = 36

/* CMD38: Erase selected blocks. */
SD_CMD_Erase = 38

/* ACMD41: Send host capacity support and request card operating condition (SD only). */
SD_CMD_SdSendOpCond = 41

/* ACMD51: Read SD configuration register (SCR) (SD only). */
SD_CMD_SendScr = 51

/* CMD55: Indicate that the next command is an application-specific command (SD only). */
SD_CMD_AppCmd = 55
struct SD_CardInfo

SD CardInfo Structure Definition.

Public Members

u8 csd[SDIOH_CSD_LEN]

Store the card-specific data (CSD) of the current SD card.

u16 rca

Store the relative address (RCA) of the current SD card.

u8 is_sdhc_sdxc

Indicate whether the current card is SDSC (0) or SDHC/SDXC (1).

u8 sd_spec_ver

Specify the physical layer specification version of the current card, which would be a value of SD Specification Version

u32 capaticy

Specify the capacity of the current card. Unit: KB.

u32 read_bl_len

Specify max. read data block length of current card. Unit: byte.

u32 write_bl_len

Specify max. write data block length. Unit: byte.

u8 sig_level

Indicate the current signaling voltage level: 0 for 3.3V, 1 for 1.8V.

u8 bus_spd

Specify current bus speed, which would be a value of SD Access Mode.

SD_RESULT sd_status

Specify current SD status, which would be a value of SD_RESULT.

u8 dma_buf[SDIOH_C6R2_BUF_LEN]

DMA buffer, 32 byte-alignment.

SD Card State Type Definition

enum SD_CardStateTypeDef

SD card state machine states reported by the SD card.

Values:

/* SD card is in ready state. */
SD_CARD_READY = 0x00000001U

/* SD card is in identification state. */
SD_CARD_IDENTIFICATION = 0x00000002U

/* SD card is in standby state. */
SD_CARD_STANDBY = 0x00000003U

/* SD card is in data transfer state. */
SD_CARD_TRANSFER = 0x00000004U

/* SD card is in sending data state. */
SD_CARD_SENDING = 0x00000005U

/* SD card is in receiving data state. */
SD_CARD_RECEIVING = 0x00000006U

/* SD card is in programming state. */
SD_CARD_PROGRAMMING = 0x00000007U

/* SD card is in disconnected state. */
SD_CARD_DISCONNECTED = 0x00000008U

/* SD card error state indicator. */
SD_CARD_ERROR = 0x000000FFU

SD CID Register Structure Definition

RTL8730E:

Not supported.

SD CSD Register Structure Definition

RTL8730E:

Not supported.

SD State enumeration structure

RTL8730E:

Not supported.

SD Status Types

RTL8730E:

Not supported.

SDHOST Exported Constants

SDHOST Bus Width

/* 1-bit bus width. */
#define SDIOH_BUS_WIDTH_1BIT ((u8)0x00U)

/* 4-bit bus width. */
#define SDIOH_BUS_WIDTH_4BIT ((u8)0x01U)
RTL8730E:

Not supported.

SDHOST Card Response

/* Response register 0. */
#define SDIO_RESP0 ((u8)0x00U)
RTL8730E: 
/* Response register 1. */
#define SDIO_RESP1 ((u8)0x01U)

/* Response register 2. */
#define SDIO_RESP2 ((u8)0x02U)

/* Response register 3. */
#define SDIO_RESP3 ((u8)0x03U)

/* Response register 4. */
#define SDIO_RESP4 ((u8)0x04U)

/* Response register 5. */
#define SDIO_RESP5 ((u8)0x05U)

SDHOST DMA ALIGN ADDR

/* DMA buffer alignment size in bytes (8-byte alignment required by hardware). */
#define SDIOH_DMA_ALIGN_SZ (8)

SD Access Mode

/* Default speed mode, 3.3V signaling, up to 25 MHz (function 0). */
#define SD_SPEED_DS ((u8)0x00U)

/* High speed mode, 3.3V signaling, up to 50 MHz (function 1). */
#define SD_SPEED_HS ((u8)0x01U)

/* Keep current bus speed without switching. */
#define SD_KEEP_CUR_SPEED ((u8)0x0FU)
RTL8730E: 
/* SDR12 mode, 1.8V signaling, up to 25 MHz (function 0). */
#define SD_SPEED_SDR12 ((u8)0x02U)

/* SDR25 mode, 1.8V signaling, up to 50 MHz (function 1). */
#define SD_SPEED_SDR25 ((u8)0x03U)

/* SDR50 mode, 1.8V signaling, up to 100 MHz (function 2). */
#define SD_SPEED_SDR50 ((u8)0x04U)

/* SDR104 mode, 1.8V signaling, up to 208 MHz (function 3). */
#define SD_SPEED_SDR104 ((u8)0x05U)

/* DDR50 mode, 1.8V signaling, up to 50 MHz DDR (function 4). */
#define SD_SPEED_DDR50 ((u8)0x06U)

SD Block Size

/* Block size is 512 bytes by default. */
#define SD_BLOCK_SIZE (512)

/* Malloc size: 8 blocks. */
#define SD_MALLOC_BLK_CNT (8)

SD CMD6 Operation Mode

/* CMD6 check mode: query function support without switching. */
#define SD_CMD6_CHECK_MODE ((u8)0x00U)

/* CMD6 switch mode: switch to the selected function. */
#define SD_CMD6_SWITCH_MODE ((u8)0x01U)

SD Specification Version

/* SD physical layer specification version 1.01. */
#define SD_SPEC_V101 ((u8)0x0)

/* SD physical layer specification version 1.10. */
#define SD_SPEC_V110 ((u8)0x1)

/* SD physical layer specification version 2.00. */
#define SD_SPEC_V200 ((u8)0x2)

/* SD physical layer specification version 3.00. */
#define SD_SPEC_V300 ((u8)0x3)

SD RESP ACMD

RTL8730E: 
/* Status bit indicating an application command follows. */
#define SD_APP_CMD BIT(5)

SDIO RESP0 CMD

RTL8730E: 
/* Status bit indicating an address error. */
#define SD_ADDRESS_ERROR BIT(6)

/* Status bit indicating a block length error. */
#define SD_BLOCK_LEN_ERROR BIT(5)

/* Status bit indicating a write protection violation. */
#define SD_WP_VIOLATION BIT(2)

SDXC Power Control ACMD41

RTL8730E: 
/* Select power saving mode for SDXC ACMD41. */
#define SD_POWER_SAVING 0

/* Select maximum performance mode for SDXC ACMD41. */
#define SD_MAX_PERFORM 1

SD Switch 18 Request ACMD41

RTL8730E: 
/* Keep current voltage without switching. */
#define SD_USE_CUR_VOL 0

/* Request switch to 1.8V signaling via ACMD41. */
#define SD_SWITCH_18V 1

SD Capacity Support ACMD41

RTL8730E: 
/* Host supports SDSC cards only. */
#define SD_SUPPORT_SDSC_ONLY 0

/* Host supports SDHC and SDXC cards. */
#define SD_SUPPORT_SDHC_SDXC 1

SDHOST Work Mode

RTL8730E: 
/* Normal write transfer mode */
#define SDIOH_NORMAL_WRITE 0

/* Auto write mode 3 */
#define SDIOH_AUTO_WRITE3 1

/* Auto write mode 4 */
#define SDIOH_AUTO_WRITE4 2

/* Auto read mode 3 */
#define SDIOH_AUTO_READ3 5

/* Auto read mode 4 */
#define SDIOH_AUTO_READ4 6

/* Send command and get response mode */
#define SDIOH_SEND_CMD_GET_RSP 8

/* Auto write mode 1 */
#define SDIOH_AUTO_WRITE1 9

/* Auto write mode 2 */
#define SDIOH_AUTO_WRITE2 10

/* Normal read transfer mode */
#define SDIOH_NORMAL_READ 12

/* Auto read mode 1 */
#define SDIOH_AUTO_READ1 13

/* Auto read mode 2 */
#define SDIOH_AUTO_READ2 14

/* Tuning mode */
#define SDIOH_TUNING 15

SDHOST Card Response Type

RTL8730E: 
/* No response expected */
#define SDIOH_RESP_NONE 0

/* Response type R1 */
#define SDIOH_RESP_R1 1

/* Response type R2 */
#define SDIOH_RESP_R2 2

/* Response type R3 */
#define SDIOH_RESP_R3 3

/* Response type R6 */
#define SDIOH_RESP_R6 4

/* Response type R7 */
#define SDIOH_RESP_R7 5

SDHOST Card Response Classification

RTL8730E: 
/* No response classification */
#define SDIOH_NO_RESP 0

/* 6-byte response classification */
#define SDIOH_RSP_6B 1

/* 17-byte response classification */
#define SDIOH_RSP_17B 2

SDHOST Data Present

RTL8730E: 
/* No data present after command response */
#define SDIOH_NO_DATA 0

/* Data present after command response */
#define SDIOH_DATA_EXIST 1

SDHOST DMA Transfer Type

RTL8730E: 
/* Normal DMA transfer type */
#define SDIOH_DMA_NORMAL 0

/* 64-byte DMA transfer type */
#define SDIOH_DMA_64B 1

/* R2 response DMA transfer type */
#define SDIOH_DMA_R2 2

SDHOST Mode

RTL8730E: 
/* SD 2.0 compatible mode (Default Speed / High Speed, 3.3V signaling). */
#define SDIOH_SD20_MODE 0

/* DDR (double data rate) mode. */
#define SDIOH_DDR_MODE 1

/* UHS-I mode (SD 3.0 specification). */
#define SDIOH_SD30_MODE 2

SDHOST DMA Operation

RTL8730E: 
/* DMA write operation (host to card) */
#define SDIOH_DMA_WRITE 0

/* DMA read operation (card to host) */
#define SDIOH_DMA_READ 1

SDHOST Timeout Value

RTL8730E: 
/* Maximum timeout value when checking the command complete flag, unit: us. */
#define SDIOH_CMD_CPLT_TIMEOUT 5000

/* Maximum timeout value when checking the transfer complete flag, unit: us. */
#define SDIOH_XFER_CPLT_TIMEOUT 1000000

/* Read operation timeout value, unit: us. */
#define SDIOH_READ_TIMEOUT 100000

/* Write operation timeout value, unit: us. */
#define SDIOH_WRITE_TIMEOUT 250000

/* Erase operation timeout value, unit: us. */
#define SDIOH_ERASE_TIMEOUT 2000000

SDHOST CMD Value

RTL8730E: 
/* Transmission bit of SD_CMD0 register; set to 1 when the host is the transmitter. */
#define HOST_COMMAND BIT(6)

/* Command index mask of SD_CMD0 register. */
#define SDIOH_CMD_IDX_MASK 0x3F

/* VHS field value in CMD8 for the 2.7-3.6V voltage range. */
#define SDIOH_CMD8_VHS 0x1

/* Check pattern field value in CMD8. */
#define SDIOH_CMD8_CHK_PATN 0xAA

/* OCR field value in ACMD41 representing VDD voltage window bits [23:15]. */
#define SDIOH_OCR_VDD_WIN 0xFF8000

SDHOST Specific Data Length

RTL8730E: 
/* Buffer length for CMD6 status data and R2 responses, in bytes. */
#define SDIOH_C6R2_BUF_LEN 64

/* CSD register response length, in bytes */
#define SDIOH_CSD_LEN 16

SDHOST Signal Level

RTL8730E: 
/* Signal voltage level 3.3V */
#define SDIOH_SIG_VOL_33 0

/* Signal voltage level 1.8V */
#define SDIOH_SIG_VOL_18 1

SD Context Enumeration

RTL8730E:

Not supported.

SD Supported Card Type

RTL8730E:

Not supported.

SD Supported Version

RTL8730E:

Not supported.

SDIO CMD Argument

RTL8730E:

Not supported.

SDIO Device CCCR Register Offsets

RTL8730E:

Not supported.

SDIO Device CCCR Register Bit Definitions

RTL8730E:

Not supported.

SDHOST Error Codes

RTL8730E:

Not supported.

SDHOST Command Index

RTL8730E:

Not supported.

SDHOST R1 Error Masks

RTL8730E:

Not supported.

SDHOST R5 Error Masks

RTL8730E:

Not supported.

SDHOST R6 Error Masks

RTL8730E:

Not supported.

SDHOST ACMD41 Argument

RTL8730E:

Not supported.

SDHOST CMD8 Argument

RTL8730E:

Not supported.

SDHOST SCR Bitmasks

RTL8730E:

Not supported.

SDHOST CCC Bits

RTL8730E:

Not supported.

SDHOST Timeout Values

RTL8730E:

Not supported.

SDHOST Bitfield Masks

RTL8730E:

Not supported.

SDHOST Clock Frequency

RTL8730E:

Not supported.

SDHOST Command Type

RTL8730E:

Not supported.

SDHOST Response Type

RTL8730E:

Not supported.

SDHOST DPSM State

RTL8730E:

Not supported.

SDHOST Data Block Size

RTL8730E:

Not supported.

SDHOST Transfer Type

RTL8730E:

Not supported.

SDHOST Transfer Direction

RTL8730E:

Not supported.

SDHOST Transfer Control

RTL8730E:

Not supported.

SDHOST DMA Mode

RTL8730E:

Not supported.

SD CMD6 Func Group

RTL8730E:

Not supported.

SDIO Function Number

RTL8730E:

Not supported.

SDHOST Exported Functions

SD Initialization and De-initialization Functions

SD_RESULT SD_DeInit(void)

De-initialize the SD host controller and connected device.

Returns:

SD operation result:

  • SD_OK: Success.

  • Others: Failure.

SD_RESULT SD_Init(void)

Initialize the SD host controller and connected device.

Returns:

SD operation result:

  • SD_OK: Success.

  • Others: Failure.

RTL8730E:
void SD_CardInit(void)

Initialize the connected device.

SDHOST Functions

RTL8730E:
u32 SDIOH_Init(u8 BusBitMode)

Initialize the SD host controller and enable the SD clock.

Parameters:

  • BusBitMode – Bus width mode, which can be SDIOH_BUS_WIDTH_1BIT or SDIOH_BUS_WIDTH_4BIT.

Returns:

HAL operation result:

  • HAL_OK: SD host initialized successfully.

  • Others: SD host failed to initialize.

u32 SDIOH_Busy(void)

Check whether SD host is busy.

Returns:

HAL operation result:

  • HAL_OK: Not busy.

  • HAL_BUSY: Busy.

u32 SDIOH_CheckBusState(u8 status, u32 timeout_us)

Wait until the SD host bus transitions to the specified logic state within a given timeout.

Parameters:

  • status –

    SD host bus state, which can be 0 or 1:

    • 0: wait for bus to go low

    • 1: wait for bus to go high

  • timeout_us – Timeout value in microseconds.

Returns:

HAL operation result:

  • HAL_OK: Bus switched to specified state within timeout.

  • HAL_TIMEOUT: Timeout waiting for bus state.

u32 SDIOH_CheckTxError(u16 *status)

Check whether an error occurred during an SD host transfer.

Parameters:

  • status – Pointer to a 16-bit variable used to store the detailed error status.

Returns:

HAL operation result:

  • HAL_OK: No error occurred during transfer.

  • HAL_ERR_UNKNOWN: An error occurred during transfer.

void SDIOH_DMAConfig(SDIOH_DmaCtl *dma_ctl)

Set SD host DMA configuration.

Parameters:

  • dma_ctl – Pointer to an SDIOH_DmaCtl structure which contains the DMA configuration parameters.

void SDIOH_DMAReset(void)

Reset SD host DMA configuration.

void SDIOH_DeInit(void)

De-initialize SD host peripheral.

void SDIOH_DebounceCmd(u8 NewState)

Enable or disable the card-detect debounce function.

Parameters:

  • NewState – ENABLE or DISABLE.

Note

Only insertion debounce is implemented.

u32 SDIOH_DebounceGet(void)

Get the card-detect debounce count value.

Returns:

Debounce count value (unit: 1 ms).

void SDIOH_DebounceSet(u32 debouncevalue)

Set the card-detect debounce count.

Parameters:

  • debouncevalue – Debounce count value (unit: 1 ms).

u8 SDIOH_GetBusWidth(void)

Get SD host bus width.

Returns:

Bus width:

  • 0: 1-bit bus.

  • 1: 4-bit bus.

u32 SDIOH_GetISR(void)

Get SD host interrupt status.

Returns:

SD host interrupt status.

u8 SDIOH_GetResponse(u8 byte_index)

Get a byte from the SD host command response register.

Parameters:

  • byte_index – Index of the response byte to read.

Returns:

The value of the specified response byte.

void SDIOH_INTClearPendingBit(u8 SDIO_IT)

Clear SD host pending interrupt status.

Parameters:

  • SDIO_IT –

    SD host interrupt pending bit, which can be one or combination of the following values:

    • SDIOH_DMA_TRANSFER_DONE

    • SDIOH_CARD_ERROR

    • SDIOH_CARD_END

void SDIOH_INTConfig(u8 SDIO_IT, u32 newState)

Configure SD host interrupt enable/disable.

Parameters:

  • SDIO_IT –

    SD host interrupt source, which can be one or combination of the following values:

    • SDIOH_DMA_CTL_INT_EN

    • SDIOH_CARD_ERR_INT_EN

    • SDIOH_CARD_END_INT_EN

  • newState – New state of the interrupt, which can be ENABLE or DISABLE.

u32 SDIOH_InitialModeCmd(u8 NewState, u8 Level)

Enable or disable SD host initialization (card identification) mode.

Parameters:

  • NewState – New state of the initialization mode, which can be ENABLE or DISABLE.

  • Level –

    Signal level, which can be one of the following values:

    • SDIOH_SIG_VOL_33

    • SDIOH_SIG_VOL_18

Returns:

HAL operation result:

  • HAL_OK: SD host configured successfully.

  • Others: SD host failed to configure.

void SDIOH_PreDMATrans(void)

Enable DMA completion interrupt and set semaphore wait flag before a DMA transfer.

u32 SDIOH_SendCommand(SDIOH_CmdTypeDef *cmd_attrib, u32 timeout_us)

Send a command to the SD card via SD host.

Parameters:

  • cmd_attrib – Pointer to an SDIOH_CmdTypeDef structure containing the command attributes.

  • timeout_us – Timeout value in microseconds.

Returns:

HAL operation result:

  • HAL_OK: Command sent successfully.

  • Others: Error occurred.

void SDIOH_SetBusWidth(u8 width)

Set SD host bus width.

Parameters:

  • width – Bus width to set, which can be SDIOH_BUS_WIDTH_1BIT or SDIOH_BUS_WIDTH_4BIT.

void SDIOH_SwitchSpeed(u8 clk_div, u8 mode)

Set the SD host clock divider and bus speed mode.

Parameters:

  • clk_div –

    Clock divider, which can be one of the following values:

    • SDIOH_CLK_DIV1: divide by 1

    • SDIOH_CLK_DIV2: divide by 2

    • SDIOH_CLK_DIV4: divide by 4

    • SDIOH_CLK_DIV8: divide by 8

  • mode – Bus speed mode, which can be SDIOH_SD20_MODE.

Note

Only SD 2.0 mode (SDIOH_SD20_MODE) is supported.

u32 SDIOH_WaitDMADone(u32 timeout_us)

Wait some time for SD host DMA done.

Parameters:

  • timeout_us – Timeout value in microseconds.

Returns:

HAL operation result:

  • HAL_OK: SD host DMA done within a specified time.

  • HAL_TIMEOUT: SD host DMA timeout.

u32 SDIOH_WaitTxDone(u32 timeout_us)

Wait for the SD host transfer to complete.

Parameters:

  • timeout_us – Timeout value in microseconds.

Returns:

HAL operation result:

  • HAL_OK: SD host TX completed within the specified timeout.

  • HAL_TIMEOUT: SD host TX timeout.

SDMMC Functions

RTL8730E:

Not supported.

SD Peripheral Control Functions

RTL8730E:
u32 SD_SwitchBusSpeed(u8 speed)

Switch the SD bus speed.

Parameters:

  • speed – Bus speed mode: SD_SPEED_DS or SD_SPEED_HS.

Returns:

HAL operation result:

  • HAL_OK: Switch speed successfully.

  • Others: Fail to switch speed.

SD Input and Output Operation Functions

RTL8730E:
u32 SD_Erase(uint32_t StartBlock, uint32_t EndBlock)

Erase data in the SD card.

Parameters:

  • StartBlock – The start block to erase.

  • EndBlock – The end block to erase.

Returns:

HAL operation result:

  • HAL_OK: Erase data successfully.

  • Others: Failed to erase data.

u32 SD_ReadBlock(uint8_t *readbuff, uint32_t BlockIdx)

Read one block from the SD card.

Parameters:

  • readbuff – Buffer to store the read data (must be 32-byte aligned).

  • BlockIdx – Index of the starting block to read.

Returns:

HAL operation result:

  • HAL_OK: Read data successfully.

  • Others: Fail to read data.

u32 SD_ReadMultiBlocks(uint8_t *readbuff, uint32_t BlockIdx, uint32_t NumberOfBlocks)

Read multiple blocks from the SD card.

Parameters:

  • readbuff – The buffer to read data blocks (must be 32-byte aligned).

  • BlockIdx – The index of the starting block to read.

  • NumberOfBlocks – The number of blocks to be read.

Returns:

HAL operation result:

  • HAL_OK: Read data successfully.

  • Others: Fail to read data.

u32 SD_WriteBlock(uint8_t *writebuff, uint32_t BlockIdx)

Write one block to the SD card.

Parameters:

  • writebuff – Buffer containing the data to write (must be 32-byte aligned).

  • BlockIdx – The index of the starting block to write.

Returns:

HAL operation result:

  • HAL_OK: Write data successfully.

  • Others: Fail to write data.

u32 SD_WriteMultiBlocks(uint8_t *writebuff, uint32_t BlockIdx, uint32_t NumberOfBlocks)

Write multiple blocks to the SD card.

Parameters:

  • writebuff – The buffer to write data blocks (must be 32-byte aligned).

  • BlockIdx – The index of the starting block to write.

  • NumberOfBlocks – The number of blocks to write.

Returns:

HAL operation result:

  • HAL_OK: Write data successfully.

  • Others: Fail to write data.

Troubleshooting

File System Init Fail

Phenomenon

Message “File System Init Fail” appears while running the VFS example.

Cause

  • The SD card or MMC card is not formatted.

  • The key sector contents of the formatted SD card or MMC card have been corrupted.

Solution

  • It is recommended to format the SD card or MMC card based on a standard file system.

  • Choose an appropriate format supported by FATFS, e.g. FAT32.

Note

Backup your important data before formatting for it will erase all the data on the cards.