Supported ICs

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

The FullMAC architecture is illustrated below:

../../_images/fullmac_architecture.svg

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 Features

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

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

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:

    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.

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

Device Driver Porting

  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:

      (Top) -> CONFIG Link Option
----Configuration----
    IMG1(Bootloader) running on FLASH or PSRAM?
    IMG2(Application) running on FLASH or PSRAM?
     ( ) FLASH
     (X) PSRAM
CONFIG Mass Production --->
... --->

    2. Locate CONFIG WHC ITNF > WHC MODE > FULLMAC_DEV > HW INTERFACE, and select the desired interface:

      (Top) -> CONFIG WHC INTF
----Configuration----
    WHC MODE (FULLMAC_DEV) --->
    HW INTERFACE --->
        ( ) WHC_INTF_SDIO
        ( ) WHC_INTF_USB
        ( ) WHC_INTF_SPI
    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.

Host Driver Porting

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 the directories component/os/freertos to target system.

FullMAC BT Porting Guide

Device Driver Porting

Host Driver Porting

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 RTL8721Dx (KM4: 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