arch/arm/rtl8721f: add RTL8721F chip and EVB board support

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.

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/*/*

arch/arm/Kconfig

@@ -880,6 +880,18 @@ config ARCH_CHIP_RTL8720F
 		runs on the km4ns network-processor core.  Shares the IC-agnostic
 		ameba glue in arch/arm/src/common/ameba.
 
+config ARCH_CHIP_RTL8721F
+	bool "Realtek RTL8721F"
+	select ARCH_CORTEXM33
+	select ARMV8M_HAVE_STACKCHECK
+	select OTHER_UART_SERIALDRIVER
+	---help---
+		Realtek RTL8721F (SDK codename Green2 / amebagreen2; km4tz
+		application/host core, ARMv8-M.main / Cortex-M33).  Dual-core WHC
+		like the RTL8720F; the WiFi MAC/PHY runs on the km4ns
+		network-processor core.  Shares the IC-agnostic ameba glue in
+		arch/arm/src/common/ameba.
+
 config ARCH_CHIP_QEMU_ARM
 	bool "QEMU virt platform (ARMv7a)"
 	select ARCH_HAVE_POWEROFF
@@ -1372,6 +1384,7 @@ config ARCH_CHIP
 	default "mps"		if ARCH_CHIP_MPS
 	default "rtl8721dx"	if ARCH_CHIP_RTL8721DX
 	default "rtl8720f"	if ARCH_CHIP_RTL8720F
+	default "rtl8721f"	if ARCH_CHIP_RTL8721F
 	default "goldfish"	if ARCH_CHIP_GOLDFISH_ARM
 	default "at32"		if ARCH_CHIP_AT32
 	default "cxd32xx"	if ARCH_CHIP_CXD32XX
@@ -1947,6 +1960,9 @@ endif
 if ARCH_CHIP_RTL8720F
 source "arch/arm/src/rtl8720f/Kconfig"
 endif
+if ARCH_CHIP_RTL8721F
+source "arch/arm/src/rtl8721f/Kconfig"
+endif
 if ARCH_CHIP_GOLDFISH_ARM
 source "arch/arm/src/goldfish/Kconfig"
 endif

arch/arm/include/rtl8721f/chip.h

@@ -0,0 +1,53 @@
+/****************************************************************************
+ * arch/arm/include/rtl8721f/chip.h
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __ARCH_ARM_INCLUDE_RTL8721F_CHIP_H
+#define __ARCH_ARM_INCLUDE_RTL8721F_CHIP_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+/****************************************************************************
+ * Pre-processor Prototypes
+ ****************************************************************************/
+
+#define NVIC_SYSH_PRIORITY_MIN     0xf0 /* Bits [7:5] set in minimum priority */
+#define NVIC_SYSH_PRIORITY_DEFAULT 0x80 /* Midpoint is the default */
+#define NVIC_SYSH_PRIORITY_MAX     0x00 /* Zero is maximum priority */
+#define NVIC_SYSH_PRIORITY_STEP    0x10 /* Four bits of interrupt priority used */
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Functions Prototypes
+ ****************************************************************************/
+
+#endif /* __ARCH_ARM_INCLUDE_RTL8721F_CHIP_H */