diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index d556692303..5636f5ef16 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -307,235 +307,6 @@ Bluetooth Bluetooth is not currently supported. -Debugging with OpenOCD -====================== - -First you in need some debug environment which would be a JTAG emulator -and the ESP32 OpenOCD software which is available here: -https://github.com/espressif/openocd-esp32 - -OpenOCD Documentation ---------------------- - -There is on overview of the use of OpenOCD `here `. -This document is also available in `ESP-IDF source tree `_ -in ``docs`` directory. - -OpenOCD Configuration File --------------------------- - -A template ESP32 OpenOCD configuration file is provided in -ESP-IDF ``docs`` directory (``esp32.cfg``). Since you are not using -FreeRTOS, you will need to uncomment the line:: - - set ESP32_RTOS none - -in the OpenOCD configuration file. You will also need to change -the source line from:: - - find interface/ftdi/tumpa.cfg - -to reflect the physical JTAG adapter connected. - -A copy of this OpenOCD configuration file available in the NuttX -source tree at ``nuttx/boards/xtensa/esp32/esp32-devkitc/scripts/esp32.cfg``. -It has these modifications: - - - The referenced "set ESP32_RTOS none" line has been uncommented - - The "find interface/ftdi/tumpa.cfg" was removed. This means that you will - need to specify the interface configuration file on the OpenOCD - command line. - -Another OpenOCD configuration file is available in the NuttX source tree at -``nuttx/boards/xtensa/esp32/esp32-devkitc/scripts/esp32-ft232h.cfg``. -It has been tested with: - - - `ESP32-DevKitC V4 `_ - - - Akizukidenshi's FT232HL, a FT232H based JTAG adapter - (http://akizukidenshi.com/catalog/g/gK-06503/) with JP3 and JP4 closed, - and connected to ESP32 as: - - +------------------+-------------+ - | ESP32-DevKitC V4 | FT232HL | - +=======+==========+=============+ - | J2 | J3 | J2 | - +-------+----------+-------------+ - | IO13 | | AD0 (TCK) | - +-------+----------+-------------+ - | IO12 | | AD1 (TDI) | - +-------+----------+-------------+ - | | IO15 | AD2 (TDO) | - +-------+----------+-------------+ - | IO14 | | AD3 (TMS) | - +-------+----------+-------------+ - | GND | | GND | - +-------+----------+-------------+ - -The following version of OpenOCD from ESP-IDF (macOS version):: - - % openocd --version - Open On-Chip Debugger v0.10.0-esp32-20191114 (2019-11-14-14:19) - Licensed under GNU GPL v2 - For bug reports, read - http://openocd.org/doc/doxygen/bugs.html - -General OpenOCD build instructions ----------------------------------- - -Installing OpenOCD. The sources for the ESP32-enabled variant of -OpenOCD are available from Espressifs GitHub. To download the source, -use the following commands: - -.. code-block:: console - - $ git clone https://github.com/espressif/openocd-esp32.git - $ cd openocd-esp32 - $ git submodule init - $ git submodule update - -Then look at the README and the docs/INSTALL.txt files in the -openocd-esp32 directory for further instructions. There area -separate README files for Linux/Cygwin, macOS, and Windows. Here -is what I ended up doing (under Linux): - -.. code-block:: console - - $ cd openocd-esp32 - $ ./bootstrap - $ ./configure - $ make - -If you do not do the install step, then you will have a localhost -version of the OpenOCD binary at ``openocd-esp32/src``. - -Starting the OpenOCD Server ---------------------------- - - - cd to openocd-esp32 directory - - copy the modified esp32.cfg script to this directory - -Then start OpenOCD by executing a command like the following. Here -I assume that: - - - You did not install OpenOCD; binaries are available at - openocd-esp32/src and interface scripts are in - openocd-esp32/tcl/interface - - I select the configuration for the Olimex ARM-USB-OCD - debugger. - -Then the command to start OpenOCD is: - -.. code-block:: console - - $ ./src/openocd -s ./tcl -f tcl/interface/ftdi/olimex-arm-usb-ocd.cfg -f ./esp32.cfg - -I then see:: - - Open On-Chip Debugger 0.10.0-dev-g3098897 (2016-11-14-12:19) - Licensed under GNU GPL v2 - For bug reports, read - http://openocd.org/doc/doxygen/bugs.html - adapter speed: 200 kHz - force hard breakpoints - Info : clock speed 200 kHz - Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : esp32.cpu0: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - Info : esp32.cpu0: Core was reset (pwrstat=0x5F, after clear 0x0F). - -Connecting a debugger to OpenOCD --------------------------------- - -OpenOCD should now be ready to accept gdb connections. If you have -compiled the ESP32 toolchain using Crosstool-NG, or if you have -downloaded a precompiled toolchain from the Espressif website, you -should already have xtensa-esp32-elf-gdb, a version of gdb that can -be used for this - -First, make sure the project you want to debug is compiled and -flashed into the ESP32’s SPI flash. Then, in a different console -than OpenOCD is running in, invoke gdb. For example, for the -template app, you would do this like such:: - -.. code-block:: console - - $ cd nuttx - $ xtensa-esp32-elf-gdb -ex 'target remote localhost:3333' nuttx - -This should give you a gdb prompt. - -Breakpoints ------------ - -You can set up to 2 hardware breakpoints, which can be anywhere in the -address space. Also 2 hardware watchpoints. - -The openocd esp32.cfg file currently forces gdb to use hardware -breakpoints, I believe because software breakpoints (or, at least, the -memory map for automatically choosing them) aren't implemented yet -(as of 2016-11-14). - -JTAG Emulator -------------- - -The documentation indicates that you need to use an external JTAG -like the TIAO USB Multi-protocol Adapter and the Flyswatter2. -The instructions at http://www.esp32.com/viewtopic.php?t=381 show -use of an FTDI C232HM-DDHSL-0 USB 2.0 high speed to MPSSE cable. - -The ESP32 DevkitC v4 board has no on board JTAG connector. It will -be necessary to make a cable or some other board to connect a JTAG -emulator. Refer to http://www.esp32.com/viewtopic.php?t=381 "How -to debug ESP32 with JTAG / OpenOCD / GDB 1st part connect the -hardware." - -Relevant pin-out: - -========= ============= -PIN LABEL JTAG FUNCTION -========= ============= -IO14 TMS -IO12 TDI -GND GND -IO13 TCK -x x -IO15 TDO -========= ============= - -You can find the mapping of JTAG signals to ESP32 GPIO numbers in -"ESP32 Pin List" document found -`here `_. - -I put the ESP32 on a prototyping board and used a standard JTAG 20-pin -connector with an older Olimex JTAG that I had. Here is how I wired -the 20-pin connector: - -===================== =============== -20-PIN JTAG CONNECTOR ESP32 PIN LABEL -===================== =============== - 1 VREF INPUT 3V3 - 3 nTRST OUTPUT N/C - 5 TDI OUTPUT IO12 - 7 TMS OUTPUT IO14 - 9 TCLK OUTPUT IO13 -11 RTCK INPUT N/C -13 TDO INPUT IO15 -15 RESET I/O N/C -17 DBGRQ OUTPUT N/C -19 5V OUTPUT N/C - 2 VCC INPUT 3V3 - 4 GND N/A GND - 6 GND N/A GND - 8 GND N/A GND -10 GND N/A GND -12 GND N/A GND -14 GND N/A GND -16 GND N/A GND -18 GND N/A GND -20 GND N/A GND -===================== =============== - Using QEMU ==========