iframe-proxy

raulcxw · 2026-06-29T06:08:41Z

Summary

Add NuttX support for two Realtek Ameba dual-core WHC (WiFi Host
Controller) SoCs and their evaluation boards:

On these parts NuttX runs on the application (AP) core; the WiFi
MAC/PHY firmware runs on the network (NP) core, and the two cores talk
over the vendor IPC. The host WiFi stack is driven through a WHC glue layer.

What this PR adds:

arch/arm/src/rtl8721dx/ and arch/arm/src/rtl8720f/ chip support, plus a
shared arch/arm/src/common/ameba/ layer (IPC, WHC WiFi host glue, flash
MTD, LOGUART console, SDK fetch/build tooling).
boards/arm/rtl8721dx/pke8721daf/ and boards/arm/rtl8720f/rtl8720f_evb/
with an nsh defconfig each.
Platform/board documentation under Documentation/platforms/arm/.

Working features (both boards): NSH over LOGUART, WiFi STA scan + connect,
WiFi SoftAP, littlefs on the on-chip flash (MTD), and AP↔NP IPC.

How the dual-core / vendor-SDK integration works

Out-of-tree, pinned SDK — no vendored blobs. The build auto-fetches a
pinned commit of the public ameba-rtos SDK (shallow clone) into
arch/arm/src/common/ameba/, provisions its toolchain/venv, and compiles the
needed register-layer (fwlib) and WHC glue sources from SDK source into
per-board archives. The SDK tree is kept pristine (zero patches) — it
natively supports the single-core / boot build entry points we use.
NuttX owns the image2 entry. arch/arm/src/<chip>/ameba_app_start.c is a
NuttX-licensed adaptation of the SDK app_start() that performs the
OS-independent silicon init and then calls NuttX main(). No SDK source file
is modified.
NP/boot built from the same pinned SDK every build, fed NuttX's own
disassembly so the SDK's "noused" WiFi-API generator keeps exactly the host
APIs NuttX references (avoids an NP deadlock). This guarantees the two cores
never drift.
All vendor build artifacts live in a git-ignored prebuilt/ staging dir;
the SDK kconfig snapshots the packaging step needs are regenerated from the
pinned SDK on every build (never committed).

Impact

New architecture/boards only — adds new files under arch/arm/src/...
and boards/arm/...; the only edits to existing files are the additive
registration entries in arch/arm/Kconfig and boards/Kconfig. No existing
board or architecture is affected.
Build system: make only. The board CMakeLists.txt intentionally emits
a clear "CMake build not yet supported" FATAL_ERROR for these boards.
Network: standard NuttX netdev / wireless ioctls; no core net changes.
Documentation: new pages only.
Security: none (no changes to common code paths).

Testing

Built and run on real hardware for both boards.

Build (host: Ubuntu, arm-none-eabi from the SDK-provisioned toolchain):

./tools/configure.sh pke8721daf:nsh   && make    # -> app.bin, boot.bin, km0_image2_all.bin
./tools/configure.sh rtl8720f_evb:nsh && make    # -> app.bin, boot.bin, km4ns_image2_all.bin

The same configs are built in CI on a clean container using the official
apache-nuttx-ci-linux image (fresh SDK fetch from the pinned commit), and the
resulting firmware was flashed and verified on hardware:

NSH prompt over LOGUART, basic shell commands.
wapi/iwconfig WiFi scan and connect to a WPA2 AP; DHCP lease and
ping over the air.
SoftAP brought up; a client associates and obtains a DHCP address.
littlefs mounted on the flash data partition (read/write/persist across
reboot).

Notes for reviewers

The vendor SDK is auto-fetched (pinned), not vendored — there are no
binary blobs in the tree, and prebuilt/ is git-ignored.
nxstyle emits "Mixed case identifier" on vendor SDK symbol names
(e.g. Img2EntryFun0, SYSTIMER_Init) referenced from the adaptation files.
These are the SDK's public API spellings and cannot be renamed.
RTL8720F links the SDK lib_rom.a with --whole-archive (its ROM symbols
must all be present); this is required by the silicon's ROM layout.
A fork-only GitHub Actions workflow used to produce/verify the CI firmware is
not part of this PR.

github-actions · 2026-06-29T06:34:15Z

MemBrowse Memory Report

No memory changes detected for:

acassis · 2026-06-29T14:48:07Z

@raulcxw nice contribution! Kudos!!

Please fix this CI issue:

./env.sh: line 223: /github/workspace/sources/nuttx/arch/arm/src/common/ameba/ameba-rtos/.venv/bin/activate: No such file or directory
/github/workspace/sources/nuttx/arch/arm/src/common/ameba/ameba-rtos/.venv/bin/python: No module named pip
ameba_setup_env.sh: SDK venv (/github/workspace/sources/nuttx/arch/arm/src/common/ameba/ameba-rtos/.venv) is missing json5/click.
  Most likely the venv was not created properly -- install the python
  venv module (e.g. 'apt install python3-venv') so the SDK env.sh can
  build .venv with pip, then retry.  (A flaky PyPI can also cause it.)
make: *** [tools/Unix.mk:529: prebuild] Error 1
make: Target 'all' not remade because of errors.

Please remove reference to this .venv python

acassis · 2026-06-30T18:00:49Z

@raulcxw please fix this issue:

chip/ameba_wifi_init.c: In function 'rtl8721dx_wifi_initialize':
Error: chip/ameba_wifi_init.c:161:3: error: implicit declaration of function 'up_enable_irq'; did you mean 'up_enable_icache'? [-Werror=implicit-function-declaration]
  161 |   up_enable_irq(RTL8721DX_IRQ_IPC_KM4);
      |   ^~~~~~~~~~~~~
      |   up_enable_icache
``

Add NuttX support for two Realtek Ameba dual-core Wi-Fi Host Controller (WHC) SoCs: RTL8721Dx (board PKE8721DAF, application core KM4) and RTL8720F (board RTL8720F EVB, application core KM4TZ). NuttX runs on the Cortex-M33 application/host core and drives the Wi-Fi MAC/PHY on the network-processor core (KM0 / KM4NS) over the on-chip IPC transport (WHC). The IC-agnostic glue is shared in arch/arm/src/common/ameba (os_wrapper backend, WHC netdev with STA + SoftAP, key-value store, flash MTD / littlefs); only the register-level drivers are per-IC. The image2 entry is a NuttX-owned app_start() (arch/arm/src/<chip>/ameba_app_start.c) that runs the SoC silicon init and calls main(); the vendor ameba-rtos SDK is used pristine -- shallow-cloned at a pinned commit, no patching -- and provides the prebuilt Wi-Fi / ROM libraries linked into the image. Features: NSH console, littlefs at /data on SPI NOR, Wi-Fi STA + SoftAP via wapi, DHCP client/server, NuttX-native TCP/IP (no lwIP). Builds via the make build only; the board CMakeLists guards CMake with a clear "not yet supported" message. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

Add platform/board documentation for the Realtek RTL8721Dx (PKE8721DAF) and RTL8720F (RTL8720F EVB) Ameba WHC ports: the vendor SDK dependency (auto-fetched at a pinned commit), the build steps, and Wi-Fi STA / SoftAP usage with wapi and the DHCP server. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

The build ran the SDK env.sh and then mandated $SDK/.venv/bin/python with json5/click. On an image without python3-venv/ensurepip the venv is created pip-less, so env.sh installs the tool deps into the system python3 instead and the build aborted in prebuild ("SDK venv is missing json5/click"). ameba_setup_env.sh now resolves a deps-carrying interpreter -- the SDK .venv when its python imports the deps, otherwise the system python3 exposed through a non-venv shim dir (so a bare `python` exists and the system site-packages stay visible) -- and records its bin directory in .amebapy/bindir. board.mk and the gen-autoconf / build-np helpers read that file instead of hard-coding .venv/bin, so the build proceeds whenever a python (venv or system) carries the deps. The sentinel also checks a compiled wheel (pycryptodome) so a partial dep install is detected, not just the pure-python json5/click. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

The board defconfigs took the DEBUG_NOOPT default (-O0), which made the whole image run several times slower and capped iperf UDP RX at ~4 Mbps. Select DEBUG_FULLOPT (-O2). Decouple the WiFi RX seam: ameba_wlan_rxframe now copies each frame into a pooled IOB, queues it and schedules a worker (ameba_wlan_rxwork), so the WHC host RX path returns immediately -- the NP recycles its RX buffer at once -- instead of running ipv4_input()/the reply TX inline in the RX callback and stalling the NP RX ring. Size the IOB pool for sustained WiFi RX (IOB_BUFSIZE=400, IOB_NBUFFERS=100, IOB_THROTTLE=40). Together these take iperf UDP RX from ~0.9 Mbps to ~20 Mbps. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

Adds a generic FLASH macro in tools/ameba/Config.mk that invokes the SDK's AmebaFlash.py, modeled on the ESP32 approach (tools/espressif/Config.mk). Each board sets AMEBA_FLASH_PROFILE and includes the fragment from its scripts/Make.defs. Usage: make flash AMEBA_PORT=/dev/ttyUSB0 [ AMEBA_BAUD=1500000 ] The python interpreter resolved by ameba_setup_env.sh (.amebapy/bindir) is used so that AmebaFlash.py's dependencies (pyDes, json5, click, etc.) are available. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

Adds the make flash AMEBA_PORT=/dev/ttyUSB0 command and a pointer to the Realtek Ameba ImageTool guide (Windows GUI) to both board docs, addressing the reviewer's request for programmer model and flashing command details. Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

…t 1500000) Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

xiaoxiang781216 · 2026-07-01T04:28:26Z

 Windows GUI tool and download-mode entry (hold the download button /
 power-cycle with the ``UART_LOG_TX`` line asserted).

+**Serial console** — after flashing, connect to the LOG-UART at 1500000 8N1::


merge into documentation patch

xiaoxiang781216 · 2026-07-01T04:28:47Z


 This produces ``nuttx/app.bin`` (the NuttX KM4TZ image2), ``boot.bin`` and the
-NP (KM4NS) image, ready to flash with the Realtek tooling.
+NP (KM4NS) image in the build directory.


merge to the documentation patch

xiaoxiang781216 · 2026-07-01T04:29:22Z


 include $(TOPDIR)/arch/arm/src/rtl8720f/ameba_board.mk
+
+# Flashing via the SDK AmebaFlash.py (make flash AMEBA_PORT=/dev/ttyUSB0)


merge to board patch

xiaoxiang781216 · 2026-07-01T04:29:57Z

 *   RX:  netif_adapter_wifi_recv_whc() -> ameba_wlan_rxframe()  (this file)
 *
- * Modeled on arch/arm/src/rtl8720c/amebaz_netdev.c and the bcmf driver.
+ * Follows the standard NuttX Ethernet-style netdev (devif) RX/TX idiom.


merge to the chip patch

xiaoxiang781216 · 2026-07-01T04:30:10Z

 CONFIG_BUILTIN=y
 CONFIG_DEBUG_ASSERTIONS=y
 CONFIG_DEBUG_FEATURES=y
+CONFIG_DEBUG_FULLOPT=y


merge to board patch

xiaoxiang781216 · 2026-07-01T04:30:37Z


-# Prefer the SDK venv python (ameba.py tooling); fall back to system python3.
-VENV_PY="$SDK/.venv/bin/python"
+# Use the python dir ameba_setup_env.sh resolved (a real .venv when one


merge into chip patch

raulcxw requested review from acassis, jerpelea and raiden00pl as code owners June 29, 2026 06:08

github-actions Bot added Area: Build system Arch: arm Issues related to ARM (32-bit) architecture Size: XL The size of the change in this PR is very large. Consider breaking down the PR into smaller pieces. Board: arm labels Jun 29, 2026

simbit18 requested review from Donny9, anchao, linguini1, michallenc, wangchdo and xiaoxiang781216 June 29, 2026 11:21

acassis previously approved these changes Jun 29, 2026

View reviewed changes

Comment thread Documentation/platforms/arm/rtl8720f/boards/rtl8720f_evb/index.rst

linguini1 reviewed Jun 29, 2026

View reviewed changes

Comment thread Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/index.rst

raulcxw dismissed acassis’s stale review via d7d72be June 30, 2026 07:04

raulcxw force-pushed the ameba-pr branch from d7d72be to 135e34d Compare June 30, 2026 07:42

raulcxw requested review from davids5 and johannes-nivus as code owners June 30, 2026 07:42

raulcxw force-pushed the ameba-pr branch 2 times, most recently from b267f29 to 3b22294 Compare June 30, 2026 08:03

xiaoxiang781216 previously approved these changes Jun 30, 2026

View reviewed changes

acassis previously approved these changes Jun 30, 2026

View reviewed changes

acassis reviewed Jun 30, 2026

View reviewed changes

Comment thread Documentation/platforms/arm/rtl8720f/boards/rtl8720f_evb/index.rst Outdated

Comment thread Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/index.rst Outdated

raulcxw added 3 commits July 1, 2026 09:45

Donny9 previously approved these changes Jul 1, 2026

View reviewed changes

raulcxw added 2 commits July 1, 2026 12:00

raulcxw dismissed stale reviews from Donny9, acassis, and xiaoxiang781216 via 9d18d78 July 1, 2026 04:01

raulcxw force-pushed the ameba-pr branch from 3b22294 to 9d18d78 Compare July 1, 2026 04:01

docs: add serial console connection command (picocom/screen/minicom a…

50da1f9

…t 1500000) Signed-off-by: raul_chen <raul_chen@realsil.com.cn>

xiaoxiang781216 reviewed Jul 1, 2026

View reviewed changes

Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

arch/arm: add Realtek RTL8721Dx and RTL8720F (Ameba IOT) support#19236

arch/arm: add Realtek RTL8721Dx and RTL8720F (Ameba IOT) support#19236
raulcxw wants to merge 7 commits into
apache:masterfrom
Ameba-AIoT:ameba-pr

raulcxw commented Jun 29, 2026

Uh oh!

github-actions Bot commented Jun 29, 2026 •

edited

Loading

Uh oh!

acassis commented Jun 29, 2026

Uh oh!

Uh oh!

Uh oh!

acassis commented Jun 30, 2026

Uh oh!

Uh oh!

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

xiaoxiang781216 Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

SoC	Board	AP core (NuttX)	NP core (WiFi)
RTL8721Dx	`pke8721daf`	km4 (Cortex-M33)	km0
RTL8720F	`rtl8720f_evb`	km4tz (Cortex-M33)	km4ns


		include $(TOPDIR)/arch/arm/src/rtl8720f/ameba_board.mk

		# Flashing via the SDK AmebaFlash.py (make flash AMEBA_PORT=/dev/ttyUSB0)

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Conversation

raulcxw commented Jun 29, 2026

Summary

How the dual-core / vendor-SDK integration works

Impact

Testing

Notes for reviewers

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MemBrowse Memory Report

Uh oh!

acassis commented Jun 29, 2026

Uh oh!

Uh oh!

Uh oh!

acassis commented Jun 30, 2026

Uh oh!

Uh oh!

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

xiaoxiang781216 Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Jun 29, 2026 •

edited

Loading