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 6d038bbb932..6c538e34f91 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 `_. +`here `_. 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 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 f2c4aeeaf70..fe817c1e698 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 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 00000000000..6b87d1162e4 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 00000000000..974c61b144d 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 00000000000..1e326e6d011 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 00000000000..208ff02f2cc 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 00000000000..6ebf5fd76ef --- /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 `_. + +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: + $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j + +Where 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 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/esp32h2/index.rst b/Documentation/platforms/risc-v/esp32h2/index.rst new file mode 100644 index 00000000000..14000de0029 --- /dev/null +++ b/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 `_ 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= ESPTOOL_BINDIR=../esp-bins + +Where ```` 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 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/*/*