This is an automated email from the ASF dual-hosted git repository.
jerpelea pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 727adcd49959f167e6ed2bfaac187612cb0d8f72
Author: Eren Terzioglu <eren.terzio...@espressif.com>
AuthorDate: Tue Jan 23 13:51:44 2024 +0300
Docs/esp: esp32h2 and esp32c6 documentation added
---
.../risc-v/esp32c6/boards/esp32c6-devkit/index.rst | 102 ++++++++++-
Documentation/platforms/risc-v/esp32c6/index.rst | 37 +++-
.../ESP32-H2-DevKitM-1-v1.0-block-diagram.png | Bin 0 -> 1925553 bytes
.../esp32-h2-devkitm-1-isometric.png | Bin 0 -> 3490600 bytes
.../esp32-h2-devkitm-1-pin-layout.png | Bin 0 -> 328480 bytes
.../esp32-h2-devkitm-1-v1.2-annotated-photo.png | Bin 0 -> 360443 bytes
.../risc-v/esp32h2/boards/esp32h2-devkit/index.rst | 201 +++++++++++++++++++++
.../risc-v/{esp32c6 => esp32h2}/index.rst | 77 +++++---
8 files changed, 387 insertions(+), 30 deletions(-)
diff --git
a/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkit/index.rst
b/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkit/index.rst
index 6d038bbb93..6c538e34f9 100644
--- a/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkit/index.rst
+++ b/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).
\ No newline at end of file
+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.
diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst
b/Documentation/platforms/risc-v/esp32c6/index.rst
index f2c4aeeaf7..fe817c1e69 100644
--- a/Documentation/platforms/risc-v/esp32c6/index.rst
+++ b/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
diff --git
a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/ESP32-H2-DevKitM-1-v1.0-block-diagram.png
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/ESP32-H2-DevKitM-1-v1.0-block-diagram.png
new file mode 100644
index 0000000000..6b87d1162e
Binary files /dev/null and
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/ESP32-H2-DevKitM-1-v1.0-block-diagram.png
differ
diff --git
a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-isometric.png
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-isometric.png
new file mode 100644
index 0000000000..974c61b144
Binary files /dev/null and
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-isometric.png
differ
diff --git
a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-pin-layout.png
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-pin-layout.png
new file mode 100644
index 0000000000..1e326e6d01
Binary files /dev/null and
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-pin-layout.png
differ
diff --git
a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-v1.2-annotated-photo.png
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-v1.2-annotated-photo.png
new file mode 100644
index 0000000000..208ff02f2c
Binary files /dev/null and
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/esp32-h2-devkitm-1-v1.2-annotated-photo.png
differ
diff --git
a/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/index.rst
b/Documentation/platforms/risc-v/esp32h2/boards/esp32h2-devkit/index.rst
new file mode 100644
index 0000000000..6ebf5fd76e
--- /dev/null
+++ b/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.
diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst
b/Documentation/platforms/risc-v/esp32h2/index.rst
similarity index 70%
copy from Documentation/platforms/risc-v/esp32c6/index.rst
copy to Documentation/platforms/risc-v/esp32h2/index.rst
index f2c4aeeaf7..14000de002 100644
--- a/Documentation/platforms/risc-v/esp32c6/index.rst
+++ b/Documentation/platforms/risc-v/esp32h2/index.rst
@@ -1,32 +1,32 @@
==================
-Espressif ESP32-C6
+Espressif ESP32-H2
==================
-The ESP32-C6 is an ultra-low-power and highly integrated SoC with a RISC-V
-core and supports 2.4 GHz Wi-Fi 6, Bluetooth 5 (LE) and the 802.15.4 protocol.
+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
- - 800 KB of internal memory address space accessed from the instruction bus
- - 560 KB of internal memory address space accessed from the data bus
- - 1016 KB of peripheral address space
- - 8 MB of external memory virtual address space accessed from the
instruction bus
- - 8 MB of external memory virtual address space accessed from the data bus
- - 480 KB of internal DMA 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
- - 320 KB ROM
- - 512 KB SRAM (16 KB can be configured as Cache)
- - 16 KB of SRAM in RTC
+ - 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
- - 35 peripherals
+ - Multiple peripherals
* GDMA
- 7 modules are capable of DMA operations.
-ESP32-C6 Toolchain
+ESP32-H2 Toolchain
==================
-A generic RISC-V toolchain can be used to build ESP32-C6 projects. It's
recommended to use the same
+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:
@@ -77,7 +77,7 @@ 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-esp32c6.bin`` and ``partition-table-esp32c6.bin`` and
place them
+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``
@@ -85,15 +85,15 @@ Building and flashing
=====================
First make sure that ``esptool.py`` is installed. This tool is used to convert
-the ELF to a compatible ESP32-C6 image and to flash the image into the board.
+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 esp32c6-devkit:nsh``
+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 esp32c6 --port /dev/ttyUSBXX --baud 921600 write_flash
0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin
+ 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::
@@ -101,11 +101,40 @@ However, this is also included in the build process and
we can build and flash w
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-C6 as explained above.
+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
==================
@@ -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
