Docs/esp: esp32h2 and esp32c6 documentation added

Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkit/index.rst

@@ -5,7 +5,7 @@ ESP32-C6-DevKitC-1
 ESP32-C6-DevKitC-1 is an entry-level development board based on ESP32-C6-WROOM-1(U),
 a general-purpose module with a 8 MB SPI flash. This board integrates complete Wi-Fi,
 Bluetooth LE, Zigbee, and Thread functions. You can find the board schematic
-`here <https://espressif-docs.readthedocs-hosted.com/projects/espressif-esp-dev-kits/en/latest/_static/esp32-c6-devkitc-1/schematics/esp32-c6-devkitc-1-schematics_v1.2.pdf>`_.
+`here <https://espressif-docs.readthedocs-hosted.com/projects/esp-dev-kits/en/latest/_static/esp32-c6-devkitc-1/schematics/esp32-c6-devkitc-1-schematics_v1.2.pdf>`_.
 
 Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing.
 Developers can either connect peripherals with jumper wires or mount ESP32-C6-DevKitC-1 on
@@ -98,7 +98,105 @@ disables the NuttShell to get the best possible score.
 .. note:: As the NSH is disabled, the application will start as soon as the
   system is turned on.
 
+gpio
+----
+
+This is a test for the GPIO driver. It uses GPIO1 and GPIO2 as outputs and
+GPIO9 as an interrupt pin.
+
+At the nsh, we can turn the outputs on and off with the following::
+
+    nsh> gpio -o 1 /dev/gpio0
+    nsh> gpio -o 1 /dev/gpio1
+
+    nsh> gpio -o 0 /dev/gpio0
+    nsh> gpio -o 0 /dev/gpio1
+
+We can use the interrupt pin to send a signal when the interrupt fires::
+
+    nsh> gpio -w 14 /dev/gpio2
+
+The pin is configured as a rising edge interrupt, so after issuing the
+above command, connect it to 3.3V.
+
 nsh
 ---
 
-Basic configuration to run the NuttShell (nsh).
+Basic configuration to run the NuttShell (nsh).
+
+ostest
+------
+
+This is the NuttX test at ``apps/testing/ostest`` that is run against all new
+architecture ports to assure a correct implementation of the OS.
+
+pwm
+---
+
+This configuration demonstrates the use of PWM through a LED connected to GPIO8.
+To test it, just execute the ``pwm`` application::
+
+    nsh> pwm
+    pwm_main: starting output with frequency: 10000 duty: 00008000
+    pwm_main: stopping output
+
+rtc
+---
+
+This configuration demonstrates the use of the RTC driver through alarms.
+You can set an alarm, check its progress and receive a notification after it expires::
+
+    nsh> alarm 10
+    alarm_daemon started
+    alarm_daemon: Running
+    Opening /dev/rtc0
+    Alarm 0 set in 10 seconds
+    nsh> alarm -r
+    Opening /dev/rtc0
+    Alarm 0 is active with 10 seconds to expiration
+    nsh> alarm_daemon: alarm 0 received
+
+sotest
+------
+
+This config is to run apps/examples/sotest.
+
+timer
+-----
+
+This config test the general use purpose timers. It includes the 4 timers,
+adds driver support, registers the timers as devices and includes the timer
+example.
+
+To test it, just run the following::
+
+  nsh> timer -d /dev/timerx
+
+Where x in the timer instance.
+
+usbconsole
+----------
+
+This configuration tests the built-in USB-to-serial converter found in ESP32-C6.
+``esptool`` can be used to check the version of the chip and if this feature is
+supported.  Running ``esptool.py -p <port> chip_id`` should have ``Chip is
+ESP32-C6`` in its output.
+When connecting the board a new device should appear, a ``/dev/ttyACMX`` on Linux
+or a ``/dev/cu.usbmodemXXX`` om macOS.
+This can be used to flash and monitor the device with the usual commands::
+
+    make download ESPTOOL_PORT=/dev/ttyACM0
+    minicom -D /dev/ttyACM0
+
+watchdog
+--------
+
+This configuration tests the watchdog timers. It includes the 1 MWDTS,
+adds driver support, registers the WDTs as devices and includes the watchdog
+example application.
+
+To test it, just run the following command::
+
+    nsh> wdog -i /dev/watchdogX
+
+Where X is the watchdog instance.

Documentation/platforms/risc-v/esp32c6/index.rst

@@ -106,6 +106,35 @@ Note that this step is required only one time.  Once the bootloader and partitio
 table are flashed, we don't need to flash them again.  So subsequent builds
 would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX``
 
+Debugging with OpenOCD
+======================
+
+Download and build OpenOCD from Espressif, that can be found in
+https://github.com/espressif/openocd-esp32
+
+You don not need an external JTAG is to debug, the ESP32-C6 integrates a
+USB-to-JTAG adapter.
+
+OpenOCD can then be used::
+
+   openocd -c 'set ESP_RTOS none' -f board/esp32c6-builtin.cfg
+
+If you want to debug with an external JTAG adapter it can
+be connected as follows::
+
+  TMS -> GPIO4
+  TDI -> GPIO5
+  TCK -> GPIO6
+  TDO -> GPIO7
+
+Furthermore, an efuse needs to be burnt to be able to debug::
+
+  espefuse.py -p <port> burn_efuse DIS_USB_JTAG
+
+OpenOCD can then be used::
+
+  openocd  -c 'set ESP_RTOS none' -f board/esp32c6-ftdi.cfg
+
 Peripheral Support
 ==================
 
@@ -121,25 +150,25 @@ CAN/TWAI         No
 DMA              No
 ECC              No
 eFuse            No
-GPIO             No
+GPIO             Yes
 HMAC             No
 I2C              No
 I2S              No
 Int. Temp.       No
 LED              No
-LED_PWM          No
+LED_PWM          Yes
 MCPWM            No
 Pulse Counter    No
 RMT              No
 RNG              No
 RSA              No
-RTC              No
+RTC              Yes
 SD/MMC           No
 SDIO             No
 SHA              No
 SPI              No
 SPIFLASH         No
-Timers           No
+Timers           Yes
 UART             Yes
 Watchdog         Yes
 Wifi             No

Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/index.rst

@@ -0,0 +1,201 @@
+==================
+ESP32-H2-DevKitM-1
+==================
+
+ESP32-H2-DevKitM-1 is an entry-level development board based on Bluetooth® Low Energy and
+IEEE 802.15.4 combo module ESP32-H2-MINI-1 or ESP32-H2-MINI-1U. You can find the board schematic
+`here <https://espressif-docs.readthedocs-hosted.com/projects/esp-dev-kits/en/latest/_static/esp32-h2-devkitm-1/esp32-h2-devkitm-1_v1.2_schematics_20230306.pdf>`_.
+
+Most of the I/O pins on the ESP32-H2-MINI-1/1U module are broken out to the pin headers on 
+both sides of this board for easy interfacing. Developers can either connect peripherals with
+jumper wires or mount ESP32-H2-DevKitM-1 on a breadboard.
+
+.. figure:: esp32-h2-devkitm-1-isometric.png
+    :alt: ESP32-H2-DevKitM-1 Board Layout
+    :figclass: align-center
+
+    ESP32-H2-DevKitM-1 Board Layout
+
+The block diagram below presents main components of the ESP32-H2-DevKitM-1.
+
+.. figure:: ESP32-H2-DevKitM-1-v1.0-block-diagram.png
+    :alt: ESP32-H2-DevKitM-1 Electrical Block Diagram
+    :figclass: align-center
+
+    ESP32-H2-DevKitM-1 Electrical Block Diagram
+
+Hardware Components
+-------------------
+
+.. figure:: esp32-h2-devkitm-1-v1.2-annotated-photo.png
+    :alt: ESP32-H2-DevKitM-1 Hardware Components
+    :figclass: align-center
+
+    ESP32-H2-DevKitM-1 Hardware Components
+
+Buttons and LEDs
+================
+
+Board Buttons
+--------------
+There are two buttons labeled Boot and RST. The RST button is not available
+to software. It pulls the chip enable line that doubles as a reset line.
+
+The BOOT button is connected to IO9. On reset it is used as a strapping
+pin to determine whether the chip boots normally or into the serial
+bootloader. After reset, however, the BOOT button can be used for software
+input.
+
+Board LEDs
+----------
+
+There is one on-board LED that indicates the presence of power.
+Another WS2812 LED is connected to GPIO8 and is available for software.
+
+Current Measurement
+===================
+
+The J5 headers on ESP32-H2-DevKitM-1 can be used for measuring the current
+drawn by the ESP32-H2-MINI-1/1U module:
+
+    - Remove the jumper: Power supply between the module and peripherals on the
+      board is cut off. To measure the module's current, connect the board with an
+      ammeter via J5 headers;
+    - Apply the jumper (factory default): Restore the board's normal functionality.
+
+.. note::
+    When using 3V3 and GND pin headers to power the board, please remove the J5 jumper,
+    and connect an ammeter in series to the external circuit to measure the module's current.
+
+Pin Mapping
+===========
+
+.. figure:: esp32-h2-devkitm-1-pin-layout.png
+    :alt: ESP32-H2-DevKitM-1 pin layout
+    :figclass: align-center
+
+    ESP32-H2-DevKitM-1 Pin Layout
+
+Configurations
+==============
+
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32h2-devkit:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
+coremark
+--------
+
+This configuration sets the CoreMark benchmark up for running on the maximum
+number of cores for this system. It also enables some optimization flags and
+disables the NuttShell to get the best possible score.
+
+.. note:: As the NSH is disabled, the application will start as soon as the
+  system is turned on.
+
+gpio
+----
+
+This is a test for the GPIO driver. It uses GPIO1 and GPIO2 as outputs and
+GPIO9 as an interrupt pin.
+
+At the nsh, we can turn the outputs on and off with the following::
+
+    nsh> gpio -o 1 /dev/gpio0
+    nsh> gpio -o 1 /dev/gpio1
+
+    nsh> gpio -o 0 /dev/gpio0
+    nsh> gpio -o 0 /dev/gpio1
+
+We can use the interrupt pin to send a signal when the interrupt fires::
+
+    nsh> gpio -w 14 /dev/gpio2
+
+The pin is configured as a rising edge interrupt, so after issuing the
+above command, connect it to 3.3V.
+
+nsh
+---
+
+Basic configuration to run the NuttShell (nsh).
+
+ostest
+------
+
+This is the NuttX test at ``apps/testing/ostest`` that is run against all new
+architecture ports to assure a correct implementation of the OS.
+
+pwm
+---
+
+This configuration demonstrates the use of PWM through a LED connected to GPIO8.
+To test it, just execute the ``pwm`` application::
+
+    nsh> pwm
+    pwm_main: starting output with frequency: 10000 duty: 00008000
+    pwm_main: stopping output
+
+rtc
+---
+
+This configuration demonstrates the use of the RTC driver through alarms.
+You can set an alarm, check its progress and receive a notification after it expires::
+
+    nsh> alarm 10
+    alarm_daemon started
+    alarm_daemon: Running
+    Opening /dev/rtc0
+    Alarm 0 set in 10 seconds
+    nsh> alarm -r
+    Opening /dev/rtc0
+    Alarm 0 is active with 10 seconds to expiration
+    nsh> alarm_daemon: alarm 0 received
+
+sotest
+------
+
+This config is to run apps/examples/sotest.
+
+timer
+-----
+
+This config test the general use purpose timers. It includes the 4 timers,
+adds driver support, registers the timers as devices and includes the timer
+example.
+
+To test it, just run the following::
+
+  nsh> timer -d /dev/timerx
+
+Where x in the timer instance.
+
+usbconsole
+----------
+
+This configuration tests the built-in USB-to-serial converter found in ESP32-H2.
+``esptool`` can be used to check the version of the chip and if this feature is
+supported.  Running ``esptool.py -p <port> chip_id`` should have ``Chip is
+ESP32-H2`` in its output.
+When connecting the board a new device should appear, a ``/dev/ttyACMX`` on Linux
+or a ``/dev/cu.usbmodemXXX`` om macOS.
+This can be used to flash and monitor the device with the usual commands::
+
+    make download ESPTOOL_PORT=/dev/ttyACM0
+    minicom -D /dev/ttyACM0
+
+watchdog
+--------
+
+This configuration tests the watchdog timers. It includes the 1 MWDTS,
+adds driver support, registers the WDTs as devices and includes the watchdog
+example application.
+
+To test it, just run the following command::
+
+    nsh> wdog -i /dev/watchdogX
+
+Where X is the watchdog instance.

Documentation/platforms/risc-v/esp32h2/index.rst

@@ -0,0 +1,185 @@
+==================
+Espressif ESP32-H2
+==================
+
+The ESP32-H2 is an ultra-low-power and highly integrated SoC with a RISC-V
+core and supports 2.4 GHz transceiver, Bluetooth 5 (LE) and the 802.15.4 protocol.
+
+* Address Space
+  - 452 KB of internal memory address space accessed from the instruction bus
+  - 452 KB of internal memory address space accessed from the data bus
+  - 832 KB of peripheral address space
+  - 16 MB of external memory virtual address space accessed from the instruction bus
+  - 16 MB of external memory virtual address space accessed from the data bus
+  - 260 KB of internal DMA address space
+* Internal Memory
+  - 128 KB ROM
+  - 320 KB SRAM (16 KB can be configured as Cache)
+  - 4 KB of SRAM in RTC
+* External Memory
+  - Up to 16 MB of external flash
+* Peripherals
+  - Multiple peripherals
+* GDMA
+  - 7 modules are capable of DMA operations.
+
+ESP32-H2 Toolchain
+==================
+
+A generic RISC-V toolchain can be used to build ESP32-H2 projects. It's recommended to use the same
+toolchain used by NuttX CI. Please refer to the Docker
+`container <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ and
+check for the current compiler version being used. For instance:
+
+.. code-block::
+
+   ###############################################################################
+   # Build image for tool required by RISCV builds
+   ###############################################################################
+   FROM nuttx-toolchain-base AS nuttx-toolchain-riscv
+   # Download the latest RISCV GCC toolchain prebuilt by xPack
+   RUN mkdir riscv-none-elf-gcc && \
+   curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \
+   | tar -C riscv-none-elf-gcc --strip-components 1 -xz
+
+It uses the xPack's prebuilt toolchain based on GCC 12.3.0.
+
+Installing
+----------
+
+First, create a directory to hold the toolchain:
+
+.. code-block:: console
+
+   $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc
+
+Download and extract toolchain:
+
+.. code-block:: console
+
+   $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v12.3.0-2/xpack-riscv-none-elf-gcc-12.3.0-2-linux-x64.tar.gz" \
+   | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz
+
+Add the toolchain to your `PATH`:
+
+.. code-block:: console
+
+   $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc
+
+You can edit your shell's rc files if you don't use bash.
+
+Second stage bootloader and partition table
+===========================================
+
+The NuttX port for now relies on IDF's second stage bootloader to carry on some hardware
+initializations.  The binaries for the bootloader and the partition table can be found in
+this repository: https://github.com/espressif/esp-nuttx-bootloader
+That repository contains a dummy IDF project that's used to build the bootloader and
+partition table, these are then presented as Github assets and can be downloaded
+from: https://github.com/espressif/esp-nuttx-bootloader/releases
+Download ``bootloader-esp32h2.bin`` and ``partition-table-esp32h2.bin`` and place them
+in a folder, the path to this folder will be used later to program them. This
+can be: ``../esp-bins``
+
+Building and flashing
+=====================
+
+First make sure that ``esptool.py`` is installed.  This tool is used to convert
+the ELF to a compatible ESP32-H2 image and to flash the image into the board.
+It can be installed with: ``pip install esptool``.
+
+Configure the NuttX project: ``./tools/configure.sh esp32h2-devkit:nsh``
+Run ``make`` to build the project.  Note that the conversion mentioned above is
+included in the build process.
+The ``esptool.py`` command to flash all the binaries is::
+
+     esptool.py --chip esp32h2 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin
+
+However, this is also included in the build process and we can build and flash with::
+
+   make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
+
+Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is
+the path to the folder containing the bootloader and the partition table
+for the ESP32-H2 as explained above.
+Note that this step is required only one time.  Once the bootloader and partition
+table are flashed, we don't need to flash them again.  So subsequent builds
+would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX``
+
+Debugging with OpenOCD
+======================
+
+Download and build OpenOCD from Espressif, that can be found in
+https://github.com/espressif/openocd-esp32
+
+You don not need an external JTAG is to debug, the ESP32-H2 integrates a
+USB-to-JTAG adapter.
+
+OpenOCD can then be used::
+
+   openocd -c 'set ESP_RTOS none' -f board/esp32h2-builtin.cfg
+
+If you want to debug with an external JTAG adapter it can
+be connected as follows::
+
+  TMS -> GPIO2
+  TDI -> GPIO5
+  TCK -> GPIO5
+  TDO -> GPIO3
+
+Furthermore, an efuse needs to be burnt to be able to debug::
+
+  espefuse.py -p <port> burn_efuse DIS_USB_JTAG
+
+OpenOCD can then be used::
+
+  openocd  -c 'set ESP_RTOS none' -f board/esp32h2-ftdi.cfg
+
+Peripheral Support
+==================
+
+The following list indicates the state of peripherals' support in NuttX:
+
+==============  =======
+Peripheral      Support
+==============  =======
+ADC              No
+AES              No
+Bluetooth        No
+CAN/TWAI         No
+DMA              No
+ECC              No
+eFuse            No
+GPIO             Yes
+HMAC             No
+I2C              No
+I2S              No
+Int. Temp.       No
+LED              No
+LED_PWM          Yes
+MCPWM            No
+Pulse Counter    No
+RMT              No
+RNG              No
+RSA              No
+RTC              Yes
+SD/MMC           No
+SDIO             No
+SHA              No
+SPI              No
+SPIFLASH         No
+Timers           Yes
+UART             Yes
+Watchdog         Yes
+Wifi             No
+XTS              No
+==============  =======
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*