WHC Overview

Supported ICs[ RTL8721Dx ][...][ RTL8720E ][ RTL8710E ][ RTL8726E ][ RTL8713E ]

WHC Transmission Interface

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713E

LinuxFreeRTOSZephyr

	Wi-Fi	BT
SDIO	Y	Y
SPI	Y	Y
USB	Y	Y
UART	X	Y
Mix Mode	SDIO/SPI/USB	SDIO/SPI/UART

WHC Introduction

WHC Architecture

In the WHC(Wi-Fi Host Control) solution, Ameba functions as a network card connected to the host MCU via UART/SPI/SDIO/USB, providing network connectivity capabilities to the Host. The architecture diagram of WHC is shown below:

WHC Architecture Advantages

• Multi-Protocol Hardware Interface Support: Supports UART, SPI, SDIO, USB, and other physical layer interfaces to meet bandwidth and real-time requirements across diverse scenarios.

• Cross-Platform Development Compatibility: Compatible with Linux, FreeRTOS, and Zephyr as Host development platforms, significantly reducing porting efforts.

• Deep Linux Platform Integration: Natively compatible with Linux standard wireless frameworks: wpa_supplicant (WPA_STD) and cfg80211，enhanced functionalities include:

  • SME mode (MLME implemented via wpa_supplicant) or non-SME mode

  • Support for P2P/NAN

WHC Wi-Fi Architecture

WPAoH and WPAoD

According to the location of wpa_supplicant, WHC is categorized into two architectures: WPAoH (wpa_supplicant on Host) and WPAoD (wpa_supplicant on Device)(Linux Host running cfg80211 belongs to the WPAoH architecture):

WPAoHWPAoD

• API_PATH

  • Definition: Standardized communication interface between the Device-Side Driver and Host wpa_supplicant.

  • Usage: Activated only when the Host runs wpa_supplicant; primarily for internal SDK calls.

  • Configuration: Requires manual enablement via Menuconfig (follow SDK guidelines).

• CMD_PATH

  • Definition: Non-standard API data transmission channel between Host and Device (based on a private protocol).

  • Usage: Most CMD_PATH APIs are reserved for internal SDK use.

  • Configuration: Enabled by default in all modes, no user intervention needed.

• CUST_PATH

  • Definition: Extends CMD_PATH to provide custom APIs for arbitrary Host-Device data transfer, termed CUST_PATH.

  • Core Feature 1：Generic Data Transfer, supports arbitrary data exchange between Host and Device.

  • Core Feature 2：In WPAoD Mode, replaces standard Wi-Fi APIs (unavailable for WPAoD Mode Host) with CUST_PATH for all Wi-Fi control.

  • Configuration: Enabled by default; no additional setup required.

  • Reference： CUST_PATH

WHC Device-Side TCP/IP Keep-Alive

Both WPAoH and WPAoD can run the TCP/IP stack on the Device-side:

• Device-side LWIP and Host-side TCP/IP stack run in parallel. Device-side LWIP handles keep-alive mechanisms, significantly reducing Host wake-ups (e.g., boosts battery life in IP Camera scenarios).

• Device-side LWIP pre-processes packets, enabling Host traffic optimization.

WHC Wi-Fi Configuration Options and Operating Modes

Linux HostFreeRTOS HostZephyr Host

MENU CONFIG	WPAoD	WPAoH (cfg80211 Host)
WHC SUPPLICANT OFFLOAD	Y	N
WHC DEV TCPIP KEEPALIVE	O	O
WHC WIFI API PATH	N	Y
WHC CMD PATH	Y	Y
Status	Ready	Ready

• WPAoH or WPAoD Mode is controlled by Support WHC SUPPLICANT OFFLOAD

• Optional TCP/IP keep-alive on the Device-side

Note

In WPAoD Mode, Device-side wpa_supplicant uses WPA_LITE:

• WPA_LITE: A lightweight wpa_supplicant implementation optimized for Realtek chips, featuring minimal code size and memory usage while supporting basic connectivity

• WPA_STD: The standard Linux wpa_supplicant with full feature support, including advanced functionalities like P2P/NAN/SME

Note

MENU CONFIG

The above configuration options correspond to the following Menuconfig navigation path CONFIG WHC ITNF > FULLMAC CONFIG :

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

WHC Wi-Fi File Tree

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 Wi-Fi Driver Components and Porting

Device-Side Driver

• Reference: Device-Side Driver

Host-Side Driver

• Reference: WPAoD Host-Side Driver / WPAoH Host-Side Driver

CUST_PATH

• WPAoH Mode: If custom communication between Host and Device is needed beyond standard Wi-Fi/BT/Socket programming, use CUST_PATH.

• WPAoD Mode: Standard Wi-Fi APIs are unavailable; CUST_PATH must be used.

• Please reference CUST_PATH .

WHC Wi-Fi Throughput

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713E

Linux HostRTOS Host

Interface	Wi-Fi driver location	Item	WPAoD	WPAoH
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] The data is the test result of device code running in Flash, host：Raspberry Pi 5 Model B Rev 1.1，root: Linux raspberrypi 6.6.31+rpt-rpi-2712

• [2] The data is the test result of device code running in Flash, host：Raspberry Pi 5 Model B Rev 1.0，root: Linux raspberrypi 6.6.31+rpt-rpi-2712