boards: esp32xx: doc: update documentation on espressif Soc

Update documentation related to debugging and supported features.

Signed-off-by: Lucas Tamborrino <[email protected]>

boards/riscv/esp32c3_devkitm/doc/index.rst

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

boards/riscv/esp32c3_devkitm/esp32c3_devkitm.yaml

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

boards/xtensa/esp32/doc/index.rst

@@ -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,32 +164,22 @@ 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.
+Further documentation can be obtained from the SoC vendor in `JTAG debugging
+for ESP32`_.
 
-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.
+Here is an example for building the :ref:`hello_world` application.
 
-.. code-block:: console
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :board: esp32
+   :goals: build flash
 
-    ~/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb outdir/esp32/zephyr.elf
-    (gdb) target remote localhost:3333
+You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
 
-Further documentation can be obtained from the SoC vendor in `JTAG debugging
-for ESP32`_.
+.. 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

boards/xtensa/esp32/esp32.yaml

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

boards/xtensa/esp32s2_saola/doc/index.rst

@@ -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,21 +122,31 @@ 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 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       |
++---------------+-----------+
 
-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.
+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.
 
 .. zephyr-app-commands::
    :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

boards/xtensa/esp32s2_saola/esp32s2_saola.yaml

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