Supported Chips

WHC Overview

In the WHC 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:

../../_images/fullmac_architecture.svg

WHC Architecture Advantages

  • Rich interface options: Establishes transmission channels between Host and Device via UART/SPI/SDIO/USB

  • Cross-platform compatibility: Supports Linux, FreeRTOS, and Zephyr as Host development environments

  • Linux platform adaptation: Compatible with Linux standard wpa_supplicant (WPA_STD) and cfg80211 wireless frameworks, supporting enhanced features:

    • SME mode (with wpa_supplicant handling Wi-Fi MLME) or non-SME mode

    • Support for P2P/NAN

Fat Host and Slim Host

Based on whether wpa_supplicant runs on the Host side, WHC is categorized into two architectures: Fat Host and Slim Host. The Linux cfg80211 architecture belongs to the Fat Host category:

WHC Configuration Options

  • Selectable WPA_SUPPLICANT:

    • WPA_LITE: Optimized wpa_supplicant with reduced code size and memory footprint, implementing basic connectivity

    • WPA_STD: Standard Linux wpa_supplicant providing advanced features including P2P/NAN/SME

  • Selectable WPA_SUPPLICANT OFFLOAD:

    • WPA_SUPPLICANT can run either on Host side (e.g., Linux cfg80211) or on Device side

    • Running on Device side avoids porting wpa_supplicant to non-Linux host platforms, accelerating project timelines

  • Optional Dual TCPIP

    • Simultaneous operation of LWIP on Device and TCP/IP stack on Host

    • Device-side LWIP maintains keep-alive mechanisms, reducing Host wake-ups - ideal for battery-powered applications like IP cameras

    • Device-side LWIP protocol stack assists Host with packet processing, enabling traffic pre-filtering

WHC Operating Modes

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

Note

Abbreviations Introduction

  • S1 represents the Realtek-optimized wpa_supplicant: WPA_LITE

    • S1D indicates: wpa_supplicant using WPA_LITE and running on the Device side

  • S2 represents the standard wpa_supplicant: WPA_STD (supports advanced features like P2P/NAN)

    • S2H indicates: wpa_supplicant using WPA_STD and running on the Host side

  • T represents the Dual TCPIP protocol stack mode where TCPIP stacks run on both Host and Device sides

Note

MENU CONFIG

The above configuration options correspond to the following options in Menuconfig’s 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 Transmission Interface

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 File TREE

Wi-Fi

├─ 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 Hardware Configuration

Interface Connections

The pin connections between Ameba and Raspberry Pi are as follows:

Note

  • SPI DEV_TX_REQ: Ameba notifies Host of pending data transmission via rising edge on this pin

  • SPI DEV_READY: Ameba status indicator

    • High level (1): Device ready to receive data

    • Low level (0): Device busy (pause transmission)

Note

  • Default SDIO pins defined in Ameba SDK are used. If modification is required, adjust the SDIO_Pin_Grp parameter in the files below, which corresponds to the pinmux index in SDIO_PAD :

    file location： component/soc/usrcfg/amebadplus/ameba_intfcfg.c

  • Host-side SDIO interrupt requirements:

    • SDIO_DATA1 must be configured for SDIO function (not GPIO).

    • Switch to polling mode if Host doesn’t support SDIO interrupts.

SDIO Adapter Board

Realtek provides adapter board that enables convenient connection to mini SD card slots. It is recommended to use dedicated adapter boards for interfacing with SDIO pins.

../../_images/sdio_adapter_board.jpg

FullMAC SDIO adapter board (physical diagram)

Note

Realtek official adapter boards will be available soon. Currently request samples via <claire_wang@realsil.com.cn>.

Raspberry Pi Direct Connection

For high-speed scenarios, directly solder Ameba SDIO pins to Raspberry Pi GPIO.

../../_images/connection_with_raspberry_pi.jpg

Ameba-Raspberry Pi direct connection diagram

WHC CONTROL APP

The Ameba SDK includes a Control Application to enable serial port-based device control with the following technical specifications:

  • Functional Purpose：Strictly for demonstration purposes, command interaction prototyping

  • Architecture Design：Standalone utility，non-integrated with production modules

  • Customization Capability：Supports code-level customization and functional extensions

Application Architecture

The application supports bidirectional communication between User Space and Kernel Space through two command types:

  1. Kernel-Level Configuration

    • setmac：Configure device MAC address

    • netifon：Activate network interface carrier

  2. Device-Level Control

    • getmac: Retrieve device MAC address

    • getip: Retrieve device IP configuration

    • setrdy: Notify device that host is ready and instruct device to acquire PMU_FULLMAC_WIFI lock

    • unrdy: Notify device that host is not ready and release device’s PMU_FULLMAC_WIFI lock

    • tickps: Tickless Power Save command

    • wifion: Notify device to initialize WiFi

The communication architecture is shown below：

../../_images/fullmac_crtlapp_control_flow.svg

Supported Commands

Command Format

Description

init

Initialize kernel Netlink communication channel

getmac <device_idx>

Retrieve specified device MAC address

device_idx: Device port index (0 or 1 only)

  • 0: Corresponds to eth_sta0 (STA on device)

  • 1: Corresponds to eth_sta1 (SoftAP on device)

getip <device_idx>

Retrieve device network layer configuration

device_idx: Device port index (same as getmac)

setrdy

Notify device host is ready and instruct acquisition of PMU_WHC_WIFI lock

unrdy

Notify device host is not ready and release device’s PMU_WHC_WIFI lock

setmac <device_idx> <mac>

Configure interface hardware address

  • device_idx: Device port index (same as getmac)

  • mac: MAC format (xx:xx:xx:xx:xx:xx)

netifon <device_idx>

Activate physical layer carrier

device_idx: Device port index (same as getmac)

tickps <subtype>

Tickless Power Save command

subtype: Tickless Power Save command type

  • cg: Set device sleep mode to clock gating

  • pg: Set device sleep mode to power gating

  • r: Release device’s PMU_OS wakelock

wifion

Notify device to initialize WiFi

connect <ssid> <pw>

Notify device to connect

  • ssid: Target AP’s SSID

  • pw: Target AP’s password (defaults to open AP if not specified)

dhcp

Notify device for IP negotiation

Compilation and Execution

# Enter module directory
cd ${SDK}/component/wifi/whc/whc_host_linux/app

# Compile executable
make

# Run with privileged mode
sudo ./whc_ctrl_app

WHC Wi-Fi Porting Guide

Device Driver Porting

  1. In the directory {SDK}/amebadxxx_gcc_project, execute ./menuconfig.py.

    1. Find CONFIG WHC INTF > WHC MODE and select FULLMAC_DEV.

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

    1. Find CONFIG WHC INTF > HW INTERFACE and select the desired interface, such as WHC_INTF_SDIO.

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

    1. Find CONFIG WHC INTF > FULLMAC CONFIG and select the desired module.

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

    1. If you want to enable Wi-Fi NAN or Wi-Fi P2P, locate CONFIG WIFI > ENABLE WIFI > CONFIG WIFI MODE, and select the desired feature:

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

  2. Execute ./build.py to generate km4_boot_all.bin and km0_km4_app.bin .

  3. Use the image tool to download the firmware to the development board.

Host Driver Porting

User Guide for Ameba as FullMAC Host

  1. Environment Setup

    Execute the configuration tool in the directory {SDK}/amebadplus_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. Firmware Compilation

    Generate target files:

    ./build.py

    Output files:

    • km4_boot_all.bin

    • km0_km4_app.bin

  3. Firmware Burning

    Use the dedicated burning tool to write the firmware to the development board

Third-party Platform Porting

When using other Host chips, the component/os/freertos directory must be ported to the target system.

WHC Demonstration

  1. Initial Configuration

  1. Run the Control Application

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

  1. Execute initialization sequence in Control App

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

  1. Connect to Wireless Network

  1. Perform WiFi scan in control app

> scan

  1. Establish wireless connection in control app

> netifon 0
> connect ap_test 12345678

Note

ap_test represents the target AP’s SSID, 12345678 is the target AP’s password. Omit password parameter for open networks.

  1. Configure network interface in a new terminal

> dhcpcd wlanX

Note

wlanX is the interface device name. Confirm actual interface name (e.g., wlan0/wlan1) using ifconfig -a

  1. Network Testing

    ping 192.168.x.x

WHC Low Power Management

Device Side Operations

  1. Configure low-power mode: AT+TICKPS=TYPE,CG .

Host Side Operations

  1. Identify wireless physical interface(find “phy” field): rfkill list .

  2. Enable any-packet wakeup: sudo iw phy <phyname> wowlan enable any (replace actual phyname).

  3. Verify WoWLAN configuration: sudo iw phy wowlan show .

  4. Initiate system suspend echo mem | sudo tee /sys/power/state .

Note

phyname may change to phy1/phyN after rmmod, Re-validate steps 1-3 after module reload.

WHC API

Header Files

whc_host_linux/common/whc_host_cmd_path_api.h

whc_host_linux/app/whc_host_app_api.h

Interface Definitions

int whc_host_buf_rx_to_user(u8 *buf, u16 size);

Item

Description

Function Function

Processes device-to-host packet transmission, default forwards to user space

Parameters

buf: Packet buffer pointer, size: Valid packet length (bytes)

Return

0 indicates success, non-zero for error codes

Note

This is a weak symbol interface in RTK SDK, recommended to override per use case.

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

Item

Description

Function

Kernel-space to device packet transmission interface

Parameters

pbuf: Tx buffer, len: Valid data length with_txdesc: 1 indicates buffer contains TX descriptor header

Return

void

 
int whc_host_api_send_nl_data(uint8_t *buf, uint32_t buf_len);

Item

Description

Function

User-space to device Netlink data transmission interface

Parameters

buf: Structured data buffer, buf_len: Data length

Return

0 indicates success, non-zero for error codes

WHC Wi-Fi Throughput

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] 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

WHC Memory Footprint

Device

Example with Wi-Fi running on KM0:

Item

KM0

KM4

txt

270KB

31KB

rodata

51KB

9KB

data+bss

17KB

4KB

heap

~68KB

~2.5KB

Host

Host

Item

whc

SPI

txt

4.8KB

bss

~3.5KB

heap

~5KB

WHC Bluetooth

WHC Bluetooth File TREE

WHC Bluetooth Porting Guide

Device Driver Porting

Host Driver Porting