Supported Chips

Ameba SoC

RTL8721Dx

RTL8726E

RTL8720E

RTL8730E

Supported

Y

N

N

N

FullMAC Overview

In the WHC FullMAC solution, Ameba acts as a network interface card connected to the host MCU via UART/SPI/SDIO/USB, providing network connectivity.

FullMAC Architecture

Core Features:

  • Establishes UART/SPI/SDIO/USB transmission channels between Host and Device

  • Compatible with Linux standard wpa_supplicant and cfg80211 wireless framework

  • Supports WiFi/BT command transmission and customized command extensions

../../_images/wifi_fullmac_architecture.svg

FullMAC architecture

Note

Host OS Support

  • Linux

  • FreeRTOS

  • Zephyr

Note

Bluetooth Stack Compatibility

  • Linux Host: Bluez Stack

  • Zephyr Host: Zephyr BT Stack

  • FreeRTOS: Realtek BT Stack

FullMAC Transmission Interface Specifications

Interface

Wi-Fi

BT

SDIO

Y

Y

SPI

Y

Y

USB

Y

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

FullMAC Feature Details

Features

Linux host

FreeRTOS host

Zephyr host

Wi-Fi API

Standard Linux APIs

FreeRTOS Wi-Fi APIs

Standard Zephyr APIs

Wi-Fi mode

  • Station

  • SoftAP

  • NAN

  • P2P GO

  • Station

  • SoftAP

  • Station

  • SoftAP

Wi-Fi security

  • Open

  • WPA

  • WPA2

  • WPA3

  • Open

  • WPA

  • WPA2

  • WPA3

  • Open

  • WPA

  • WPA2

  • WPA3

Wowlan

Y

Y

Y

Bluetooth features

  • BLE 5.0

  • BLE 5.2

  • Bluetooth 5.3

  • BLE 5.0

  • BLE 5.2

  • Bluetooth 5.3

  • BLE 5.0

  • BLE 5.2

  • Bluetooth 5.3

FullMAC File Structure

Wi-Fi

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

Bluetooth

FullMAC Hardware Configuration

Interface Connections

Pin connections between Ameba and Raspberry Pi are as follows:

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:

    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:

../../_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

FullMAC Wi-Fi Device Driver Porting Guide

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

    1. Locate CONFIG Link Option > IMG2(Application) running on FLASH or PSRAM?, and select PSRAM:

      ----General Config----
    CONFIG TrustZone --->
    CONFIG Link Option --->
      (FLASH) MG1(Bootloader) running on FLASH or PSRAM?
      (PSRAM) MG2(Application) running on FLASH or PSRAM?
    CONFIG Mass Production --->
    ... --->

    2. Locate CONFIG WHC ITNF > WHC MODE (FULLMAC), and select the desired interface:

      (Top) -> CONFIG WHC INTF
----Configuration----
    WHC MODE (FULLMAC) --->
    HW INTERFACE (WHC_INTF_SDIO) --->
    WPA Lite location (Host) --->
    Debug --->

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

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

FullMAC Wi-Fi Host Driver Porting Guide

Ameba as FullMAC Host Guide

  1. Configuration

    1. Execute config tool in directory {SDK}/amebadplus_gcc_project:

    ./menuconfig.py

    1. Navigate to CONFIG WHC ITNF > WHC MODE and select interface:

      (Top) -> CONFIG WHC INTF
----Configuration----
    WHC MODE (FULLMAC_HOST) --->
    HW INTERFACE (WHC_INTF_SPI) --->

  2. Firmware Compilation

    Generate target files:

    ./build.py

    Output Files:

    • km4_boot_all.bin

    • km0_km4_app.bin

  3. Firmware Flashing

    Use dedicated flashing tool to program development board

Third-party Platform Porting

For other host chips, port these directories to target system:

  • component/os/freertos

FullMAC BT Device Driver Porting Guide

FullMAC BT Host Driver Porting Guide

FullMAC Wi-Fi Throughput

Interface

Item

BW 20M (Mbps)

SPI [1]

TCP RX

8.3

TCP TX

9.9

UDP RX

15.8

UDP TX

17.6

  • [1] The data is the test result of device code running in PSRAM, host driver running on 8721Dx (260MHz).

FullMAC 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