mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'feature/openocd_doc' into 'master'
Add openocd documentation and config file As we (=Ivan/Angus) discussed, the esp32-specific openocd/gdb documentation and helper tools will live in the esp-idf repository. This is an initial document detailing the basics of setting up OpenOCD with an esp32 module. It should be sufficient for people already familiar with a similar setup on another platform to start using JTAG for debugging. It can be expanded much more (e.g. the tracetool still is missing) but we'llhave to add that later. See merge request !31
This commit is contained in:
Jeroen Domburg
commit
8c7afb4b46
51
docs/esp32.cfg
Normal file
51
docs/esp32.cfg
Normal file
@ -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
|
||||
|
||||
|
||||
130
docs/openocd.rst
Normal file
130
docs/openocd.rst
Normal file
@ -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 <https://github.com/espressif/openocd-esp32>`_.
|
||||
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.
|
||||
Loading…
Reference in New Issue
Block a user