This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 76838fa1b2a5cc8aadd29725e081fbd779faa04b Author: raul_chen <[email protected]> AuthorDate: Wed Jul 1 16:07:41 2026 +0800 Documentation: add Realtek RTL8721Dx and RTL8720F platform docs Add the chip-level and board-level documentation for both Ameba WHC SoCs and their evaluation boards. Each board document follows the board.rst template with tags, features, configurations, building and flashing instructions, and license exceptions. Signed-off-by: raul_chen <[email protected]> --- .../arm/rtl8720f/boards/rtl8720f_evb/index.rst | 131 +++++++++++++++++++++ Documentation/platforms/arm/rtl8720f/index.rst | 62 ++++++++++ .../arm/rtl8721dx/boards/pke8721daf/PKE8721DAF.png | Bin 0 -> 1371429 bytes .../arm/rtl8721dx/boards/pke8721daf/index.rst | 130 ++++++++++++++++++++ Documentation/platforms/arm/rtl8721dx/index.rst | 61 ++++++++++ 5 files changed, 384 insertions(+) diff --git a/Documentation/platforms/arm/rtl8720f/boards/rtl8720f_evb/index.rst b/Documentation/platforms/arm/rtl8720f/boards/rtl8720f_evb/index.rst new file mode 100644 index 00000000000..e5322bd19cd --- /dev/null +++ b/Documentation/platforms/arm/rtl8720f/boards/rtl8720f_evb/index.rst @@ -0,0 +1,131 @@ +============ +RTL8720F EVB +============ + +.. tags:: chip:rtl8720f, arch:arm, vendor:realtek + +.. todo:: + + Add a photo of the RTL8720F EVB board here as ``rtl8720f_evb.png`` in this + directory, referenced with a ``.. figure::`` directive. + +The RTL8720F EVB is a Realtek RTL8720F (dual-core Wi-Fi Host Controller) +evaluation board. NuttX runs on the KM4TZ (Cortex-M33, secure world) +application core as the Wi-Fi host; the KM4NS network processor runs the +prebuilt vendor Wi-Fi firmware. See the +:doc:`RTL8720F chip documentation <../../index>` for the SoC architecture, +memory map and vendor-SDK dependency. + +Features +======== + +* RTL8720F dual-core Wi-Fi Host Controller (KM4TZ Cortex-M33 secure host + + KM4NS NP) +* 2.4 GHz Wi-Fi (station and SoftAP) +* SPI NOR flash (shared with the NP, XIP) +* LOG-UART console + +Supported in this NuttX port: + +* NSH shell over the LOG-UART console (NuttX owns LOG-UART RX directly; the NP + shell is disabled) +* littlefs persistent storage mounted at ``/data`` (a dedicated SPI NOR flash + partition), backing the Wi-Fi key-value store +* Wi-Fi station and SoftAP through the ``wapi`` tool +* DHCP client (STA) and DHCP server (SoftAP) + +.. note:: + + The Wi-Fi MAC/PHY is driven by the prebuilt vendor firmware on the KM4NS + network processor. NuttX is the Wi-Fi host and exchanges frames with the NP + over the on-chip IPC transport; see the chip documentation. + +Buttons and LEDs +================ + +This NuttX port does not wire any user buttons or LEDs. + +Configurations +============== + +.. code:: console + + $ ./tools/configure.sh rtl8720f_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``. + +Building and Flashing +===================== + +The build auto-fetches the Realtek ``ameba-rtos`` SDK on first use and a +Realtek ``arm-none-eabi`` toolchain must be on ``PATH``; see the +:doc:`chip documentation <../../index>` for both. + +.. code:: console + + $ ./tools/configure.sh rtl8720f_evb:nsh + $ make + +This produces ``nuttx/app.bin`` (the NuttX KM4TZ image2), ``boot.bin`` and the +NP (KM4NS) image in the build directory. + +After a successful build, flash via one of these methods: + +**CLI (Linux/macOS)** — connect a USB-UART adapter (PL2303) and use the +built-in ``make flash`` target: + +.. code:: console + + $ make flash AMEBA_PORT=/dev/ttyUSB0 + +The baud rate defaults to 1500000; override with ``AMEBA_BAUD`` if needed. + +**GUI (Windows)** — use the Realtek AmebaImageTool (``AmebaImageTool.exe`` +under ``tools/ameba/ImageTool/`` in the SDK tree) to select ``boot.bin`` and +``app.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 + +Other tools: ``screen /dev/ttyUSB0 1500000`` or ``minicom -b 1500000 -D /dev/ttyUSB0``. + +License Exceptions +================== + +This board depends on Realtek vendor code that is not part of NuttX and is +subject to its own license: + +* The prebuilt KM4NS (NP) Wi-Fi 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/rtl8720f/index.rst b/Documentation/platforms/arm/rtl8720f/index.rst new file mode 100644 index 00000000000..942fe1697a8 --- /dev/null +++ b/Documentation/platforms/arm/rtl8720f/index.rst @@ -0,0 +1,62 @@ +================ +Realtek RTL8720F +================ + +The Realtek RTL8720F is a dual-core Wi-Fi Host Controller (WHC) SoC, similar in +scheme to the :doc:`RTL8721Dx <../rtl8721dx/index>`: + +- **KM4TZ** — an ARM Cortex-M33 (ARMv8-M.main, with FPU) application/host core + running in the TrustZone secure world. NuttX runs here. +- **KM4NS** — the non-secure network-processor (NP) core that owns the Wi-Fi + MAC/PHY and runs a prebuilt vendor firmware image. + +NuttX is the Wi-Fi *host*: it talks to the NP over the on-chip IPC transport +(WHC) while the NP drives the radio. The IC-agnostic glue (os_wrapper backend, +netdev, key-value store, flash MTD, WHC Wi-Fi glue) is shared from +``arch/arm/src/common/ameba`` with the other Ameba WHC parts; only the +register-level drivers are IC-specific. + +Memory Map +========== + +============ ============= ====== +Block Name Start Address Length +============ ============= ====== +SRAM 0x20000000 512K +============ ============= ====== + +The KM4TZ runs in the secure world, so the SRAM is also visible through the +secure alias at ``0x30000000``. The KM4TZ image2 RAM window is a slice of that +SRAM; the flash is a SPI NOR shared with the NP. + +Vendor SDK Dependency +===================== + +The build depends on Realtek's open ``ameba-rtos`` SDK, which is **not** part +of the NuttX tree. The first build auto-fetches the pinned revision (a shallow +``git clone`` of ``https://gitee.com/ameba-aiot/ameba-rtos.git``) into +``arch/arm/src/common/ameba/ameba-rtos`` (git-ignored) and applies the +out-of-SDK build patch under ``arch/arm/src/common/ameba/patches``. To use a +local checkout instead of auto-fetching, export ``AMEBA_SDK`` to its path. + +A matching Realtek ARM toolchain (``arm-none-eabi`` from the Realtek asdk +release) is required; NuttX links its own libc/libm and reuses the SDK's +``app_start()`` as the image2 entry point. + +Supported Features +================== + +- NSH over the LOG-UART console (NuttX owns LOG-UART RX directly; the NP shell + is disabled) +- littlefs persistent storage at ``/data`` on the SPI NOR +- Wi-Fi STA (scan / connect) and SoftAP via the ``wapi`` tool +- Networking over the WHC netdev (NuttX TCP/IP stack), DHCP client and server + +Boards +====== + +.. toctree:: + :glob: + :maxdepth: 1 + + boards/*/* diff --git a/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/PKE8721DAF.png b/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/PKE8721DAF.png new file mode 100644 index 00000000000..7fc7be1e23b Binary files /dev/null and b/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/PKE8721DAF.png differ diff --git a/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/index.rst b/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/index.rst new file mode 100644 index 00000000000..7f41d08f797 --- /dev/null +++ b/Documentation/platforms/arm/rtl8721dx/boards/pke8721daf/index.rst @@ -0,0 +1,130 @@ +========== +PKE8721DAF +========== + +.. tags:: chip:rtl8721dx, arch:arm, vendor:realtek + +.. figure:: PKE8721DAF.png + :scale: 50 % + :align: center + :alt: Realtek PKE8721DAF development board + + The PKE8721DAF development board. + +The PKE8721DAF is a Realtek RTL8721Dx (dual-core Wi-Fi Host Controller) +development board. NuttX runs on the KM4 (Cortex-M33) application core as the +Wi-Fi host; the KM0 network processor runs the prebuilt vendor Wi-Fi firmware. +See the :doc:`RTL8721Dx chip documentation <../../index>` for the SoC +architecture, memory map and vendor-SDK dependency. + +Features +======== + +* RTL8721Dx dual-core Wi-Fi Host Controller (KM4 Cortex-M33 host + KM0 NP) +* 2.4 GHz Wi-Fi (station and SoftAP) +* SPI NOR flash (shared with the NP, 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), backing the Wi-Fi key-value store +* Wi-Fi station and SoftAP through the ``wapi`` tool +* DHCP client (STA) and DHCP server (SoftAP) + +.. note:: + + The Wi-Fi MAC/PHY is driven by the prebuilt vendor firmware on the KM0 + network processor. NuttX is the Wi-Fi host and exchanges frames with the NP + over the on-chip IPC transport; see the chip documentation. + +Buttons and LEDs +================ + +This NuttX port does not wire any user buttons or LEDs. + +Configurations +============== + +.. code:: console + + $ ./tools/configure.sh pke8721daf:<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``. + +Building and Flashing +===================== + +The build auto-fetches the Realtek ``ameba-rtos`` SDK on first use and a +Realtek ``arm-none-eabi`` toolchain must be on ``PATH``; see the +:doc:`chip documentation <../../index>` for both. + +.. code:: console + + $ ./tools/configure.sh pke8721daf:nsh + $ make + +This produces ``nuttx/app.bin`` (the NuttX KM4 image2), ``boot.bin`` and the +NP (KM0) image in the build directory. + +After a successful build, flash via one of these methods: + +**CLI (Linux/macOS)** — connect a USB-UART adapter (PL2303) and use the +built-in ``make flash`` target: + +.. code:: console + + $ make flash AMEBA_PORT=/dev/ttyUSB0 + +The baud rate defaults to 1500000; override with ``AMEBA_BAUD`` if needed. + +**GUI (Windows)** — use the Realtek AmebaImageTool (``AmebaImageTool.exe`` +under ``tools/ameba/ImageTool/`` in the SDK tree) to select ``boot.bin`` and +``app.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 + +Other tools: ``screen /dev/ttyUSB0 1500000`` or ``minicom -b 1500000 -D /dev/ttyUSB0``. + +License Exceptions +================== + +This board depends on Realtek vendor code that is not part of NuttX and is +subject to its own license: + +* The prebuilt KM0 (NP) Wi-Fi 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/rtl8721dx/index.rst b/Documentation/platforms/arm/rtl8721dx/index.rst new file mode 100644 index 00000000000..56c0c120b77 --- /dev/null +++ b/Documentation/platforms/arm/rtl8721dx/index.rst @@ -0,0 +1,61 @@ +================= +Realtek RTL8721Dx +================= + +The Realtek RTL8721Dx is a dual-core Wi-Fi Host Controller (WHC) SoC: + +- **KM4** — an ARM Cortex-M33 (ARMv8-M.main, with FPU) application/host core. + NuttX runs here. +- **KM0** — the network-processor (NP) core that owns the Wi-Fi MAC/PHY and + runs a prebuilt vendor firmware image. + +NuttX is the Wi-Fi *host*: it talks to the NP over the on-chip IPC transport +(WHC, ``WHC_HOST`` + ``WHC_INTF_IPC``) while the NP drives the radio. The +IC-agnostic glue (os_wrapper backend, netdev, key-value store, flash MTD, WHC +Wi-Fi glue) is shared from ``arch/arm/src/common/ameba`` with the other Ameba +WHC parts; only the register-level drivers are IC-specific. + +Memory Map +========== + +============ ============= ====== +Block Name Start Address Length +============ ============= ====== +SRAM (KM4) 0x20020000 288K +============ ============= ====== + +The KM4 image2 RAM window is a slice of the on-chip SRAM; the flash is a SPI +NOR accessed via the SDK XIP path and shared with the NP. + +Vendor SDK Dependency +===================== + +The build depends on Realtek's open ``ameba-rtos`` SDK, which is **not** part +of the NuttX tree. The first build auto-fetches the pinned revision (a shallow +``git clone`` of ``https://gitee.com/ameba-aiot/ameba-rtos.git``) into +``arch/arm/src/common/ameba/ameba-rtos`` (git-ignored) and applies the +out-of-SDK build patch under ``arch/arm/src/common/ameba/patches``. To use a +local checkout instead of auto-fetching, export ``AMEBA_SDK`` to its path. + +A matching Realtek ARM toolchain (``arm-none-eabi`` from the Realtek asdk +release) is required; NuttX links its own libc/libm and reuses the SDK's +``app_start()`` as the image2 entry point. + +Supported Features +================== + +- NSH over the LOG-UART console +- littlefs persistent storage at ``/data`` on the SPI NOR (a dedicated flash + partition), backing the Wi-Fi key-value store +- Wi-Fi STA (scan / connect) and SoftAP via the ``wapi`` tool +- Networking (lwIP-free: NuttX's own TCP/IP stack over the WHC netdev), + DHCP client and DHCP server + +Boards +====== + +.. toctree:: + :glob: + :maxdepth: 1 + + boards/*/*
