支持的芯片

• RTL8721Dx

• RTL8721F

WHC 概述

在 WHC 方案中，Ameba 作为网卡通过 UART/SPI/SDIO/USB 与主机 MCU 连接，为 Host 提供网络接入能力, WHC 的架构图如下所示：

WHC 架构优势

• 接口类型丰富：可通过 UART/SPI/SDIO/USB 在 Host 和 Device 间建立传输通道

• 跨平台兼容性: Linux、 FreeRTOS 以及 Zephyr 均可以作为 Host 进行开发

• 适配 Linux 平台，兼容 Linux 标准 wpa_supplicant(WPA_STD) 和 cfg80211 无线框架，支持如下增强功能：

  • SME(由 wpa_supplicant 做 Wi-Fi 的 MLME) 或非 SME 模式

  • 支持 P2P/NAN

Fat Host 与 Slim Host

根据 Host 端是否运行 wpa_supplicant 我们将 WHC 分为 Fat Host 与 Slim Host 两种架构， 而 Linux 的 cfg80211 属于 Fat Host 架构：

Slim HostFat Host

WHC 配置选项

• 可选择的 WPA_SUPPLIANT

  • WPA_LITE: 为 realtek 优化过的 wpa_supplicant, 通过更小的 code size 和内存占用, 实现最基本的连线功能

  • WPA_STD: 标准的 Linux wpa_supplicant, 除了基本的连线功能之外, 还提供 P2P/NAN/SME 等高级功能

• 可选择的 WPA_SUPPLIANT OFFLOAD:

  • WPA_SUPPLIANT 既可以跑在 Host 端(比如 linux cfg80211), 也可以跑在 Device 端

  • WPA_SUPPLIANT 跑在 Device 端, 对于非标准的 Linux 系统可以省去移植 wap_supplicant 到 host 平台的烦恼, 缩短项目周期

• 可选择的 Dual TCPIP

  • Device 端 LWIP 和 host 端 TCPIP stack 并行运行, Device 端 LWIP 用于提供必要的保活机制, 避免 Host 端被频繁唤醒, 在 IP Camera 等电池场景下大幅提升电池使用时间

  • Device 端的 LWIP 协议栈可以协助 Host 处理一些数据包交互，实现 Host 流量预过滤

WHC 典型模式

Linux HostFreeRTOS HostZephyr Host

	Abbreviation	wpa_supplicant	Dual TCPIP(T)	API PATH	CMD PATH	Status
slim host	S1D	WPA LITE in DEV	N	N	Y	Ready
	S1D-T	WPA LITE in DEV	Y	N	Y	Ready
fat host (cfg80211)	S2H	WPA STD in Host	N	Y	Y	Ready
	S2H-T	WPA STD in Host	Y	Y	Y	Ready
	S2H-SME	WPA STD in Host	N	Y	Y	Ongoing
	S2H-T-SME	WPA STD in Host	Y	Y	Y	Ongoing

备注

缩写词介绍

• S1 代表为 realtek 优化过的 wpa_supplicant: WPA_LITE

  • S1D 代表: wpa_supplicant 使用 WPA_LITE, 并且跑在 Device 端

• S2 代表标准的 wpa_supplicant: WPA_STD(支持 P2P/NAN 等高级功能)

  • S2H 代表: wpa_supplicant 使用 WPA_STD, 并且跑在 Host 端

• T 代表运行 Dual TCPIP 协议栈模式，Host 端和 Device 端都运行 TCPIP 协议栈

备注

MENU CONFIG

以上配置选项对应 Menuconfig 中 CONFIG WHC ITNF > FULLMAC CONFIG 下面的如下选项：

(Top) -> CONFIG WHC INTF -> FULLMAC config
----Configuration----
    (X) Support WHC CMD PATH
    ( ) Support WHC WIFI API PATH
    ( ) Support WHC SUPPLICANT OFFLOAD
    ( ) Support WHC DUAL TCPIP

WHC 传输接口

RTL8721DxRTL8721F

LinuxFreeRTOSZephyr

Interface	SDIO	SPI	USB	UART	SDIO (Wi-Fi) + UART (BT)	SPI (Wi-Fi) + UART (BT)	USB (Wi-Fi) + UART (BT)
Wi-Fi	Y	Y	Y	X	Y	Y	X
BT	Y	Y	X	X	Y	Y	X

WHC 文件目录

Wi-Fi

RTOS Host/DeviceLinux Host

├─ whc
│  ├─ README.md
│  ├─ CMakeLists.txt
│  ├─ whc_def.h
│  ├─ whc_dev
│  │  ├─ ipc
│  │  │  ├─ whc_ipc_dev_api.c
│  │  │  ├─ whc_ipc_dev_trx.c
│  │  │  ├─ whc_ipc_dev_trx.h
│  │  │  └─ whc_ipc_device.c
│  │  ├─ sdio
│  │  │  ├─ whc_sdio_dev.c
│  │  │  ├─ whc_sdio_dev.h
│  │  │  ├─ whc_sdio_drv.c
│  │  │  └─ whc_sdio_drv.h
│  │  ├─ spi
│  │  │  ├─ whc_spi_dev.c
│  │  │  ├─ whc_spi_dev.h
│  │  │  ├─ whc_spi_drv.c
│  │  │  └─ whc_spi_drv.h
│  │  ├─ usb
│  │  │  ├─ whc_usb_dev.c
│  │  │  └─ whc_usb_dev.h
│  │  ├─ whc_dev.h
│  │  ├─ whc_dev_api.c
│  │  ├─ whc_dev_api.h
│  │  ├─ whc_dev_api_path.c
│  │  ├─ whc_dev_api_path.h
│  │  ├─ whc_dev_app.c
│  │  ├─ whc_dev_cust_evt.c
│  │  ├─ whc_dev_cust_evt.h
│  │  ├─ whc_dev_msg_queue.c
│  │  ├─ whc_dev_msg_queue.h
│  │  ├─ whc_dev_protocal_offload.c
│  │  ├─ whc_dev_protocal_offload.h
│  │  ├─ whc_dev_tcpip.c
│  │  ├─ whc_dev_tcpip.h
│  │  ├─ whc_dev_trx.c
│  │  └─ whc_dev_trx.h
│  ├─ whc_host_rtos
│  │  ├─ ipc
│  │  │  ├─ whc_ipc_host.c
│  │  │  ├─ whc_ipc_host_api.c
│  │  │  ├─ whc_ipc_host_api.h
│  │  │  ├─ whc_ipc_host_api_basic.c
│  │  │  ├─ whc_ipc_host_api_ext.c
│  │  │  ├─ whc_ipc_host_trx.c
│  │  │  ├─ whc_ipc_host_trx.h
│  │  │  └─ whc_ipc_host_zephyr.c
│  │  ├─ spi
│  │  │  ├─ whc_spi_host.c
│  │  │  ├─ whc_spi_host.h
│  │  │  ├─ whc_spi_host_trx.c
│  │  │  └─ whc_spi_host_trx.h
│  │  ├─ sdio
│  │  │  ├─ rtw_sdio_drvio.c
│  │  │  ├─ rtw_sdio_drvio.h
│  │  │  ├─ whc_sdio_host.c
│  │  │  ├─ whc_sdio_host.h
│  │  │  ├─ whc_sdio_init.c
│  │  │  ├─ whc_sdio_host_trx.c
│  │  │  └─ whc_sdio_host_trx.h
│  │  ├─ whc_host.h
│  │  ├─ whc_host_api.c
│  │  ├─ whc_host_api.h
│  │  ├─ whc_host_api_basic.c
│  │  ├─ whc_host_api_ext.c
│  │  ├─ whc_host_app.c
│  │  ├─ whc_host_app.h
│  │  ├─ whc_host_init.c
│  │  ├─ whc_host_cust_evt.c
│  │  ├─ whc_host_cust_evt.h
│  │  └─ whc_rtos
│  │     ├─ os_wrapper_memory.c
│  │     ├─ os_wrapper_mutex.c
│  │     └─ os_wrapper_semaphore.c
│  ├─ whc_ipc.h
│  ├─ whc_ipc_cfg.h
│  ├─ whc_ipc_msg_queue.c
│  └─ whc_ipc_msg_queue.h

WHC 硬件配置

接口连接

Ameba 与树莓派引脚对应关系如下：

RTL8721DxRTL8721FRaspberry Pi

Interface	SoC pin	Function
SDIO	PB6	SDIO_DAT2
	PB7	SDIO_DAT3
	PB8	SDIO_CMD
	PB9	SDIO_CLK
	PB13	SDIO_DAT0
	PB14	SDIO_DAT1
SPI	PB24	SPI_MOSI
	PB25	SPI_MISO
	PB23	SPI_CLK
	PB26	SPI_CS
	PB8	DEV_TX_REQ
	PB9	DEV_READY

备注

• SPI DEV_TX_REQ：Ameba 通过此引脚上升沿通知 Host 有数据待发送

• SPI DEV_READY：Ameba 状态指示信号

  • 高电平（1）：设备就绪，可接收数据

  • 低电平（0）：设备繁忙，暂停传输

备注

• 默认使用 Ameba SDK 预定义 SDIO 引脚，如需修改需调整以下文件中 SDIO_Pin_Grp , 对应 SDIO_PAD 中的 pinmux 的索引：

  RTL8721DxRTL8721F

  文件地址： component/soc/usrcfg/amebadplus/ameba_intfcfg.c

• Host 端 SDIO 中断模式要求：

  • SDIO_DATA1 必须配置为 SDIO 功能（非 GPIO）。

  • 若 Host 不支持 SDIO 中断，可切换为轮询模式。

SDIO 转接板

Realtek 提供了方便对接 mini SD 卡槽的转接板供客户选择，推荐使用专用转接板连接 SDIO 引脚。

FullMAC SDIO 转接板实物图

备注

Realtek 官方转接板即将上市，当前可邮件联系 <claire_wang@realsil.com.cn> 申请样品。

树莓派直连方案

高速传输场景建议直接将 Ameba SDIO 引脚焊接至树莓派 GPIO。

Ameba 与树莓派直连示意图

WHC CONTROL APP

Ameba SDK 提供控制应用程序（Control App） 来实现通过串口对 device 的控制，该应用特性如下：

• 功能定位：纯演示用途，用于命令交互原型开发

• 架构设计：独立实用程序，不属于任何功能模块

• 定制化能力：支持客户深度扩展开发

LINUX HOSTRTOS HOST

APP 架构

APP 支援 USER Space 和 Kernel Space 的双向沟通，可以通过两类命令实现双向控制：

1. 内核级配置

   • setmac：配置设备 MAC 地址

   • netifon：激活网络接口载波

2. 设备级控制

   • getmac：获取设备 MAC 地址

   • getip：获取设备 IP 配置

   • setrdy：通知设备主机就绪且指示设备获取 PMU_FULLMAC_WIFI 锁

   • unrdy：通知设备主机未就绪且释放设备的 PMU_FULLMAC_WIFI 锁

   • tickps：Tickless Power Save 指令

   • wifion：通知设备进行 wifi init

其通信架构如下图所示：

APP 支持的命令

命令格式	功能描述
init	初始化内核 Netlink 通信通道
getmac <device_idx>	获取指定设备MAC地址 device_idx：设备端口索引，只能是 0 或 1 0：对应 eth_sta0（设备端的STA） 1：对应 eth_sta1（设备端的SoftAP）
getip <device_idx>	获取设备网络层配置 device_idx：设备端口索引，同 getmac 命令
setrdy	通知设备主机就绪且指示设备获取PMU_WHC_WIFI锁
unrdy	通知设备主机未就绪且释放设备的PMU_WHC_WIFI锁
setmac <device_idx> <mac>	配置接口硬件地址 device_idx：设备端口索引，同 getmac 命令 mac：MAC格式（xx:xx:xx:xx:xx:xx）
netifon <device_idx>	激活接口物理层载波 device_idx：设备端口索引，同 getmac 命令
tickps <subtype>	Tickless Power Save指令 subtype: ticklessPower Save指令类型 cg：设置设备的休眠类型为clock gating pg：设置设备的休眠类型为power gating r：释放设备的PMU_OS wakelock
wifion	通知设备初始化WIFI
connect <ssid> <pw>	通知设备连线 ssid：目标AP的ssid pw：目标AP的密码，默认为open AP如果没有输入
dhcp	通知设备进行IP协商

APP 的编译和执行

# 进入模块目录
cd ${SDK}/component/wifi/whc/whc_host_linux/app

# 编译可执行文件
make

# 以特权模式运行
sudo ./whc_ctrl_app

WHC Wi-Fi 移植指南

Device 驱动移植

1. 在目录 {SDK}/amebadxxx_gcc_project 中执行 ./menuconfig.py。

   1. 找到 CONFIG WHC ITNF > WHC MODE，选择 FULLMAC_DEV。

   (Top) -> CONFIG WHC INTF -> WHC_MODE
   ----Configuration----
       ( ) WHC_IPC
       (X) FULLMAC_DEV
       ( ) FULLMAC_HOST
   

   2. 找到 CONFIG WHC ITNF > HW INTERFACE，选择想要的接口，比如 WHC_INTF_SDIO。

   (Top) -> CONFIG WHC INTF -> HW INTERFACE
   ----Configuration----
       (X) WHC_INTF_SDIO
       ( ) WHC_INTF_USB
       ( ) WHC_INTF_SPI
   

   3. 找到 CONFIG WHC ITNF > FULLMAC CONFIG，选择想要的模块。

   (Top) -> CONFIG WHC INTF -> FULLMAC config
   ----Configuration----
       ( ) Support WHC CMD PATH
       ( ) Support WHC WIFI API PATH
       ( ) Support WHC SUPPLICANT OFFLOAD
       ( ) Support WHC DUAL TCPIP
   

   4. 若需要使能 Wi-Fi NAN 或 Wi-Fi P2P, 则找到 CONFIG WIFI > ENABLE WIFI > CONFIG WIFI MODE，选择需要的功能。

   (Top) -> CONFIG WIFI
   ----Configuration----
       (X)ENABLE WIFI --->
         CONFIG WIFI MODE --->
            (X) ENABLE NAN
            ( ) ENABLE P2P
   

2. 执行 ./build.py 生成 km4_boot_all.bin 和 km0_km4_app.bin。

3. 使用 image tool 下载固件到开发板。

Host 驱动移植

RTOSLinux

Ameba 作为 FullMAC Host 使用指南

1. 环境配置

   1. 在目录 {SDK}/amebaxxx_gcc_project 执行配置工具

   (Top) -> CONFIG WHC INTF -> WHC_MODE
   ----Configuration----
       ( ) WHC_IPC
       ( ) FULLMAC_DEV
       (X) FULLMAC_HOST
   
   (Top) -> CONFIG WHC INTF -> FULLMAC HOST config
   ----Configuration----
       (X) Support WHC CMD PATH
       (X) Support WHC WIFI API PATH
   

2. 固件编译

   生成目标文件：

   ./build.py
   

   输出文件：

   • km4_boot_all.bin

   • km0_km4_app.bin

3. 固件烧录

   使用专用烧录工具将固件写入开发板

第三方平台移植

使用其他 Host 芯片时，需将 component/os/freertos 目录移植至目标系统。

WHC Demo

LinuxRTOS

S1DS1D-TS2HS2H-T

1. 初始化配置

1. 运行控制应用程序

cd ${SDK}/component/wifi/whc/whc_host_linux/app
sudo ./whc_ctrl_app

2. 在 Control App 执行初始化序列

> init
> wifion
> getmac 0
00:0A:35:XX:XX:XX
> setmac 0 00:0A:35:11:22:33

2. 连接无线网络

1. 在 control app 执行 WiFi 扫描

> scan

2. 在 control app 建立无线连接

> netifon 0
> connect ap_test 12345678

备注

ap_test 为目标 AP 的 ssid，12345678 为目标 AP 的密码，开放网络可省略密码参数。

3. 新建终端，配置网络接口

> dhcpcd wlanX

备注

wlanX 为模式设备名，使用 ifconfig -a 确认实际接口名称 (如 wlan0/wlan1)

3. 网络测试

   ping 192.168.x.x
   

WHC 低功耗

Device 端操作

1. 执行 AT+TICKPS=TYPE,CG 来设置 device 的低功耗模式。

Host 端操作

1. 查询无线物理接口名称（观察输出中的 "phy" 字段）： rfkill list。

2. 启用任意数据包唤醒功能： sudo iw phy <phyname> wowlan enable any （需替换实际 phyname）。

3. 验证 WoWLAN 配置状态： sudo iw phy wowlan show。

4. 触发系统挂起（内存休眠状态） echo mem | sudo tee /sys/power/state 。

备注

执行 rmmod 后 phyname 可能变为 phy1/phyN，每次重启无线模块需重新执行步骤 1-3

WHC API

头文件

LINUX HOSTRTOS HOSTDEVICE

whc_host_linux/common/whc_host_cmd_path_api.h

whc_host_linux/app/whc_host_app_api.h

接口定义

LINUX HOSTRTOS HOSTDEVICE

int whc_host_buf_rx_to_user(u8 *buf, u16 size);

项目	描述
功能	处理设备到主机的数据包传输，默认实现将数据包转发至用户空间
参数	buf: 数据包缓冲区指针，size: 数据包有效长度（字节）
返回值	0表示成功，非零为错误码

备注

此为 RTK SDK 中的弱定义接口，建议用户根据实际场景重载实现。

void whc_host_send_data_to_dev(u8 *pbuf, u32 len, u32 with_txdesc);

项目	描述
功能	内核空间到设备的数据包传输接口
参数	pbuf: 发送数据缓冲区，len: 有效数据长度 ， with_txdesc: 1表示缓冲区已包含TX描述符头
返回值	无

int whc_host_api_send_nl_data(uint8_t *buf, uint32_t buf_len);

项目	描述
功能	用户空间到设备的Netlink数据传输接口
参数	buf: 结构化数据缓冲区，buf_len: 数据长度
返回值	0表示成功，非零为错误码

WHC Wi-Fi 吞吐量

RTL8721DxRTL8721F

Linux HostRtos Host

Interface	Wi-Fi driver location	Item	Slim Host	Fat Host
SDIO [1]	KM4 (334MHz)	TCP RX	49.7	53.5
		TCP TX	50.1	51.2
		UDP RX	58.9	59.6
		UDP TX	56.5	56.6
SPI [2]	KM4 (334MHz)	TCP RX	16.8	17.1
		TCP TX	17.4	17.7
		UDP RX	19.1	18.6
		UDP TX	18.9	18.4
USB [3]		TCP RX
		TCP TX
		UDP RX
		UDP TX

• [1] Device 代码运行在 Flash 中，主机：Raspberry Pi 5 Model B Rev 1.1，root: Linux raspberrypi 6.6.31+rpt-rpi-2712

• [2] Device 代码运行在 Flash 中，主机：Raspberry Pi 5 Model B Rev 1.0，root: Linux raspberrypi 6.6.31+rpt-rpi-2712

WHC 内存占用量

Device

RTL8721Dx

以 Wi-Fi 运行在 KM0 上为例：

项目	KM0	KM4
txt	270KB	31KB
rodata	51KB	9KB
data+bss	17KB	4KB
heap	~68KB	~2.5KB

Host

RTOSLinux

Host	Item	whc
SPI	txt	4.8KB
	bss	~3.5KB
	heap	~5KB

WHC BT

文件目录

DeviceRTOS HostLinux Host

WHC BT 移植指南

Device 驱动移植

Host 驱动移植

LinuxRTOS