mirror of
https://github.com/apache/nuttx.git
synced 2026-08-09 14:35:08 +00:00
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 <raul_chen@realsil.com.cn>
This commit is contained in:
raul_chen
Alan C. Assis
parent
7355393fcd
commit
76838fa1b2
5 changed files with 384 additions and 0 deletions
|
|
@ -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.
|
||||
62
Documentation/platforms/arm/rtl8720f/index.rst
Normal file
62
Documentation/platforms/arm/rtl8720f/index.rst
Normal file
|
|
@ -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/*/*
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.3 MiB |
|
|
@ -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.
|
||||
61
Documentation/platforms/arm/rtl8721dx/index.rst
Normal file
61
Documentation/platforms/arm/rtl8721dx/index.rst
Normal file
|
|
@ -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/*/*
|
||||
Loading…
Add table
Add a link
Reference in a new issue