luchianmihai/walnux
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation: Improve Espressif toolchain/debugger documentation

Browse source 
This commits improves the documentation about Espressif's toolchain
and debugging tools for the supported SoCs on NuttX.
This commit is contained in:
Tiago Medicci Serrano 2024-06-19 16:39:56 -03:00 • committed by Xiang Xiao
parent caeb1757f6
commit d295752a26
7 changed files with 152 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Documentation/platforms/risc-v/esp32c3-legacy/index.rst
View file

@ -259,7 +259,7 @@ Now you can design an update and confirm agent to your application. Check the `M
`MCUboot Espressif port documentation <https://docs.mcuboot.com/readme-espressif.html>`_ for
more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port <https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md>`_,
the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md>`_ and some
`examples of MCUboot applied in Nuttx applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
`examples of MCUboot applied in NuttX applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
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

34
Documentation/platforms/risc-v/esp32c3/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32c3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
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 <https://docs.mcuboot.com/readme-espressif.html>`_ for
more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port <https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md>`_,
the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md>`_ and some
`examples of MCUboot applied in Nuttx applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
`examples of MCUboot applied in NuttX applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
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

17
Documentation/platforms/risc-v/esp32c6/index.rst
View file

@ -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
==================

19
Documentation/platforms/risc-v/esp32h2/index.rst
View file

@ -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 <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ and
`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::
@ -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
==================

35
Documentation/platforms/xtensa/esp32/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.
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 ``<port>`` is typically ``/dev/ttyUSB0`` or similar. You can change the baudrate by passing ``ESPTOOL_BAUD``.
Debugging with OpenOCD
======================
Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
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 <platforms/xtensa/esp32/boards/esp32-ethernet-kit/index:ESP32-Ethernet-Kit V1.2>` and
:ref:`ESP-WROVER-KIT <platforms/xtensa/esp32/boards/esp32-wrover-kit/index: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 <platforms/xtensa/esp32/boards/esp32-devkitc/index:Debugging with OpenOCD>`.
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 <https://docs.mcuboot.com/readme-espressif.html>`_ for
more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port <https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md>`_,
the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md>`_ and some
`examples of MCUboot applied in Nuttx applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
`examples of MCUboot applied in NuttX applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
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

85
Documentation/platforms/xtensa/esp32s2/index.rst
View file

@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.
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=<port>
where ``<port>`` 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 <https://github.com/espressif/esp-nuttx-bootloader>`__.
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=<port> ESPTOOL_BINDIR=<dir>
$ 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=<port> ESPTOOL_BINDIR=./
where ``<port>`` 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 <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s2/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
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 <platforms/xtensa/esp32s2/boards/esp32s2-kaluga-1/index: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 <https://docs.mcuboot.com/readme-espressif.html>`_ for
more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port <https://github.com/mcu-tools/mcuboot/blob/main/docs/readme-nuttx.md>`_,
the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/PORTING.md>`_ and some
`examples of MCUboot applied in Nuttx applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
`examples of MCUboot applied in NuttX applications <https://github.com/apache/nuttx-apps/tree/master/examples/mcuboot>`_.
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

22
Documentation/platforms/xtensa/esp32s3/index.rst
View file

@ -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 ``<port>`` 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 <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
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 <platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:ESP32S3-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
==================