SDIO

支持的芯片[ RTL8721Dx ][ RTL8721F ][ RTL8720F ]

概述

SDIO（Secure Digital Input Output）是一种基于 SD 卡协议的接口标准，方便与具有 SDIO Host 接口的设备建立高速连接。

目前 Realtek 提供 turnkey solution 可以将具有 SDIO Device 的 IC 虚拟成 Wi-Fi 网卡设备 或者 Wi-Fi/BT combo 设备。

功能特性

• 数据宽度：支持 1-bit 和 4-bit 数据总线宽度

• 传输速率：支持标准模式和高速模式，数据传输最高可达 50MHz

• 多功能扩展：SDIO 不仅可以用于存储，还可以扩展至其它功能模块

• 中断机制：SDIO 拉低 DAT1 产生中断通知 SD 主控

• 支持 DMA

• 协议支持：完全兼容 SDIO 卡协议 2.0

备注

想要了解多功能扩展的更多细节，请参考 多功能扩展 。

支持的数据位宽

SDIO 支持 1-bit 和 4-bit 模式，这两种模式在信号线数量和数据传输速率方面有所不同。

1-bit 模式

• 信号线：在 1-bit 模式下，SDIO 使用一条数据线（DAT0）进行数据传输，加上命令线（CMD）和时钟线（CLK）。

• 传输速率：由于只有一条数据线，传输速率相对较低，但该模式具有更简单的硬件接口和较低的功耗。

• 主要应用：适用于低成本、低速率的应用场景，或者在不需要高数据吞吐量的设备中。

4-bit 模式

• 信号线：在 4-bit 模式下，SDIO 使用四条数据线（DAT0 - DAT3）进行数据传输，同时包括命令线（CMD）和时钟线（CLK）。

• 传输速率：数据传输速率显著提高。

• 主要应用：适用于需要较高数据吞吐量的设备，如高速传输的无线模块、存储设备等。

备注

• 初始化完成后，SDIO 的总线位宽取决于 SD 主控端的操作。

• 如需修改总线位宽，请在 SD 主控端进行修改。

支持的速度模式

SDIO 支持 默认速度模式 和 高速模式 ，以满足不同设备和应用的需求。

默认速度模式

• 时钟频率：最高支持到 25 MHz。

• 应用场景：适用于基本数据传输需求的设备。

高速模式

• 时钟频率：最高支持到 50 MHz。

• 应用场景：适合需要较高数据传输率的应用，如无线通信模块。

备注

• 初始化完成后，当前 SDIO 默认工作在高速模式。

• 如果开发者需要初始化完成后，SDIO 工作在默认速度模式，请联系 Realtek.

多功能扩展

SDIO 具有灵活的应用扩展能力，同时支持多个设备功能，包括 WLAN 和 蓝牙 。

RTL8721DxRTL8721FRTL8720F

RTL8721Dx:

备注

仅支持 1 个功能模块，即 WLAN。

SDIO 架构

SDIO 接口的结构如下图所示：

RTL8721DxRTL8721FRTL8720F

RTL8721Dx:

引脚分组

SDIO 接口具有硬件灵活性，其功能引脚被划分为多个功能组。

不同型号的开发板可能会提供不同组的引脚，开发者可以根据硬件选择合适的引脚组。

引脚基本功能

• CLK：时钟输入引脚，用于数据同步。

• CMD：指令输入/响应输出引脚，用于发送命令/响应命令。

• DAT0-DAT3：数据引脚，支持 1-bit 和 4-bit 模式的数据传输。

引脚组划分

RTL8721DxRTL8721FRTL8720F

RTL8721Dx:

组号	CLK	CMD	DAT3	DAT2	DAT1	DAT0
0	PA16	PA15	PA14	PA13	PA18	PA17
1	PA29	PA28	PA27	PA26	PA31	PA30
2(默认)	PB9	PB8	PB7	PB6	PB14	PB13
3	PB19	PB18	PB17	PA12	PB21	PB20
4	PB26	PB25	PB24	PB23	PB28	PB27

备注

开发者可以修改 ameba_intfcfg.c 文件中的 SDIO_Pin_Grp 来选择不同的引脚组，具体请参考 ameba_intfcfg 。

WHC

Ameba 可以通过 SDIO 与主机 MCU 连接，实现 Wi-Fi 网卡功能。

更多详细信息请参考 Wi-Fi 网卡模式 。

应用示例

SDK 提供了 SDIO 设备进行回环测试的示例，帮助开发者了解和使用 SDIO 功能。

开发者可以通过运行该回环测试的示例，判断当前硬件环境是否正常。

示例代码包括 SDIO 设备示例代码和基于树莓派的 SD 主控示例代码。

SDIO 设备示例代码

示例 mbed_sdio_loopback_device 演示 在 SDIO 设备端进行回环测试。 其主要内容包括：

• 初始化 SDIO 接口及功能 1（WLAN 功能）

• 初始化回环测试的收发缓冲区

• 设置 SDIO 设备的中断处理函数，保证能够及时处理接收到的数据并发送数据。

SD 主控示例代码

示例 sdio_device_loopback_Raspberry 演示在树莓派上通过 SD 主控与 SDIO 设备进行收发通信。 其主要内容包括：

• 初始化树莓派上的 SD 主控

• 通过 SD 主控识别并初始化 SDIO 设备及功能 1

• 通过 SD 主控向 SDIO 设备的功能 1 连续发送数据

• 通过 SD 主控从 SDIO 设备的功能 1 连续接收数据

备注

• 想要了解更多测试细节，请查看示例路径下的 sdio_loopback_test_guide.pdf 。

• 如果开发者想要基于示例进行开发，请避免在 SDIO 中断例程关联的任务中占用太多时间，以免影响及时处理中断相关事件。

Raw API

SDIO Exported Types

RTL8721DxRTL8721F

RTL8721Dx:

struct SDIO_InitTypeDef

SDIO Init Structure Definition.

Public Members

u32 TXBD_BAR

Specifies TXBD base address

u32 TXBD_RING_SIZE

Specifies TXBD ring size, This parameter must be set to a value in the 0-0xFFFF range.

u32 TX_BUFFER_SIZE

Specifies TX buffer size, This parameter must be set to a value in the 0-0xFF range.

u32 RXBD_BAR

Specifies RXBD base address

u32 RXBD_RING_SIZE

Specifies RXBD ring size, This parameter must be set to a value in the 0-0xFFFF range.

u32 RXBD_FREE_TH

Specifies the threshold of free RX BD count to trigger interrupt.

SDIO Exported Constants

RTL8721DxRTL8721F

RTL8721Dx:

/* Check if the given device is a valid SDIO device. */
#define IS_SDIO_DEVICE ((x) == SDIO_WIFI)

SDIO EVENT Definitions

RTL8721DxRTL8721F

RTL8721Dx:

/* SDIO event: new RX packet ready */
#define SDIO_EVENT_RX_PKT_RDY (0x00000001 << 1)

/* SDIO event: enable periodic SDIO status dump */
#define SDIO_EVENT_DUMP (0x00000001 << 3)

/* SDIO event: request to exit the SDIO task */
#define SDIO_EVENT_EXIT (0x00000001 << 27)

/* SDIO event: SDIO MP task has stopped */
#define SDIO_EVENT_MP_STOPPED (0x00000001 << 28)

/* SDIO event: SDIO IRQ task has stopped */
#define SDIO_EVENT_IRQ_STOPPED (0x00000001 << 29)

/* SDIO event: SDIO TX task has stopped */
#define SDIO_EVENT_TX_STOPPED (0x00000001 << 30)

/* SDIO event: SDIO RX task has stopped */
#define SDIO_EVENT_RX_STOPPED (0x00000001 << 31)

SDIO Exported Functions

void SDIO_AbortRxReq(SDIO_TypeDef *SDIO)

Abort SDIO RX request.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

void SDIO_CPWM2_Set(SDIO_TypeDef *SDIO, u16 Val, u32 Newstate)

Set CPWM2 to host.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• Val -- CPWM2 message to be sent.

• Newstate -- New state of CPWM2, which can be ENABLE or DISABLE.

u32 SDIO_DMA_CTRL_Get(SDIO_TypeDef *SDIO)

Get AHB DMA control register value.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

AHB DMA control register value.

void SDIO_DMA_Reset(SDIO_TypeDef *SDIO)

Reset SDIO DMA.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

u32 SDIO_H2C_MSG_Get(SDIO_TypeDef *SDIO)

Get H2C message from host.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

H2C message value.

void SDIO_INTClear(SDIO_TypeDef *SDIO, u16 SDIO_INT)

Clear specified SDIO interrupt bit(s).

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• SDIO_INT -- Specified interrupt bit(s) to be cleared.

void SDIO_INTClearAll(SDIO_TypeDef *SDIO)

Clear all the SDIO interrupt bits.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

void SDIO_INTConfig(SDIO_TypeDef *SDIO, u16 IntMask, u32 NewState)

Enable or disable specified interrupt source(s).

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• IntMask -- Specifies the interrupt source(s) to configure; refer to SPDIO_CPU_INT_MASK definitions for the target SDIO instance.

• NewState -- Interrupt status, which can be ENABLE or DISABLE.

u16 SDIO_INTStatus(SDIO_TypeDef *SDIO)

Get SDIO interrupt status.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

Interrupt status.

void SDIO_Init(SDIO_TypeDef *SDIO, SDIO_InitTypeDef *SDIOInit_Struct)

Initialize the SDIO according to the specified parameters in SDIO_InitStruct.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• SDIOInit_Struct -- Pointer to an SDIO_InitTypeDef structure that contains the configuration information of the SDIO peripheral.

备注

Pinmux function and CCCR (if needed) should be configured before this function.

u8 SDIO_RPWM1_Get(SDIO_TypeDef *SDIO)

Get RPWM1 value from host.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

RPWM1 value.

u16 SDIO_RPWM2_Get(SDIO_TypeDef *SDIO)

Get RPWM2 value from host.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

RPWM2 value.

u16 SDIO_RXBD_RPTR_Get(SDIO_TypeDef *SDIO)

Get RXBD read pointer, which is updated by SDIO IP.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

RXBD read pointer.

void SDIO_RXBD_WPTR_Set(SDIO_TypeDef *SDIO, u16 Val)

Set RXBD write pointer, which is updated by CPU.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• Val -- RXBD write pointer.

void SDIO_RxReq(SDIO_TypeDef *SDIO)

Set SDIO RX request.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

void SDIO_SetReady(SDIO_TypeDef *SDIO, int ready)

Set SDIO ready bit to tell host if SDIO is ready.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• ready -- If SDIO is ready, which can be ENABLE or DISABLE.

void SDIO_StructInit(SDIO_InitTypeDef *SDIO_InitStruct)

Fill each SDIO_InitStruct member with its default value.

参数:

• SDIO_InitStruct -- Pointer to an SDIO_InitTypeDef structure which will be initialized.

RTL8721DxRTL8721F

RTL8721Dx:

void SDIO_CPWM1_Set(SDIO_TypeDef *SDIO, u8 Val)

Set CPWM1 to host.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• Val -- CPWM1 message to be sent.

u32 SDIO_TXBD_RPTR_Get(SDIO_TypeDef *SDIO)

Get TXBD read pointer.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

TXBD read pointer.

void SDIO_TXBD_RPTR_Set(SDIO_TypeDef *SDIO, u32 Val)

Set TXBD read pointer, which is updated by CPU.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

• Val -- TXBD read pointer.

u32 SDIO_TXBD_WPTR_Get(SDIO_TypeDef *SDIO)

Get TXBD write pointer, which is updated by SDIO IP.

参数:

• SDIO -- SDIO device, refer to IS_SDIO_DEVICE() for valid values.

返回:

TXBD write pointer.

Mbed API

MBED_SPDIO Exported Types

Structure Type

RTL8721DxRTL8721F

RTL8721Dx:

struct spdio_t

MBED SPDIO driver configuration and callback structure.

Public Members

SDIO_TypeDef *pSDIO

Pointer to SDIO hardware base address (SDIO_WIFI only).

void *priv

Reserved for internal use; not set by user.

u32 host_rx_bd_num

Number of host RX BDs for sending data to host; 2 BDs per packet, must be even.

u32 host_tx_bd_num

Number of host TX BDs for receiving data from host.

u32 device_rx_bufsz

RX buffer size: desired packet length + 24-byte SPDIO header; must be a multiple of 64.

struct spdio_buf_t *rx_buf

RX buffer array pre-allocated by user; total size = device_rx_bufsz * host_tx_bd_num.

char (*device_rx_done_cb)(void *priv, void *pbuf, u8 *pdata, u16 size, u8 type)

Callback function defined by user, called by SPDIO when one packet is received.

Parameters

• priv: Pointer to spdio_t structure which is used to initialize the SPDIO interface.

• pbuf: Pointer to spdio_buf_t structure which is the SPDIO receive buffer.

• pdata: Actual received packet payload.

• size: Actual payload length.

• type: Received packet type, which should be a value of spdio_rx_data_t.

Returns: RTK_SUCCESS or RTK_FAIL.

char (*device_tx_done_cb)(void *priv, void *pbuf)

Callback function defined by user, called by SPDIO when one packet is sent.

Parameters

• priv: Pointer to spdio_t structure which is used to initialize the SPDIO interface.

• pbuf: Pointer to spdio_buf_t structure which carries the transmit packet.

Returns: RTK_SUCCESS or RTK_FAIL.

char (*rpwm_cb)(void *priv, u16 value)

Callback function defined by user to respond to RPWM from host.

Parameters

• priv: Pointer to spdio_t structure which is used to initialize the SPDIO interface.

• value: RPWM2 value.

Returns: RTK_SUCCESS or RTK_FAIL.

struct spdio_buf_t

SPDIO buffer structure for TX and RX data transfer.

Public Members

void *priv

Private data from user.

u32 buf_allocated

Allocated address of the SPDIO buffer.

u16 size_allocated

Actual allocated size of the buffer.

u32 buf_addr

Physical address of the SPDIO buffer; must be 4-byte aligned.

u16 buf_size

Size of valid data in the buffer.

u8 type

Data type of the buffer payload; see spdio_rx_data_t and spdio_tx_data_t.

u8 reserved

Reserved.

Enumeration Type

RTL8721DxRTL8721F

RTL8721Dx:

enum spdio_rx_data_t

Data type identifiers for SPDIO receive buffers.

Values:

/* No data type. */
SPDIO_RX_DATA_NULL = 0x00

/* Ethernet packet received. */
SPDIO_RX_DATA_ETH = 0x83

/* AT command packet received. */
SPDIO_RX_DATA_ATCMD = 0x11

/* User-defined data type. */
SPDIO_RX_DATA_USER = 0x41

enum spdio_tx_data_t

Data type identifiers for SPDIO transmit buffers.

Values:

/* No data type. */
SPDIO_TX_DATA_NULL = 0x00

/* Ethernet packet sent. */
SPDIO_TX_DATA_ETH = 0x82

/* AT command response packet sent. */
SPDIO_TX_DATA_ATCMDRSP = 0x10

/* User-defined data type. */
SPDIO_TX_DATA_USER = 0x40

MBED_SPDIO Exported Constants

/* DMA alignment requirement in bytes for SPDIO buffers. */
#define SPDIO_DMA_ALIGN_4 4

/* Align RX buffer size x to the next multiple of 64 bytes. */
#define SPDIO_RX_BUFSZ_ALIGN ((((x-1)>>6)+1)<<6)

/* Size of the SPDIO receive descriptor in bytes. */
#define SPDIO_RXDESC_SZ 24

MBED_SPDIO Exported Functions

void spdio_deinit(struct spdio_t *obj)

Deinitialize the SPDIO interface.

参数:

• obj -- Pointer to a spdio_t structure which is already initialized.

void spdio_init(struct spdio_t *obj)

Initialize the SPDIO interface.

参数:

• obj --

  Pointer to a spdio_t structure which should be initialized by user, and which will be used to initialize the SPDIO interface.

  • obj->host_rx_bd_num: Number of host RX BDs for device-to-host transfer (must be even, 2 BDs per packet).

  • obj->host_tx_bd_num: Number of host TX BDs for host-to-device transfer.

  • obj->device_rx_bufsz: Device RX buffer size (must be a multiple of 64).

  • obj->rx_buf: Device RX buffer array pre-allocated by user.

void spdio_structinit(struct spdio_t *obj)

Fill spdio_t structure with default settings.

参数:

• obj -- Pointer to a spdio_t structure which will be filled with default settings.

void spdio_trigger_rx_handle(void)

Trigger SDIO to process a received packet when a free RX buffer is available.

RTL8721DxRTL8721F

RTL8721Dx:

s8 spdio_tx(struct spdio_t *obj, struct spdio_buf_t *pbuf)

Prepare RX buffer descriptor and notify the SD host.

参数:

• obj -- Pointer to an initialized spdio_t structure.

• pbuf -- Pointer to a spdio_buf_t structure which carries the payload.

返回:

RTK_SUCCESS or RTK_FAIL.