diff --git a/docs/esp32.cfg b/docs/esp32.cfg new file mode 100644 index 0000000000..e6e880b800 --- /dev/null +++ b/docs/esp32.cfg @@ -0,0 +1,51 @@ +# +# Example configuration file to hook up an ESP32 module or board to a JTAG +# adapter. Please modify this file to your local setup. +# +# + + +# Include the configuration for the JTAG adapter. We use the Tian TUMPA here. +# If you have a different interface, please edit this to include the +# configuration file of yours. +source [find interface/ftdi/tumpa.cfg] + +# The ESP32 only supports JTAG. +transport select jtag + +# The speed of the JTAG interface, in KHz. If you get DSR/DIR errors (and they +# do not relate to OpenOCD trying to read from a memory range without physical +# memory being present there), you can try lowering this. +adapter_khz 200 + +# With no variables set, openocd will configure JTAG for the two cores of the ESP32 and +# will do automatic RTOS detection. This can be be adjusted by uncommenting any of the +# following lines: + +# Only configure the PRO CPU +#set ESP32_ONLYCPU 1 +# Only configure the APP CPU +#set ESP32_ONLYCPU 2 +# Disable RTOS support +#set ESP32_RTOS none +# Force RTOS to be FreeRTOS +#set ESP32_RTOS FreeRTOS + +#Source the ESP32 configuration file +source [find target/esp32.cfg] + + +# The TDI pin of ESP32 is also a bootstrap pin that selects the voltage the SPI flash +# chip runs at. When a hard reset happens (e.g. because someone switches the board off +# and on) the ESP32 will use the current TDI value as the bootstrap value because the +# JTAG adapter overrides the pull-up or pull-down resistor that is supposed to do the +# bootstrapping. These lines basically set the idle value of the TDO line to a +# specified value, therefore reducing the chance of a bad bootup due to a bad flash +# voltage greatly. + +# Enable this for 1.8V SPI flash +esp108 flashbootstrap 1.8 +# Enable this for 3.3V SPI flash +#esp108 flashbootstrap 3.3 + + diff --git a/docs/openocd.rst b/docs/openocd.rst new file mode 100644 index 0000000000..57ee93db4a --- /dev/null +++ b/docs/openocd.rst @@ -0,0 +1,130 @@ +OpenOCD setup for ESP32 +----------------------- + +The ESP31 and ESP32 have two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS +OS that comes with ESP-IDF is capable multi-core pre-emptive multithreading, allowing for an intuitive way of writing software. + +The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused +by two threads, maybe even running simultaneously on two different CPU cures, can take a long time when all you have are printf +statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over +a debug port. + +Espressif has ported OpenOCD to support the ESP32 processor and the multicore FreeRTOS that will be the foundation of most ESP32 +apps, and has written some tools to help with features OpenOCD does not support natively. These are all available for free, and +this document describes how to install and use them. + +JTAG adapter hardware +--------------------- + +You will need a JTAG adapter that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. +The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins +all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3V rail) so the JTAG adapter needs to be +able to work with JTAG pins in that voltage range. On the software side, OpenOCD supports a fair amount of JTAG adapters. +See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters +OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. + +At Espressif, we have tested the TIAO USB Multi-protocol Adapter board as well as the Flyswatter2, which are both USB2.0 high-speed +devices and give a good throughput. We also tested a J-link-compatible and an EasyOpenJTAG adapter; both worked as well but are +somewhat slower. + +The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and Gnd. Some JTAG debuggers also need a connection +from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of +the ESP32, although for now, support in OpenOCD for that line is pretty minimal. + +Installing OpenOCD +------------------ + +The sources for the ESP32-enabled variant of OpenOCD are available from `Espressifs Github `_. +To download the source, use the following commands:: + + git clone https://github.com/espressif/openocd-esp32.git + cd openocd-esp32 + git submodule init + git submodule update + +For compilation of OpenOCD, please refer to the README, README.OSX and README.Windows file in the openocd-esp32 directory. You can skip +the ``make install`` step if you want. + +Configuring the ESP32 target in OpenOCD +--------------------------------------- + +After OpenOCD is compiled (and optionally installed) and the JTAG adapter is connected to the ESP32 board, everything is ready to +invoke OpenOCD for the first time. To do this, OpenOCD needs to be told what JTAG adapter to use as well as what type of board +and processor the JTAG adapter is connected to. It is the easiest to do both using a configuration file. A template configuration +file (esp32.cfg) is included in the same directory as this file. A way to use this would be: + +- Copy esp32.cfg to the openocd-esp32 directory +- Edit the copied esp32.cfg file. Most importantly, change the ``source [find interface/ftdi/tumpa.cfg]`` line to reflect the + physical JTAG adapter connected. +- Open a terminal and ``cd`` to the openocd-esp32 directory. +- Run ``./src/openocd -s ./tcl -f ./esp32.cfg`` to start OpenOCD + +You should now see something like this:: + + user@machine:~/esp32/openocd-esp32$ ./src/openocd -s ./tcl/ -f ../openocd-esp32-tools/esp32.cfg + Open On-Chip Debugger 0.10.0-dev-00446-g6e13a97-dirty (2016-08-23-16:36) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + none separate + adapter speed: 200 kHz + 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). + + +- If you see an error indicating permission problems, please see the 'Permissions delegation' bit in the OpenOCD README +- If you see JTAG errors (...all ones/...all zeroes) please check your connections and see if everything is powered on. + +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 ESP32s 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:: + + cd esp-idf-template + xtensa-esp32-elf-gdb -ex 'target remote localhost:3333' ./build/app-template.elf + + +This should give you a gdb prompt. + +FreeRTOS support +---------------- + +OpenOCD has explicit support for the ESP-IDF FreeRTOS; FreeRTOS detection can be disabled in esp32.conf. When enabled, +gdb can see FreeRTOS tasks as threads. Viewing them all can be done using the gdb ``i threads`` command, changing +to a certain task is done with ``thread x``, with x being the number of the thread. All threads can be switched to +except for a thread actually running on the other CPU, please see ``ESP32 quirks`` for more information. + + +ESP32 quirks +------------ + +Normal gdb breakpoints (``b myFunction``) can only be set in IRAM, because that memory is writable. Setting these types of +breakpoints in code in flash will not work. Instead, use a hardware breakpoint (``hb myFunction``). The esp32 supports +2 hardware breakpoints. It also supports two watchpoint, so two variables can be watched for change or read by the gdb +command ``watch myVariable``. + +Connecting gdb to the APP or PRO cpu happens by changing the port gdb connects to. ``target remote localhost:3333`` connects +to the PRO CPU, ``target remote localhost:3334`` to the APP CPU. Hardware-wise, when one CPU is halted because of debugging +reasons, the other one will be halted as well; resuming also happens simultaneously. + +Because gdb only sees the system from the point of view of the selected CPU, only the FreeRTOS tasks that are suspended +and the task running on the CPU gdb is connected to, will be shown correctly. The task that was active on the other +cpu can be inspected, but its state may be wildly inconsistent. + +The ESP-IDF code has the option of compiling in various support options for OpenOCD: it can stop execution when the first +thread is started and break the system if a panic or unhandled exception is thrown. Both options are enabled by default +but can be disabled using the esp-idf configuration menu. Please see the ``make menuconfig`` menu for more details. + +Normally, under OpenOCD, a board can be reset by entering 'mon reset' or 'mon reset halt' into gdb. For +the ESP32, these commands work more or less, but have side effects. First of all, an OpenOCD reset only +resets the CPU cores, not the peripherals, which may lead to undefined behaviour if software assumes the +after-reset state of peripherals. Secondly, 'mon reset halt' stops before FreeRTOS is initialized. +OpenOCD assumes (in the default configuration, you can change this by editing esp32.cfg) a running +FreeRTOS and may get confused.