diff --git a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst index ad585da475d..4fdee90272e 100644 --- a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst +++ b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst @@ -1,5 +1,6 @@ .. note:: A new approach is being adopted for this chip and this implementation will be deprecated when the same support level is achieved. + For the new approach please check :ref:`here`. =========================== Espressif ESP32-C3 (Legacy) diff --git a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitC-02-v1.1.png b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitC-02-v1.1.png new file mode 100644 index 00000000000..88a89947554 Binary files /dev/null and b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitC-02-v1.1.png differ diff --git a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitM-1-v1.0.png b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitM-1-v1.0.png new file mode 100644 index 00000000000..ad0c387cc73 Binary files /dev/null and b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/ESP32-C3-DevKitM-1-v1.0.png differ diff --git a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst new file mode 100644 index 00000000000..11d96d1ee83 --- /dev/null +++ b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst @@ -0,0 +1,167 @@ +================ +ESP32-C3 DevKit +================ + +The ESP32-C3 DevKit is an entry-level development board equipped with either +an ESP32-C3-WROOM-02 or an ESP32-C3-MINI-1. +ESP32-C3-WROOM-02 and ESP32-C3-MINI-1 are SoMs based on the RISC-V ESP32-C3 CPU. + +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-C3 DevKit on a breadboard. + +.. list-table:: + :align: center + + * - .. figure:: ESP32-C3-DevKitC-02-v1.1.png + :align: center + + ESP32-C3-DevKitC-02 + + - .. figure:: ESP32-C3-DevKitM-1-v1.0.png + :align: center + + ESP32-C3-DevKitM-1 + +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. + +Configurations +============== + +All of the configurations presented below can be tested by running the following commands:: + + $ ./tools/configure.sh esp32c3-generic: + $ 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 GPIO2. +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-C3 (revision 3). +``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-C3 (revision 3)`` 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 2 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/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst new file mode 100644 index 00000000000..6902bd4a543 --- /dev/null +++ b/Documentation/platforms/risc-v/esp32c3/index.rst @@ -0,0 +1,285 @@ +.. _esp32c3: + +================== +Espressif ESP32-C3 +================== + +The ESP32-C3 is an ultra-low-power and highly integrated SoC with a RISC-V +core and supports 2.4 GHz Wi-Fi and Bluetooth Low Energy. + +* 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 +* Internal Memory + - 384 KB ROM + - 400 KB SRAM (16 KB can be configured as Cache) + - 8 KB of SRAM in RTC +* External Memory + - Up to 16 MB of external flash +* Peripherals + - 35 peripherals +* GDMA + - 7 modules are capable of DMA operations. + +ESP32-C3 Toolchain +================== + +A generic RISC-V toolchain can be used to build ESP32-C3 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-esp32c3.bin`` and ``partition-table-esp32c3.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 image and to flash the image into the board. +It can be installed with: ``pip install esptool``. + +Configure the NuttX project: ``./tools/configure.sh esp32c3-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 esp32c3 --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-C3 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 + +If you have an ESP32-C3 ECO3, no external JTAG is required to debug, the ESP32-C3 +integrates a USB-to-JTAG adapter. + +OpenOCD can then be used:: + + openocd -c 'set ESP_RTOS none' -f board/esp32c3-builtin.cfg + +For versions prior to ESP32-C3 ECO3, an external JTAG adapter is needed. +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/esp32c3-ftdi.cfg + +Peripheral Support +================== + +The following list indicates the state of peripherals' support in NuttX: + +=========== ======= ===== +Peripheral Support NOTES +=========== ======= ===== +ADC No +AES No +Bluetooth No +CDC Console Yes Rev.3 +DMA No +eFuse No +GPIO Yes +I2C No +LED_PWM Yes +RNG No +RSA No +RTC Yes +SHA No +SPI No +SPIFLASH No +Timers Yes +Touch No +UART Yes +Watchdog Yes +Wifi No +=========== ======= ===== + +Secure Boot and Flash Encryption +================================ + +Secure Boot +----------- + +Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that +each piece of software that is being booted is signed. On an ESP32-C3, these pieces of software include +the second stage bootloader and each application binary. Note that the first stage bootloader does not +require signing as it is ROM code thus cannot be changed. This is achieved using specific hardware in +conjunction with MCUboot (read more about MCUboot `here `__). + +The Secure Boot process on the ESP32-C3 involves the following steps performed: + +1. The first stage bootloader verifies the second stage bootloader's RSA-PSS signature. If the verification is successful, + the first stage bootloader loads and executes the second stage bootloader. + +2. When the second stage bootloader loads a particular application image, the application's signature (RSA, ECDSA or ED25519) is verified + by MCUboot. + If the verification is successful, the application image is executed. + +.. warning:: Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only boot an + application firmware image if it has a verified digital signature. There are implications for reflashing + updated images once Secure Boot is enabled. You can find more information about the ESP32-C3's Secure boot + `here `__. + +.. note:: As the bootloader image is built on top of the Hardware Abstraction Layer component + of `ESP-IDF `_, the + `API port by Espressif `_ will be used + by MCUboot rather than the original NuttX port. + +Flash Encryption +---------------- + +Flash encryption is intended for encrypting the contents of the ESP32-C3's off-chip flash memory. Once this feature is enabled, +firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout +of flash will not be sufficient to recover most flash contents. + +.. warning:: After enabling Flash Encryption, an encryption key is generated internally by the device and + cannot be accessed by the user for re-encrypting data and re-flashing the system, hence it will be permanently encrypted. + Re-flashing an encrypted system is complicated and not always possible. You can find more information about the ESP32-C3's Flash Encryption + `here `__. + +Prerequisites +------------- + +First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary +images) and ``esptool`` (the ESP32-C3 toolkit):: + + $ pip install imgtool esptool + +We also need to make sure that the python modules are added to ``PATH``:: + + $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc + +Now, we will create a folder to store the generated keys (such as ``~/signing_keys``):: + + $ mkdir ~/signing_keys && cd ~/signing_keys + +With all set up, we can now generate keys to sign the bootloader and application binary images, +respectively, of the compiled project:: + + $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem + $ imgtool keygen --key app_signing_key.pem --type rsa-3072 + +.. important:: The contents of the key files must be stored securely and kept secret. + +Enabling Secure Boot and Flash Encryption +----------------------------------------- + +To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps: + + 1. Enable experimental features in :menuselection:`Build Setup --> Show experimental options`; + + 2. Enable MCUboot in :menuselection:`Application Configuration --> Bootloader Utilities --> MCUboot`; + + 3. Change image type to ``MCUboot-bootable format`` in :menuselection:`System Type --> Application Image Configuration --> Application Image Format`; + + 4. Enable building MCUboot from the source code by selecting ``Build binaries from source``; + in :menuselection:`System Type --> Application Image Configuration --> Source for bootloader binaries`; + + 5. Enable Secure Boot in :menuselection:`System Type --> Application Image Configuration --> Enable hardware Secure Boot in bootloader`; + + 6. If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in + :menuselection:`System Type --> Application Image Configuration --> Enable Flash Encryption on boot`. + +Now you can design an update and confirm agent to your application. Check the `MCUboot design guide `_ and the +`MCUboot Espressif port documentation `_ for +more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port `_, +the `MCUboot porting guide `_ and some +`examples of MCUboot applied in Nuttx applications `_. + +After you developed an application which implements all desired functions, you need to flash it into the primary image slot +of the device (it will automatically be in the confirmed state, you can learn more about image +confirmation `here `_). +To flash to the primary image slot, select ``Application image primary slot`` in +:menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing` +and compile it using ``make -j ESPSEC_KEYDIR=~/signing_keys``. + +When creating update images, make sure to change :menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing` +to ``Application image secondary slot``. + +.. important:: When deploying your application, make sure to disable UART Download Mode by selecting ``Permanently disabled`` in + :menuselection:`System Type --> Application Image Configuration --> UART ROM download mode` + and change usage mode to ``Release`` in `System Type --> Application Image Configuration --> Enable usage mode`. + **After disabling UART Download Mode you will not be able to flash other images through UART.** + + +Supported Boards +================ + +.. toctree:: + :glob: + :maxdepth: 1 + + boards/*/*