Supported ICs

Ameba SoC	RTL8721Dx	RTL8726EA	RTL8720EA	RTL8730E
Supported	Y	N	N	N

WiFi Bridge Introduction

The following figure is the high-level block diagram for WiFi bridge solution.

WiFi bridge architecture

WiFi Bridge Interfaces

RTL8721Dx

Linux HOSTFreeRTOS HOSTZephyr HOST

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

WiFi Bridge Features

Features	Linux host	FreeRTOS host
Wi-Fi API	FreeRTOS Wi-Fi APIs	FreeRTOS Wi-Fi APIs
Wi-Fi mode	Station SoftAP	Station SoftAP
Wi-Fi security	Open WPA WPA2 WPA3	Open WPA WPA2 WPA3
Wowlan	Y	Y
Bluetooth features	BLE 5.0 BLE 5.2 Bluetooth 5.3	BLE 5.0 BLE 5.2 Bluetooth 5.3

WiFi Bridge File Architecture

RTOS HOST/DEVLinux HOST

├─ whc
│  ├─ README.md
│  ├─ 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_bridge_sdio_dev.c
│  │  │  ├─ whc_bridge_sdio_dev.h
│  │  │  ├─ whc_fullmac_sdio_dev.c
│  │  │  ├─ whc_fullmac_sdio_dev.h
│  │  │  ├─ whc_sdio_drv.c
│  │  │  └─ whc_sdio_drv.h
│  │  ├─ spi
│  │  │  ├─ whc_bridge_spi_dev.c
│  │  │  ├─ whc_bridge_spi_dev.h
│  │  │  ├─ whc_fullmac_spi_dev.c
│  │  │  ├─ whc_fullmac_spi_dev.h
│  │  │  ├─ whc_spi_dev.c
│  │  │  └─ whc_spi_dev.h
│  │  ├─ usb
│  │  │  ├─ whc_usb_dev.c
│  │  │  └─ whc_usb_dev.h
│  │  ├─ whc_bridge_dev_api.c
│  │  ├─ whc_bridge_dev_api.h
│  │  ├─ whc_dev.h
│  │  ├─ whc_dev_api.c
│  │  ├─ whc_dev_api.h
│  │  ├─ whc_dev_app.c
│  │  ├─ whc_dev_bridge.c
│  │  ├─ whc_dev_bridge.h
│  │  ├─ 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_struct.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
│  │  ├─ whc_host.h
│  │  ├─ whc_host_api.c
│  │  ├─ whc_host_api.h
│  │  ├─ whc_host_api_basic.c
│  │  ├─ whc_host_api_ext.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

WiFi Bridge Hardware Configuration

Interface Connections

Pin connections between Ameba and Raspberry Pi are as follows:

RTL8721DxRaspberry Pi

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

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. Modify pinmux configuration in SPDIO_Board_Init function at:

  RTL8721Dx

  component/soc/amebadplus/hal/src/spdio_api.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

To avoid signal interference from flying wires, use dedicated adapter board for SDIO connections:

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:

Ameba-Raspberry Pi Direct Connection Diagram

WiFi Bridge Device Porting Guide

1. Project Configuration

   Execute in project directory (example path: {SDK}/amebaxxx_gcc_project):

   ./menuconfig.py
   

   1. Navigate through menu path for bridge mode selection:

      Locate CONFIG_WHC_ITNF ‣ WHC Mode ‣ WHC_BRIDGE, and select the desired interface:

      SDIOSPI

      To select the WHC_INTF_SDIO.

      (Top) -> CONFIG WHC INTF
      ----Configuration----
          WHC MODE (WHC_BRIDGE)  --->
          HW INTERFACE (WHC_INTF_SDIO)  --->
      

2. Firmware Compilation

   Build the image with compile command:

   ./build.py
   

3. Image Flashing

   Flash the generated image to development board using programming tool.

WiFi Bridge Host Porting Guide

RTOSLinux EnvironmentRaspberry Pi

WiFi Bridge API

Linux HOSTRTOS DEVICE

API Documentation

# Kernel Layer APIs
whc_bridge_host_tx.c
whc_bridge_host_netlink.c

# User Space Layer APIs
whc_bridge_host_demo.c

whc_bridge_host_send_data_to_dev

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

Item	Description
Overview	Sends data from the kernel to the device
Parameters	pbuf: Address of the data buffer len: Length of the data with_txdesc: Whether the buffer has a reserved TX descriptor
Return Value	None

whc_bridge_host_buf_rx_to_user

__attribute__((weak)) int whc_bridge_host_buf_rx_to_user(u8 *buf, u16 size);

Item	Description
Overview	Receives data from the device to the host. This is a weak function, the SDK sends data from the kernel to user space. Customers not using the bridge app need to implement this function.
Parameters	buf: Address of the received data size: Length of the received data (including padding)
Return Value	Data reception result: 0: Data successfully transferred to user space Other: Data reception error

whc_bridge_host_api_send_nl_data

int whc_bridge_host_api_send_nl_data(uint8_t *buf, uint32_t buf_len);

Item	Description
Overview	Sends data from user space to the kernel. which processes or forwards the data to the device based on the buffer content
Parameters	buf: Address of the data buffer buf_len: Length of the data
Return Value	Data transmission result: 0: Data sent successfully Other: Data transmission error

WiFi Bridge Linux Test

APP Architecture

The demo APP implements bidirectional control through two command categories:

1. Kernel-level Configuration

   • setmac: Configure device MAC address

   • netifon: Activate network interface carrier

2. Device-level Control

   • getmac: Retrieve device MAC address

   • getip: Fetch device IP configuration

   • setrdy: Notify device host status

Communication Stack

Supported Commands

Command Syntax	Description
init	Initialize Netlink communication channel
getmac <device_idx>	Retrieve device MAC address device_idx: The device port index can only be 0 or 1: where 0 corresponds to eth_sta0 (STA on the device side) and 1 corresponds to eth_sta1 (SoftAP on the device side).
getip <device_idx>	Fetch network layer configuration device_idx: The device port index and it is same to “getmac”.
setrdy	Notify device host readiness
setmac <device_idx> <mac>	Configure interface hardware address device_idx: The device port index and it is same to “getmac”. mac: MAC format (xx:xx:xx:xx:xx:xx)
netifon <device_idx>	Activate physical layer carrier device_idx: The device port index and it is same to “getmac”.

Note

1. In our kernel driver, the carrier state of the network device (net_device) is off by default, causing the device to not work properly. Use the “netifon” command to enable the carrier state, similar to calling the netif_carrier_on function. Developers should call netif_carrier_on to ensure proper device operation.

2. In our provided kernel driver, the network device (net_device) has a default MAC address of 00:00:00:00:00:00. Use the “setmac” command to configure the correct MAC address. Developers must set the correct physical address for the network device. Refer to the “getmac” and “setmac” commands for more details.

Build & Execution

# Navigate to bridge module
cd ${SDK}/component/wifi/whc_host_linux/bridge

# Build executable
make

# Run with privileges
sudo ./bridge

Testing Procedure

1. Initial Configuration

   # Start console
   > init
   > getmac 0
   00:0A:35:XX:XX:XX
   > setmac 0 00:0A:35:11:22:33
   > getip 0
   

2. Network Configuration

   # Assign IP address
   sudo ip addr add 192.168.1.100/24 dev eth_sta0
   sudo ip link set eth_sta0 up
   

3. Data Path Validation

   # Enable communication
   > setrdy
   > netifon 0
   
   # Perform network test
   ping 192.168.1.1
   

Validation Results

Test application control flow

Interface status verification

WiFi Bridge Throughput

SDIOSPI

Item	Bandwidth 20M
TCP TX	42Mbps
TCP RX	42Mbps
UDP TX	53Mbps
UDP RX	52Mbps

Test conditions:

• Image2 running on PSRAM

• AP: xiaomi AX3000

• Host platform: Linux PC

WiFi Bridge MP flow

There are two ways to implement the WiFi MP (Mass Production) flow:

1. If the loguart on the WHC bridge device is pinned out, the WiFi MP commands can be executed directly via the loguart.

2. If the loguart on the WHC bridge device is not pinned out, the WiFi MP commands must be executed on the Linux host application via the bridge’s passthrough mechanism.

With LoguartWithout Loguart

This approach is almost same to the standard RTOS MP test. To minimize interference from the WHC bridge, it is recommended to execute whc_bridge_dev_api_set_host_state(WHC_BRIDGE_HOST_UNREADY).