Supported ICs

Ameba SoC	RTL8721Dx	RTL8726EA	RTL8720EA	RTL8730E
Supported	Y	N	N	N

Wi-Fi Bridge Architecture

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

Wi-Fi Bridge Interfaces

RTL8721Dx

Linux HostFreeRTOS HostZephyr Host

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

Wi-Fi 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

Wi-Fi Bridge File Architecture

RTOS Host/DeviceLinux 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

Wi-Fi Bridge Hardware Configuration

Interface Connections

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

RTL8721DxRaspberry 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
UART	PB4	UART_RX
	PB5	UART_TX

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

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.

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

Wi-Fi Bridge Porting Guide

Device Porting

1. Project Configuration

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

      ./menuconfig.py
      

   2. Select CONFIG WHC ITNF > WHC Mode > WHC_BRIDGE > HW INTERFACE in order, then select the bridge mode and desired interface

      SDIOSPI

      Select WHC_INTF_SDIO:

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

2. Firmware Compilation

   Build the image with compile command:

   ./build.py
   

3. Image Flashing

   Flash the generated image to development board using programming tool.

Host Porting

RTOSLinux EnvironmentRaspberry Pi

Wi-Fi 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

Wi-Fi 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

The communication control flow is illustrated below:

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. 0: corresponds to eth_sta0 (STA on the device side) 1: corresponds to eth_sta1 (SoftAP on the device side).
getip <device_idx>	Fetch network layer configuration device_idx: The device port index. It is the same to getmac.
setrdy	Notify device host readiness
setmac <device_idx> <mac>	Configure interface hardware address device_idx: The device port index. It is the 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. It is the same to getmac.

Note

• In our provided kernel driver, the carrier state of the network 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.

• In our provided kernel driver, the network device has a default MAC address of 00:00:00:00:00:00. Developers must set the correct physical address for the network device with the setmac command. 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

testapp control flow

ifconfig status verification

Wi-Fi 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

Wi-Fi Bridge MP flow

There are two ways to implement the Wi-Fi MP (Mass Production) flow:

• If the LOGUART on the WHC bridge device is pinned out, the Wi-Fi MP commands can be executed directly via the LOGUART.

• If the LOGUART on the WHC bridge device is not pinned out, the Wi-Fi 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 FreeRTOS, refer to 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).