This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 83ac26ba1cdd811e80a6df12364d9126dd8de9bc Author: dechao_gong <[email protected]> AuthorDate: Tue Jul 28 17:59:17 2026 +0800 Documentation/rtl8721f: add RTL8721F platform and EVB board pages Add platform documentation for the Realtek RTL8721F: a chip overview page and the rtl8721f_evb board page, modelled on the existing RTL8720F / RTL8721Dx docs. The platform index picks them up automatically via its */index glob. The pages cover the vendor-SDK/toolchain dependency, the make and CMake build/flash flow, and the hardware-verified features: NSH over the LOG-UART console, littlefs at /data on the on-chip NOR flash, Wi-Fi station and SoftAP via the wapi tool, and the DHCP client/server. Signed-off-by: dechao_gong <[email protected]> Co-Authored-By: Claude <[email protected]> --- .../arm/rtl8721f/boards/rtl8721f_evb/index.rst | 85 ++++++++++++ Documentation/platforms/arm/rtl8721f/index.rst | 144 +++++++++++++++++++++ 2 files changed, 229 insertions(+) diff --git a/Documentation/platforms/arm/rtl8721f/boards/rtl8721f_evb/index.rst b/Documentation/platforms/arm/rtl8721f/boards/rtl8721f_evb/index.rst new file mode 100644 index 00000000000..b1f348cd5f6 --- /dev/null +++ b/Documentation/platforms/arm/rtl8721f/boards/rtl8721f_evb/index.rst @@ -0,0 +1,85 @@ +============ +RTL8721F EVB +============ + +.. tags:: chip:rtl8721f, arch:arm, vendor:realtek + +.. todo:: + + Add a photo of the RTL8721F EVB board here as ``rtl8721f_evb.png`` in this + directory, referenced with a ``.. figure::`` directive. + +The RTL8721F EVB is a Realtek RTL8721F evaluation board. NuttX runs on the +KM4TZ application core — an Arm Cortex-M55-compatible core running at up to +320 MHz. See the :doc:`RTL8721F chip documentation <../../index>` for the +full SoC specifications and the vendor-SDK dependency. + +Features +======== + +* RTL8721F: Arm Cortex-M55-compatible KM4TZ core up to 320 MHz, + 512 KB SRAM, 4 MB NOR flash +* Wi-Fi 6 (802.11 a/b/g/n/ax), dual-band 2.4/5 GHz station and SoftAP +* SPI NOR flash (XIP) +* LOG-UART console + +Supported in this NuttX port: + +* NSH shell over the LOG-UART console +* littlefs persistent storage mounted at ``/data`` (a dedicated SPI NOR flash + partition) +* Wi-Fi station and SoftAP through the ``wapi`` tool +* DHCP client (STA) and DHCP server (SoftAP) + +Buttons and LEDs +================ + +This NuttX port does not wire any user buttons or LEDs. + +Configurations +============== + +Build and flash any of these per the :doc:`RTL8721F build instructions +<../../index>`; for the CMake build, source ``. tools/ameba/env.sh +rtl8721f_evb`` first (the make build needs no sourcing). + +.. code:: console + + $ ./tools/configure.sh rtl8721f_evb:<config-name> + +nsh +--- + +Networking-enabled NSH with littlefs at ``/data`` and the ``wapi`` Wi-Fi tool. +The console is the LOG-UART at 1500000 8N1 (the rate is configured by the +bootloader and inherited by NuttX). The Wi-Fi examples below are available from +this configuration. + +Wi-Fi +===== + +Station (connect to an AP):: + + nsh> wapi psk wlan0 <password> 3 + nsh> wapi essid wlan0 <ssid> 1 + nsh> renew wlan0 + +SoftAP (become an access point, with a DHCP server for clients):: + + nsh> wapi mode wlan0 3 + nsh> wapi psk wlan0 <password> 3 + nsh> wapi essid wlan0 <ssid> 1 + nsh> ifconfig wlan0 192.168.4.1 netmask 255.255.255.0 + nsh> dhcpd_start wlan0 + +Stop the SoftAP with ``wapi essid wlan0 <ssid> 0``. + +License Exceptions +================== + +This board depends on Realtek vendor code that is not part of NuttX and is +subject to its own license: + +* The prebuilt Wi-Fi / Bluetooth firmware image and the Realtek ``ameba-rtos`` + SDK libraries/headers linked into the image. See the SDK's own license; the + SDK is auto-fetched and is not redistributed in the NuttX tree. diff --git a/Documentation/platforms/arm/rtl8721f/index.rst b/Documentation/platforms/arm/rtl8721f/index.rst new file mode 100644 index 00000000000..945940e4d0b --- /dev/null +++ b/Documentation/platforms/arm/rtl8721f/index.rst @@ -0,0 +1,144 @@ +================ +Realtek RTL8721F +================ + +The Realtek RTL8721F is a low-power multi-protocol wireless SoC from the +Realtek Ameba IoT family, combining dual-band (2.4/5 GHz) Wi-Fi 6 and +Bluetooth LE connectivity. + +NuttX runs on the **KM4TZ application core** — an Arm Cortex-M55-compatible +core (Real-M300, Armv8.1-M) running at up to **320 MHz**, with Arm +TrustZone-M. The image is built soft-float. + +Highlights +========== + +- **CPU:** Arm Cortex-M55-compatible KM4TZ application core, up to 320 MHz, + with TrustZone-M and instruction/data caches; the image is built soft-float. +- **Memory:** 512 KB on-chip SRAM; external QSPI NOR flash (up to 104 MHz) + and/or DDR PSRAM (up to 200 MHz), depending on the part number. +- **Wireless:** Wi-Fi 6 (802.11 a/b/g/n/ax), dual-band 2.4/5 GHz, up to + 114.7 Mbps, WPA/WPA2/WPA3; Bluetooth LE 5.x. +- **Peripherals:** UART, SPI, I2C, I2S, SDIO, ADC, IR, CAN, RTC and + watchdogs (count varies by package). +- **Security:** Secure Boot, TrustZone-M, AES/SHA and ECDSA/RSA crypto + engines, Flash decryption, OTP, and a true random number generator. +- **Package:** QFN48, QFN68 or QFN100 (varies by part number). + +Memory +====== + +============ ============= ======= +Block Start Address Length +============ ============= ======= +SRAM 0x2000_0000 512 KB +============ ============= ======= + +The on-chip SRAM holds the system heap and application. The flash is an SPI +NOR accessed through the SDK XIP path. The exact flash / PSRAM size depends on +the part number. + +Vendor SDK and Toolchain +======================== + +The build depends on Realtek's open ``ameba-rtos`` SDK and its matching +``arm-none-eabi`` toolchain (from the Realtek asdk release), neither of which is +part of the NuttX tree. The SDK provides the Wi-Fi / Bluetooth firmware and the +low-level chip libraries; NuttX links its own libc / libm and reuses the SDK's +``app_start()`` as the image entry point. + +Both are fetched automatically — there is nothing to install by hand: + +- **make** fetches them on the first ``make`` (from its ``PREBUILD`` step). +- **CMake** fetches them when you source ``. tools/ameba/env.sh <board>``, which + must run before ``cmake`` (CMake probes the compiler at configure time). The + make build resolves everything on demand, so it needs no sourcing. + +The SDK is a shallow ``git clone`` of the pinned revision of +``https://github.com/Ameba-AIoT/ameba-rtos.git`` into +``arch/arm/src/common/ameba/ameba-rtos`` (git-ignored) and is built unmodified; +export ``AMEBA_SDK`` to use a local checkout instead. The asdk version is +pinned **per IC** by the SDK, so different Ameba ICs may use different toolchain +versions — the build selects the matching one automatically. + +Building and Flashing +===================== + +Replace ``<board>`` below with an actual board (e.g. ``rtl8721f_evb``) and +``<config>`` with one of its configurations. The first build fetches the SDK +and toolchain (see `Vendor SDK and Toolchain`_). + +With make +--------- + +.. code:: console + + $ ./tools/configure.sh <board>:<config> + $ make + +With CMake +---------- + +CMake probes the compiler at configure time, so source the Ameba environment +once first, **passing the board** so the asdk version that IC pins is on +``PATH``: + +.. code:: console + + $ . tools/ameba/env.sh <board> + $ cmake -B build -DBOARD_CONFIG=<board>:<config> -GNinja + $ cmake --build build + +make writes ``nuttx.bin`` to the top-level directory; CMake writes it under +``build/``. The bootloader ``boot.bin`` is a prebuilt binary under the board's +``prebuilt/`` directory; the flash step writes both at the offsets taken from +the generated flash layout, so none are entered by hand. + +Flashing +-------- + +**CLI (Linux/macOS)** — connect a USB-UART adapter and use the built-in flash +target (the baud defaults to 1500000; override with ``AMEBA_BAUD``):: + + $ make flash AMEBA_PORT=/dev/ttyUSB0 # make build + $ AMEBA_PORT=/dev/ttyUSB0 cmake --build build --target flash # CMake build + +**GUI (Windows)** — use the Realtek AmebaImageTool (``AmebaImageTool.exe`` under +``tools/ameba/ImageTool/`` in the SDK tree) to select ``boot.bin`` (from the +board's ``prebuilt/`` directory) and ``nuttx.bin``. See the `Realtek Ameba +ImageTool guide <https://aiot.realmcu.com/en/latest/tools/image_tool/index.html>`_ +for the 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:: + + $ picocom -b 1500000 /dev/ttyUSB0 + +Configuration +============= + +The build-time options are the same for make and CMake (both edit the one +Kconfig for the selected board); only the command that launches the menuconfig +UI differs: + +.. code:: console + + $ make menuconfig # make build + $ cmake --build build -t menuconfig # CMake build + +Supported Features +================== + +- NSH over the LOG-UART console +- littlefs persistent storage at ``/data`` on the SPI NOR flash +- Wi-Fi station (scan / connect) and SoftAP via the ``wapi`` tool +- Networking on NuttX's own TCP/IP stack, with DHCP client and DHCP server + +Boards +====== + +.. toctree:: + :glob: + :maxdepth: 1 + + boards/*/*
