SD 主机

支持的芯片[ RTL8730E ][ RTL8721F ][RTL8735C]

概述

SD Host 提供了访问 SD 卡、MMC 卡和 SDIO 卡的硬件通信接口，实现数据存储和设备扩展功能。其主要特性包括：

  • 协议支持: SD Host 支持 SD 协议、MMC 协议和 SDIO 协议，具有高度兼容性。

  • 数据宽度: 支持 1-bit 和 4-bit 数据总线宽度，能够适应不同的传输速率需求。

  • 高速操作: 支持标准模式和高速模式，数据传输最高可达 50MHz。

  • 块传输：支持单块传输和多块传输，最大化利用总线带宽。

  • 支持 DMA: 通过模块内部的 DMA 控制器，自动搬移数据以降低 CPU 占用。

  • SDIO 扩展：支持无线通信模块、蓝牙模块等 SDIO 设备的连接，增强系统功能。

RTL8730E:

备注

暂不支持与 SDIO 卡通信。

上层应用

SD Host 为虚拟文件系统（VFS）应用和 USB 大容量存储设备(MSC)应用提供底层支持。

VFS

VFS 提供与多种底层文件系统交互的便捷接口，用于多平台开发。

基于 SD Host 的 VFS 应用的层级架构和主要相关驱动如图所示：

../../_images/vfs_fatfs_sdh.svg

基于 SD Host 的 VFS 架构

用户可以参考 SD 卡中的 VFS ，了解 VFS 如何基于 SD Host 在 SD 卡或 MMC 卡上实现文件级操作。

备注

VFS 当前最高支持 32GByte 的 SD 卡或 MMC 卡。

USB MSC

USB MSC 应用将连接到 SD Host 接口的设备作为 USB 存储设备连接至计算机，提高数据管理的灵活性。

更多详细信息请参考 存储设备方案 。

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.

返回:

SD operation result:

  • SD_OK: Success.

  • Others: Failure.

SD_RESULT SD_Init(void)

Initialize the SD host controller and connected device.

返回:

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.

参数:

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

返回:

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.

返回:

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.

参数:

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

返回:

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.

参数:

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

返回:

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.

参数:

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

参数:

  • NewState -- ENABLE or DISABLE.

备注

Only insertion debounce is implemented.

u32 SDIOH_DebounceGet(void)

Get the card-detect debounce count value.

返回:

Debounce count value (unit: 1 ms).

void SDIOH_DebounceSet(u32 debouncevalue)

Set the card-detect debounce count.

参数:

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

u8 SDIOH_GetBusWidth(void)

Get SD host bus width.

返回:

Bus width:

  • 0: 1-bit bus.

  • 1: 4-bit bus.

u32 SDIOH_GetISR(void)

Get SD host interrupt status.

返回:

SD host interrupt status.

u8 SDIOH_GetResponse(u8 byte_index)

Get a byte from the SD host command response register.

参数:

  • byte_index -- Index of the response byte to read.

返回:

The value of the specified response byte.

void SDIOH_INTClearPendingBit(u8 SDIO_IT)

Clear SD host pending interrupt status.

参数:

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

参数:

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

参数:

  • 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

返回:

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.

参数:

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

  • timeout_us -- Timeout value in microseconds.

返回:

HAL operation result:

  • HAL_OK: Command sent successfully.

  • Others: Error occurred.

void SDIOH_SetBusWidth(u8 width)

Set SD host bus width.

参数:

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

参数:

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

备注

Only SD 2.0 mode (SDIOH_SD20_MODE) is supported.

u32 SDIOH_WaitDMADone(u32 timeout_us)

Wait some time for SD host DMA done.

参数:

  • timeout_us -- Timeout value in microseconds.

返回:

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.

参数:

  • timeout_us -- Timeout value in microseconds.

返回:

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.

参数:

  • speed -- Bus speed mode: SD_SPEED_DS or SD_SPEED_HS.

返回:

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.

参数:

  • StartBlock -- The start block to erase.

  • EndBlock -- The end block to erase.

返回:

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.

参数:

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

  • BlockIdx -- Index of the starting block to read.

返回:

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.

参数:

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

返回:

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.

参数:

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

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

返回:

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.

参数:

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

返回:

HAL operation result:

  • HAL_OK: Write data successfully.

  • Others: Fail to write data.

常见问题排查

文件系统初始化失败

现象

运行VFS示例出现 "File System Init Fail" 的提示

原因

  • SD卡或MMC卡未经过格式化

  • 格式化后的SD卡或MMC卡的关键扇区内容被破坏

解决方法

  • 建议使用操作系统自带的磁盘管理工具，确保将SD卡或MMC卡格式化为标准兼容的文件系统

  • 选择合适的 FATFS 支持的格式，建议格式化为 FAT32

备注

格式化将清空卡上的所有内容，因此在格式化之前，请备份您的重要数据。