michaelh/zephyr
1
0
Fork 0
Code Releases Activity

boards: esp32xx: doc: update documentation on espressif Soc

Browse source 
Update documentation related to debugging and supported features.

Signed-off-by: Lucas Tamborrino <lucas.tamborrino@espressif.com>
This commit is contained in:
Lucas Tamborrino 2023-03-31 17:08:56 -03:00 • committed by Carles Cufí
commit 0ea10827a9
9 changed files with 270 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

54
boards/riscv/esp32c3_devkitm/doc/index.rst
View file

@ -32,8 +32,48 @@ The features include the following:
- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
Supported Features
==================
Current Zephyr's ESP32-C3-Devkitm board supports the following features:
+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
+============+============+=====================================+
+------------+------------+-------------------------------------+
| UART | on-chip | serial port |
+------------+------------+-------------------------------------+
| GPIO | on-chip | gpio |
+------------+------------+-------------------------------------+
| PINMUX | on-chip | pinmux |
+------------+------------+-------------------------------------+
| USB-JTAG | on-chip | hardware interface |
+------------+------------+-------------------------------------+
| SPI Master | on-chip | spi |
+------------+------------+-------------------------------------+
| Timers | on-chip | counter |
+------------+------------+-------------------------------------+
| Watchdog | on-chip | watchdog |
+------------+------------+-------------------------------------+
| TRNG | on-chip | entropy |
+------------+------------+-------------------------------------+
| LEDC | on-chip | pwm |
+------------+------------+-------------------------------------+
| SPI DMA | on-chip | spi |
+------------+------------+-------------------------------------+
| TWAI | on-chip | can |
+------------+------------+-------------------------------------+
| USB-CDC | on-chip | serial |
+------------+------------+-------------------------------------+
| ADC | on-chip | adc |
+------------+------------+-------------------------------------+
| Wi-Fi | on-chip | |
+------------+------------+-------------------------------------+
| Bluetooth | on-chip | |
+------------+------------+-------------------------------------+
System requirements
*******************
===================
Prerequisites
-------------
@ -86,7 +126,7 @@ message in the monitor:
Debugging
---------
As with much custom hardware, the ESP32 modules require patches to
As with much custom hardware, the ESP32-C3 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
@ -109,10 +149,12 @@ You can debug an application in the usual way. Here is an example for the :ref:`
:board: esp32c3_devkitm
:goals: debug
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
References
**********
==========
.. [1] https://www.espressif.com/en/products/socs/esp32-c3
.. _`ESP32C3 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
.. _`ESP32C3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
.. _ESP32C3 Devkitm User Guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/hw-reference/esp32c3/user-guide-devkitm-1.html
.. _ESP32C3 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
.. _ESP32C3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf

4
boards/riscv/esp32c3_devkitm/esp32c3_devkitm.yaml
View file

@ -11,6 +11,10 @@ supported:
- watchdog
- uart
- dma
- pwm
- spi
- counter
- entropy
testing:
ignore_tags:
- net

130
boards/xtensa/esp32/doc/index.rst
View file

@ -41,8 +41,52 @@ The features include the following:
- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
- 5uA deep sleep current
Supported Features
==================
Current Zephyr's ESP32-devkitc board supports the following features:
+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
+============+============+=====================================+
+------------+------------+-------------------------------------+
| UART | on-chip | serial port |
+------------+------------+-------------------------------------+
| GPIO | on-chip | gpio |
+------------+------------+-------------------------------------+
| PINMUX | on-chip | pinmux |
+------------+------------+-------------------------------------+
| USB-JTAG | on-chip | hardware interface |
+------------+------------+-------------------------------------+
| SPI Master | on-chip | spi |
+------------+------------+-------------------------------------+
| Timers | on-chip | counter |
+------------+------------+-------------------------------------+
| Watchdog | on-chip | watchdog |
+------------+------------+-------------------------------------+
| TRNG | on-chip | entropy |
+------------+------------+-------------------------------------+
| LEDC | on-chip | pwm |
+------------+------------+-------------------------------------+
| MCPWM | on-chip | pwm |
+------------+------------+-------------------------------------+
| PCNT | on-chip | qdec |
+------------+------------+-------------------------------------+
| SPI DMA | on-chip | spi |
+------------+------------+-------------------------------------+
| TWAI | on-chip | can |
+------------+------------+-------------------------------------+
| ADC | on-chip | adc |
+------------+------------+-------------------------------------+
| DAC | on-chip | dac |
+------------+------------+-------------------------------------+
| Wi-Fi | on-chip | |
+------------+------------+-------------------------------------+
| Bluetooth | on-chip | |
+------------+------------+-------------------------------------+
System requirements
*******************
===================
Prerequisites
-------------
@ -95,40 +139,8 @@ message in the monitor:
Debugging
---------
As with much custom hardware, the ESP32 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: debug
Using JTAG
======================
On the ESP-WROVER-KIT board, the JTAG pins are connected internally to
a USB serial port on the same device as the console. These boards
require no external hardware and are debuggable as-is. The JTAG
signals, however, must be jumpered closed to connect the internal
controller (the default is to leave them disconnected). The jumper
headers are on the right side of the board as viewed from the power
switch, next to similar headers for SPI and UART. See
`ESP-WROVER-32 V3 Getting Started Guide`_ for details.
ESP32 support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
standard connector (e.g. ARM 20-pin) and need to be manually connected
@ -152,33 +164,23 @@ to the external programmer (e.g. a Flyswatter2):
| IO15 | TDO |
+------------+-----------+
Once the device is connected, you should be able to connect with (for
a DevKitC board, replace with esp32-wrover.cfg for WROVER):
.. code-block:: console
cd ~/esp/openocd-esp32
src/openocd -f interface/ftdi/flyswatter2.cfg -c 'set ESP32_ONLYCPU 1' -c 'set ESP32_RTOS none' -f board/esp-wroom-32.cfg -s tcl
The ESP32_ONLYCPU setting is critical: without it OpenOCD will present
only the "APP_CPU" via the gdbserver, and not the "PRO_CPU" on which
Zephyr is running. It's currently unexplored as to whether the CPU
can be switched at runtime or if breakpoints can be set for
either/both.
Now you can connect to openocd with gdb and point it to the OpenOCD
gdbserver running (by default) on localhost port 3333. Note that you
must use the gdb distributed with the ESP-32 SDK. Builds off of the
FSF mainline get inexplicable protocol errors when connecting.
.. code-block:: console
~/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb outdir/esp32/zephyr.elf
(gdb) target remote localhost:3333
Further documentation can be obtained from the SoC vendor in `JTAG debugging
for ESP32`_.
Here is an example for building the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: build flash
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: esp32
:goals: debug
Note on Debugging with GDB Stub
===============================
@ -190,12 +192,12 @@ GDB stub is enabled on ESP32.
This does not work as the code is on flash which cannot be randomly
accessed for modification.
.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`OpenOCD`: https://github.com/openocd-org/openocd
References
**********
.. [1] https://en.wikipedia.org/wiki/ESP32
.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
.. _`Hardware Reference`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
.. _`ESP-WROVER-32 V3 Getting Started Guide`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-wrover-kit.html
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html

3
boards/xtensa/esp32/esp32.yaml
View file

@ -14,6 +14,9 @@ supported:
- nvs
- pwm
- dac
- spi
- counter
- entropy
testing:
ignore_tags:
- net

74
boards/xtensa/esp32s2_saola/doc/index.rst
View file

@ -30,8 +30,46 @@ The features include the following:
- DAC
- LED PWM with up to 8 channels
Supported Features
==================
Current Zephyr's ESP32-S2-saola board supports the following features:
+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
+============+============+=====================================+
+------------+------------+-------------------------------------+
| UART | on-chip | serial port |
+------------+------------+-------------------------------------+
| GPIO | on-chip | gpio |
+------------+------------+-------------------------------------+
| PINMUX | on-chip | pinmux |
+------------+------------+-------------------------------------+
| USB-JTAG | on-chip | hardware interface |
+------------+------------+-------------------------------------+
| SPI Master | on-chip | spi |
+------------+------------+-------------------------------------+
| Timers | on-chip | counter |
+------------+------------+-------------------------------------+
| Watchdog | on-chip | watchdog |
+------------+------------+-------------------------------------+
| TRNG | on-chip | entropy |
+------------+------------+-------------------------------------+
| LEDC | on-chip | pwm |
+------------+------------+-------------------------------------+
| PCNT | on-chip | qdec |
+------------+------------+-------------------------------------+
| SPI DMA | on-chip | spi |
+------------+------------+-------------------------------------+
| ADC | on-chip | adc |
+------------+------------+-------------------------------------+
| DAC | on-chip | dac |
+------------+------------+-------------------------------------+
| Wi-Fi | on-chip | |
+------------+------------+-------------------------------------+
System requirements
*******************
===================
Prerequisites
-------------
@ -84,13 +122,24 @@ message in the monitor:
Debugging
---------
As with much custom hardware, the ESP32 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
ESP32-S2 support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
The following table shows the pin mapping between ESP32-S2 board and JTAG interface.
+---------------+-----------+
| ESP32 pin | JTAG pin |
+===============+===========+
| MTDO / GPIO40 | TDO |
+---------------+-----------+
| MTDI / GPIO41 | TDI |
+---------------+-----------+
| MTCK / GPIO39 | TCK |
+---------------+-----------+
| MTMS / GPIO42 | TMS |
+---------------+-----------+
Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S2`_.
Here is an example for building the :ref:`hello_world` application.
@ -98,7 +147,6 @@ Here is an example for building the :ref:`hello_world` application.
:zephyr-app: samples/hello_world
:board: esp32s2_saola
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
@ -107,10 +155,14 @@ You can debug an application in the usual way. Here is an example for the :ref:`
:board: esp32s2_saola
:goals: debug
.. _`OpenOCD`: https://github.com/openocd-org/openocd
.. _`JTAG debugging for ESP32-S2`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/jtag-debugging/index.html
References
**********
.. [1] https://www.espressif.com/en/products/socs/esp32-s2
.. _`ESP32S2 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf
.. _`ESP32S2 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
.. _ESP32-S2 Saola User Guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html
.. _ESP32S2 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf
.. _ESP32S2 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf

5
boards/xtensa/esp32s2_saola/esp32s2_saola.yaml
View file

@ -11,6 +11,11 @@ supported:
- i2c
- watchdog
- uart
- nvs
- pwm
- spi
- counter
- entropy
testing:
ignore_tags:
- net

25
boards/xtensa/esp32s3_devkitm/doc/index.rst
View file

@ -156,13 +156,13 @@ message in the monitor:
Debugging
---------
As with much custom hardware, the ESP32 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
ESP32-S3 support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
ESP32-S3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary.
Further documentation can be obtained from the SoC vendor in `JTAG debugging
for ESP32-S3`_.
Here is an example for building the :ref:`hello_world` application.
@ -170,7 +170,6 @@ Here is an example for building the :ref:`hello_world` application.
:zephyr-app: samples/hello_world
:board: esp32s3_devkitm
:goals: build flash
:gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
@ -179,11 +178,13 @@ You can debug an application in the usual way. Here is an example for the :ref:`
:board: esp32s3_devkitm
:goals: debug
.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
.. _`OpenOCD`: https://github.com/openocd-org/openocd
.. _`ESP32-S3 DevKitM`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3/user-guide-devkitm-1.html
References
**********
.. _`ESP32-S3 DevKitM`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3/user-guide-devkitm-1.html
.. _`ESP32-S3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s3-mini-1_mini-1u_datasheet_en.pdf
.. _`ESP32 Technical Reference Manual`: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
.. _ESP32-S3 DevKitM User Guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3/user-guide-devkitm-1.html
.. _ESP32-S3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s3-mini-1_mini-1u_datasheet_en.pdf
.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf

76
boards/xtensa/esp_wrover_kit/doc/index.rst
View file

@ -439,8 +439,52 @@ Do not install any other jumpers.
Turn the Power Switch to ON, the 5V Power On LED should light up.
Supported Features
==================
Current Zephyr's ESP32-Wrover-Kit board supports the following features:
+------------+------------+-------------------------------------+
| Interface | Controller | Driver/Component |
+============+============+=====================================+
+------------+------------+-------------------------------------+
| UART | on-chip | serial port |
+------------+------------+-------------------------------------+
| GPIO | on-chip | gpio |
+------------+------------+-------------------------------------+
| PINMUX | on-chip | pinmux |
+------------+------------+-------------------------------------+
| USB-JTAG | on-chip | hardware interface |
+------------+------------+-------------------------------------+
| SPI Master | on-chip | spi |
+------------+------------+-------------------------------------+
| Timers | on-chip | counter |
+------------+------------+-------------------------------------+
| Watchdog | on-chip | watchdog |
+------------+------------+-------------------------------------+
| TRNG | on-chip | entropy |
+------------+------------+-------------------------------------+
| LEDC | on-chip | pwm |
+------------+------------+-------------------------------------+
| MCPWM | on-chip | pwm |
+------------+------------+-------------------------------------+
| PCNT | on-chip | qdec |
+------------+------------+-------------------------------------+
| SPI DMA | on-chip | spi |
+------------+------------+-------------------------------------+
| TWAI | on-chip | can |
+------------+------------+-------------------------------------+
| ADC | on-chip | adc |
+------------+------------+-------------------------------------+
| DAC | on-chip | dac |
+------------+------------+-------------------------------------+
| Wi-Fi | on-chip | |
+------------+------------+-------------------------------------+
| Bluetooth | on-chip | |
+------------+------------+-------------------------------------+
System requirements
*******************
===================
Prerequisites
-------------
@ -493,13 +537,17 @@ message in the monitor:
Debugging
---------
As with much custom hardware, the ESP32 modules require patches to
OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
ESP32 support on OpenOCD is available upstream as of version 0.12.0.
Download and install OpenOCD from `OpenOCD`_.
The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
parameter when building.
On the ESP-WROVER-KIT board, the JTAG pins are connected internally to
a USB serial port on the same device as the console. These boards
require no external hardware and are debuggable as-is. The JTAG
signals, however, must be jumpered closed to connect the internal
controller (the default is to leave them disconnected). The jumper
headers are on the right side of the board as viewed from the power
switch, next to similar headers for SPI and UART. See
`ESP-WROVER-32 V3 Getting Started Guide`_ for details.
Here is an example for building the :ref:`hello_world` application.
@ -516,12 +564,14 @@ You can debug an application in the usual way. Here is an example for the :ref:`
:board: esp_wrover_kit
:goals: debug
.. _`OpenOCD`: https://github.com/openocd-org/openocd
.. _`ESP-WROVER-32 V3 Getting Started Guide`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-wrover-kit.html
Related Documents
*****************
- `ESP-WROVER-KIT V4.1 schematic <https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4_1.pdf>`_ (PDF)
- `ESP-WROVER-KIT V4.1 layout <https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4.1.dxf>`_ (DXF)
- `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
- `ESP32-WROVER-E Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf>`_ (PDF)
- `ESP32 Hardware Reference <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html>`_
- `OpenOCD ESP32 <https://github.com/espressif/openocd-esp32/releases>`_
.. _ESP-WROVER-KIT V4.1 schematics: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4_1.pdf (PDF)
.. _ESP-WROVER-KIT V4.1 layout: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_V4.1.dxf (DXF)
.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf (PDF)
.. _ESP32-WROVER-E Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-e_esp32-wrover-ie_datasheet_en.pdf (PDF)
.. _ESP32 Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html

6
boards/xtensa/esp_wrover_kit/esp_wrover_kit.yaml
View file

@ -5,13 +5,17 @@ arch: xtensa
toolchain:
- zephyr
supported:
- adc
- dac
- gpio
- i2c
- spi
- watchdog
- uart
- nvs
- pwm
- spi
- counter
- entropy
testing:
ignore_tags:
- net