diff --git a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst index 415b363d84..074d86919f 100644 --- a/Documentation/platforms/risc-v/esp32c3-legacy/index.rst +++ b/Documentation/platforms/risc-v/esp32c3-legacy/index.rst @@ -259,7 +259,7 @@ Now you can design an update and confirm agent to your application. Check the `M `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 `_. +`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 diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst index 16daf38f8d..642c02dfe6 100644 --- a/Documentation/platforms/risc-v/esp32c3/index.rst +++ b/Documentation/platforms/risc-v/esp32c3/index.rst @@ -70,12 +70,15 @@ Add the toolchain to your `PATH`: You can edit your shell's rc files if you don't use bash. -Second stage bootloader -======================= +Building and flashing NuttX +=========================== -Nuttx can boot the ESP32-C3 directly using the so-called "Simple Boot". +Bootloader and partitions +------------------------- + +NuttX can boot the ESP32-C3 directly using the so-called "Simple Boot". An externally-built 2nd stage bootloader is not required in this case as all -functions required to boot the device are built within Nuttx. Simple boot does not +functions required to boot the device are built within NuttX. Simple boot does not require any specific configuration (it is selectable by default if no other 2nd stage bootloader is used). @@ -87,10 +90,19 @@ to specify the path to the bootloader. For compatibility among other SoCs and future options of 2nd stage bootloaders, the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be used even if no externally-built 2nd stage bootloader is being built (they will be ignored if -Simple Boot is used, for instance). +Simple Boot is used, for instance):: + + $ make bootloader + +.. note:: It is recommended that if this is the first time you are using the board with NuttX to + perform a complete SPI FLASH erase. + + .. code-block:: console + + $ esptool.py erase_flash Building and flashing -===================== +--------------------- First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a compatible ESP32-C3 image and to flash the image into the board. @@ -111,15 +123,15 @@ the ESP32-C3 as explained above. Debugging with OpenOCD ====================== -Download and build OpenOCD from Espressif, that can be found in -https://github.com/espressif/openocd-esp32 +Please check `Building OpenOCD from Sources `_ +for more information on how to build OpenOCD for ESP32-C3. 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 + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-builtin.cfg For versions prior to ESP32-C3 ECO3, an external JTAG adapter is needed. It can be connected as follows:: @@ -135,7 +147,7 @@ Furthermore, an efuse needs to be burnt to be able to debug:: OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32c3-ftdi.cfg + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-ftdi.cfg Peripheral Support ================== @@ -253,7 +265,7 @@ Now you can design an update and confirm agent to your application. Check the `M `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 `_. +`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 diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst b/Documentation/platforms/risc-v/esp32c6/index.rst index 44091ee528..636ca5bbfe 100644 --- a/Documentation/platforms/risc-v/esp32c6/index.rst +++ b/Documentation/platforms/risc-v/esp32c6/index.rst @@ -68,19 +68,22 @@ Add the toolchain to your `PATH`: You can edit your shell's rc files if you don't use bash. -Second stage bootloader -======================= +Building and flashing NuttX +=========================== -Nuttx can boot the ESP32-C6 directly using the so-called "Simple Boot". +Bootloader and partitions +------------------------- + +NuttX can boot the ESP32-C6 directly using the so-called "Simple Boot". An externally-built 2nd stage bootloader is not required in this case as all -functions required to boot the device are built within Nuttx. Simple boot does not +functions required to boot the device are built within NuttX. Simple boot does not require any specific configuration (it is selectable by default if no other 2nd stage bootloader is used). For compatibility among other SoCs and future options of 2nd stage bootloaders, the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) are kept (and ignored if Simple Boot is used). 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. @@ -109,7 +112,7 @@ USB-to-JTAG adapter. OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32c6-builtin.cfg + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c6-builtin.cfg If you want to debug with an external JTAG adapter it can be connected as follows:: @@ -125,7 +128,7 @@ Furthermore, an efuse needs to be burnt to be able to debug:: OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32c6-ftdi.cfg + openocd -c 'set ESP_RTOS hwtread; set ESP_FLASH_SIZE 0' -f board/esp32c6-ftdi.cfg Peripheral Support ================== diff --git a/Documentation/platforms/risc-v/esp32h2/index.rst b/Documentation/platforms/risc-v/esp32h2/index.rst index b8533cf6e2..3f5d8d17b9 100644 --- a/Documentation/platforms/risc-v/esp32h2/index.rst +++ b/Documentation/platforms/risc-v/esp32h2/index.rst @@ -28,7 +28,7 @@ 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 +`container `_ and check for the current compiler version being used. For instance: .. code-block:: @@ -68,19 +68,22 @@ Add the toolchain to your `PATH`: You can edit your shell's rc files if you don't use bash. -Second stage bootloader -======================= +Building and flashing NuttX +=========================== -Nuttx can boot the ESP32-H2 directly using the so-called "Simple Boot". +Bootloader and partitions +------------------------- + +NuttX can boot the ESP32-H2 directly using the so-called "Simple Boot". An externally-built 2nd stage bootloader is not required in this case as all -functions required to boot the device are built within Nuttx. Simple boot does not +functions required to boot the device are built within NuttX. Simple boot does not require any specific configuration (it is selectable by default if no other 2nd stage bootloader is used). For compatibility among other SoCs and future options of 2nd stage bootloaders, the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) are kept (and ignored if Simple Boot is used). 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. @@ -109,7 +112,7 @@ USB-to-JTAG adapter. OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32h2-builtin.cfg + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32h2-builtin.cfg If you want to debug with an external JTAG adapter it can be connected as follows:: @@ -125,7 +128,7 @@ Furthermore, an efuse needs to be burnt to be able to debug:: OpenOCD can then be used:: - openocd -c 'set ESP_RTOS none' -f board/esp32h2-ftdi.cfg + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32h2-ftdi.cfg Peripheral Support ================== diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index 24059e7d42..c21d54513b 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -17,7 +17,7 @@ On dual-core SoCs, the two CPUs are typically named "PRO_CPU" and "APP_CPU" two CPUs are interchangeable. ESP32 Toolchain -================== +=============== The toolchain used to build ESP32 firmware can be either downloaded or built from the sources. It is **highly** recommended to use (download or build) the same toolchain version that is being @@ -96,8 +96,8 @@ build the toolchain with crosstool-NG on Linux are as follows These steps are given in the setup guide in `ESP-IDF documentation `_. -Flashing -======== +Building and flashing NuttX +=========================== Firmware for ESP32 is flashed via the USB/UART interface using the ``esptool.py`` tool. It's a two step process where the first converts the ELF file into a ESP32-compatible binary @@ -108,6 +108,33 @@ flash your NuttX firmware simply by running:: where ```` is typically ``/dev/ttyUSB0`` or similar. You can change the baudrate by passing ``ESPTOOL_BAUD``. +Debugging with OpenOCD +====================== + +Please check `Building OpenOCD from Sources `_ +for more information on how to build OpenOCD for ESP32. + +ESP32 has dedicated pins for JTAG debugging. The following pins are used for JTAG debugging: + +============= =========== +ESP32 Pin JTAG Signal +============= =========== +MTDO / GPIO15 TDO +MTDI / GPIO12 TDI +MTCK / GPIO13 TCK +MTMS / GPIO14 TMS +============= =========== + +Some boards, like :ref:`ESP32-Ethernet-Kit V1.2 ` and +:ref:`ESP-WROVER-KIT `, have a built-in JTAG debugger. + +Other boards that don't have any built-in JTAG debugger can be debugged using an external JTAG debugger, like the one +described for the :ref:`ESP32-DevKitC `. + +OpenOCD can then be used:: + + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-1.8v.cfg + Bootloader and partitions ------------------------- @@ -546,7 +573,7 @@ Now you can design an update and confirm agent to your application. Check the `M `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 `_. +`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 diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst index 95b1dde7f0..47037b72e6 100644 --- a/Documentation/platforms/xtensa/esp32s2/index.rst +++ b/Documentation/platforms/xtensa/esp32s2/index.rst @@ -89,48 +89,77 @@ build the toolchain with crosstool-NG on Linux are as follows These steps are given in the setup guide in `ESP-IDF documentation `_. -Flashing -======== - -Firmware for ESP32-S2 is flashed via the USB/UART or internal USB DEVICE JTAG interface using the -``esptool.py`` tool. -It's a two-step process where the first converts the ELF file into a ESP32-S2 compatible binary -and the second flashes it to the board. These steps are included in the build system and you can -flash your NuttX firmware simply by running:: - - $ make flash ESPTOOL_PORT= - -where ```` is typically ``/dev/ttyUSB0`` or similar. You can change the baudrate by passing ``ESPTOOL_BAUD``. +Building and flashing NuttX +=========================== Bootloader and partitions ------------------------- -ESP32-S2 requires a bootloader to be flashed as well as a set of FLASH partitions. This is only needed the first time -(or any time you which to modify either of these). -An easy way is to use prebuilt binaries for NuttX `from here `__. -In there you will find instructions to rebuild these if necessary. -Once you downloaded both binaries, you can flash them by adding an ``ESPTOOL_BINDIR`` parameter, pointing to the directory where these binaries were downloaded: +NuttX can boot the ESP32-S2 directly using the so-called "Simple Boot". An externally-built +2nd stage bootloader is not required in this case as all functions required to boot the device +are built within NuttX. Simple boot does not require any specific configuration (it is selectable +by default if no other 2nd stage bootloader is used). -.. code-block:: console +If other features are required, an externally-built 2nd stage bootloader is needed. The bootloader +is built using the ``make bootloader`` command. This command generates the firmware in the +``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command to specify the path +to the bootloader. For compatibility among other SoCs and future options of 2nd stage bootloaders, +the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be +used even if no externally-built 2nd stage bootloader is being built (they will be ignored if +Simple Boot is used, for instance):: - $ make flash ESPTOOL_PORT= ESPTOOL_BINDIR= + $ make bootloader -.. note:: It is recommended that if this is the first time you are using the board with NuttX that you perform a complete - SPI FLASH erase. +.. note:: It is recommended that if this is the first time you are using the board with NuttX to + perform a complete SPI FLASH erase. - .. code-block:: console + .. code-block:: console $ esptool.py erase_flash -.. note:: Alternatively, you can automatically download the bootloader/partitions from the NuttX build system - by using the following command: +Building and Flashing +--------------------- - .. code-block:: console +First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a +compatible ESP32-S2 image and to flash the image into the board. +It can be installed with: ``pip install esptool==4.8.dev4``. - $ make bootloader +It's a two-step process where the first converts the ELF file into an ESP32-S2 compatible binary +and the second flashes it to the board. These steps are included in the build system and it is +possible to build and flash the NuttX firmware simply by running:: - The binaries will be downloaded to the project's main folder and ``ESPTOOL_BINDIR`` may be set as ``.`` + $ make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ +where ```` is typically ``/dev/ttyUSB0`` or similar. ``ESPTOOL_BINDIR=./`` is the path of the +externally-built 2nd stage bootloader and the partition table (if applicable): when built using the +``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to +change the flash baud rate if desired. + +Debugging with OpenOCD +====================== + +Please check `Building OpenOCD from Sources `_ +for more information on how to build OpenOCD for ESP32-S2. + +ESP32-S2 has dedicated pins for JTAG debugging. The following pins are used for JTAG debugging: + +============= =========== +ESP32-S2 Pin JTAG Signal +============= =========== +MTDO / GPIO40 TDO +MTDI / GPIO41 TDI +MTCK / GPIO39 TCK +MTMS / GPIO42 TMS +============= =========== + +Some boards, like :ref:`ESP32-S2-Kaluga-1 Kit v1.3 ` have a built-in JTAG debugger. + +Other boards that don't have any built-in JTAG debugger can be debugged using an external JTAG debugger being connected +directly to the ESP32-S2 JTAG pins. + +OpenOCD can then be used:: + + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s2-kaluga-1.cfg Peripheral Support ================== @@ -400,7 +429,7 @@ Now you can design an update and confirm agent to your application. Check the `M `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 `_. +`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 diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst index 4d6e2df612..4956759903 100644 --- a/Documentation/platforms/xtensa/esp32s3/index.rst +++ b/Documentation/platforms/xtensa/esp32s3/index.rst @@ -102,9 +102,9 @@ Building and flashing NuttX Bootloader and partitions ------------------------- -Nuttx can boot the ESP32-S3 directly using the so-called "Simple Boot". An externally-built +NuttX can boot the ESP32-S3 directly using the so-called "Simple Boot". An externally-built 2nd stage bootloader is not required in this case as all functions required to boot the device -are built within Nuttx. Simple boot does not require any specific configuration (it is selectable +are built within NuttX. Simple boot does not require any specific configuration (it is selectable by default if no other 2nd stage bootloader is used). If other features are required, an externally-built 2nd stage bootloader is needed. The bootloader @@ -140,7 +140,23 @@ possible to build and flash the NuttX firmware simply by running:: where ```` is typically ``/dev/ttyUSB0`` or similar. ``ESPTOOL_BINDIR=./`` is the path of the externally-built 2nd stage bootloader and the partition table (if applicable): when built using the ``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to -change the flash baudrate if desired. +change the flash baud rate if desired. + +Debugging with OpenOCD +====================== + +Please check `Building OpenOCD from Sources `_ +for more information on how to build OpenOCD for ESP32-S3. + +The quickest and most convenient way to start with JTAG debugging is through a USB cable +connected to the D+/D- USB pins of ESP32-S3. No need for an external JTAG adapter and +extra wiring/cable to connect JTAG to ESP32-S3. Most of the ESP32-S3 boards have a +USB connector that can be used for JTAG debugging. +This is the case for the :ref:`ESP32-S3-DevKit ` board. + +OpenOCD can then be used:: + + openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s3-builtin.cfg Peripheral Support ==================