boards/arm/ht32f491x3: Add support for the HT32F49163 Starter Kit board

Documentation/platforms/arm/ht32f491x3/boards/esk32/index.rst

@@ -0,0 +1,177 @@
+==================
+ESK32 (HT32F49163)
+==================
+
+.. tags:: arch:arm, chip:ht32f491x3, chip:ht32f49163, vendor:holtek
+
+The ESK32 is a development board based on the Holtek HT32F49163 MCU.
+The current NuttX port targets the HT32F49163 device used on the
+HT32F49163 development kit and focuses on a working serial-console NSH
+configuration with basic board bring-up.
+
+For additional hardware details, refer to Holtek's
+`HT32F491x3 Starter Kit User Guide <https://www.holtek.com/webapi/106680/HT32F491x3_StarterKitUserManualv100.pdf>`_.
+
+.. figure:: ht32f491x3-starter-kit.jpg
+   :align: center
+   :alt: HT32F491x3 Starter Kit
+
+   HT32F491x3 Starter Kit board photo
+
+Features
+========
+
+The current port provides:
+
+* Holtek HT32F49163 MCU from the HT32F491x3 family
+* ARM Cortex-M4 core with FPU support
+* Boot and clock initialization for the ESK32 8 MHz external crystal
+* System clock configured to 150 MHz
+* USART1 serial console at 115200 8N1
+* ``/bin`` mounted through ``binfs``
+* ``/proc`` mounted through ``procfs``
+* User LED registration through ``/dev/userleds``
+* Basic internal GPIO helpers used by the console and LED support
+
+The default ``esk32:nsh`` configuration also enables these built-in
+applications:
+
+* ``hello``
+* ``ostest``
+* ``dumpstack``
+* ``leds``
+
+Buttons and LEDs
+================
+
+Board LEDs
+----------
+
+Three user LEDs from the development kit are currently mapped by the board
+port. They are active-low and are exposed through the standard NuttX
+``USERLED`` interface and the ``/dev/userleds`` device.
+
+===== =========== ==========
+LED   Port/Pin    Notes
+===== =========== ==========
+LED2  PD13        Active-low
+LED3  PD14        Active-low
+LED4  PD15        Active-low
+===== =========== ==========
+
+The generic ``leds`` example from ``nuttx-apps`` can be used to validate the
+LED interface.
+
+Board Buttons
+-------------
+
+No button is currently exposed by the board port.
+
+Pin Mapping
+===========
+
+The current port uses the following MCU pins:
+
+===== ========== ==========
+Pin   Signal     Notes
+===== ========== ==========
+PA9   USART1_TX  Default serial console TX
+PA10  USART1_RX  Default serial console RX
+PD13  LED2       User LED, active-low
+PD14  LED3       User LED, active-low
+PD15  LED4       User LED, active-low
+===== ========== ==========
+
+Flashing
+========
+
+The board directory includes a helper script for flashing through Holtek's
+Windows OpenOCD package from a WSL-based development environment:
+
+.. code-block:: console
+
+   $ ./boards/arm/ht32f491x3/esk32/tools/flash.sh
+
+The script expects:
+
+* ``nuttx.bin`` already generated in the ``nuttx`` directory
+* Holtek xPack OpenOCD installed under
+  ``C:\Program Files (x86)\Holtek HT32 Series\HT32-IDE\xPack\xpack-openocd-0.11.0-4``
+* an HT32-Link compatible debug connection
+* Holtek xPack OpenOCD can be installed together with the HT32 IDE, available
+  from Holtek's website: `Holtek Downloads <https://www.holtek.com/page/index>`_
+
+Useful options:
+
+.. code-block:: console
+
+   $ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --dry-run
+   $ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --device HT32F49163_100LQFP
+   $ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --openocd-root /mnt/c/path/to/openocd
+
+Testing Notes
+=============
+
+The following commands are useful for validating the current port:
+
+.. code-block:: console
+
+   nsh> hello
+   nsh> ostest
+   nsh> dumpstack
+   nsh> leds
+
+When ``leds`` is executed, the example opens ``/dev/userleds`` and cycles
+through the LED bitmasks supported by the board.
+
+Current Limitations
+===================
+
+The current port is still intentionally small. In particular:
+
+* only the ``nsh`` board configuration is maintained
+* only USART1 routing is described by the board port
+* LEDs are supported, but board buttons are not yet implemented
+* internal GPIO helpers exist, but there is not yet a board-level ``/dev/gpio``
+  test interface in this port
+
+Configurations
+==============
+
+nsh
+---
+
+This is the currently maintained configuration for the board. It provides a
+serial console with the NuttShell and mounts ``/bin`` and ``/proc`` during
+board bring-up.
+
+Configure and build it from the ``nuttx`` directory:
+
+.. code-block:: console
+
+   $ ./tools/configure.sh -l esk32:nsh
+   $ make -j
+
+After boot, a typical prompt looks like:
+
+.. code-block:: console
+
+   NuttShell (NSH) NuttX-12.x.x
+   nsh> ls /
+   /:
+    bin/
+    dev/
+    proc/
+
+And the built-in applications can be listed with:
+
+.. code-block:: console
+
+   nsh> ls /bin
+   dd
+   dumpstack
+   hello
+   leds
+   nsh
+   ostest
+   sh

Documentation/platforms/arm/ht32f491x3/index.rst

@@ -0,0 +1,14 @@
+===============
+Holtek HT32F491
+===============
+
+The HT32F491x3 family is based on the ARM Cortex-M4 core.
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

arch/arm/Kconfig

@@ -779,6 +779,14 @@ config ARCH_CHIP_CXD32XX
 	---help---
 		Sony CXD32XX (ARM Cortex-M4) architectures
 
+config ARCH_CHIP_HT32F491X3
+	bool "Holtek HT32F491x3"
+	select ARCH_CORTEXM4
+	select ARCH_HAVE_FPU
+	select LIBC_ARCH_ATOMIC
+	---help---
+		Holtek HT32F491x3 (ARM Cortex-M4) architectures
+
 config ARCH_CHIP_ARM_CUSTOM
 	bool "Custom ARM chip"
 	select ARCH_CHIP_CUSTOM
@@ -1207,6 +1215,7 @@ config ARCH_CHIP
 	default "goldfish"	if ARCH_CHIP_GOLDFISH_ARM
 	default "at32"		if ARCH_CHIP_AT32
 	default "cxd32xx"	if ARCH_CHIP_CXD32XX
+	default "ht32f491x3"	if ARCH_CHIP_HT32F491X3
 	default "csk6"		if ARCH_CHIP_CSK6
 	default "mcx-nxxx"	if ARCH_CHIP_MCX_NXXX
 
@@ -1748,6 +1757,9 @@ endif
 if ARCH_CHIP_CXD32XX
 source "arch/arm/src/cxd32xx/Kconfig"
 endif
+if ARCH_CHIP_HT32F491X3
+source "arch/arm/src/ht32f491x3/Kconfig"
+endif
 if ARCH_CHIP_MCX_NXXX
 source "arch/arm/src/mcx-nxxx/Kconfig"
 endif

arch/arm/include/ht32f491x3/chip.h

@@ -0,0 +1,69 @@
+/****************************************************************************
+ * arch/arm/include/ht32f491x3/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_HT32F491X3_CHIP_H
+#define __ARCH_ARM_INCLUDE_HT32F491X3_CHIP_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+#define HT32M4_SYSH_PRIORITY_MIN     0xe0
+#define HT32M4_SYSH_PRIORITY_DEFAULT 0x80
+#define HT32M4_SYSH_PRIORITY_MAX     0x00
+#define HT32M4_SYSH_PRIORITY_STEP    0x20
+
+#define NVIC_SYSH_PRIORITY_MIN        HT32M4_SYSH_PRIORITY_MIN
+#define NVIC_SYSH_PRIORITY_DEFAULT    HT32M4_SYSH_PRIORITY_DEFAULT
+#define NVIC_SYSH_PRIORITY_MAX        HT32M4_SYSH_PRIORITY_MAX
+#define NVIC_SYSH_PRIORITY_STEP       HT32M4_SYSH_PRIORITY_STEP
+
+#if defined(CONFIG_ARCH_CHIP_HT32F49153)
+#  define HT32_FLASH_KB 128
+#elif defined(CONFIG_ARCH_CHIP_HT32F49163)
+#  define HT32_FLASH_KB 256
+#else
+#  error "Unsupported HT32F491x3 device"
+#endif
+
+#define HT32_SRAM_KB             48
+#define HT32_NUSART              8
+#define HT32_NGPIO               6
+
+#define HT32_HICK_FREQUENCY       8000000
+#define HT32_HICK48_FREQUENCY     48000000
+#define HT32_HEXT_MIN_FREQUENCY   4000000
+#define HT32_HEXT_MAX_FREQUENCY   25000000
+#define HT32_PLL_MAX_FREQUENCY    150000000
+
+#define HT32_SYSCLK_FREQUENCY CONFIG_HT32F491X3_SYSCLK_FREQUENCY
+#define HT32_HCLK_FREQUENCY   HT32_SYSCLK_FREQUENCY
+#define HT32_PCLK1_FREQUENCY  CONFIG_HT32F491X3_PCLK1_FREQUENCY
+#define HT32_PCLK2_FREQUENCY  CONFIG_HT32F491X3_PCLK2_FREQUENCY
+
+#endif /* __ARCH_ARM_INCLUDE_HT32F491X3_CHIP_H */