mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-09 20:41:14 +00:00
docs: jtag-debugging: update for IDF Tools installation method
- rely on OPENOCD_SCRIPTS variable in all cases, remove -s flags - replace installation section with a reference to the Getting Started guides - add Windows-specific commands in a few cases
This commit is contained in:
Ivan Grokhotkov
@@ -121,20 +121,14 @@ Manually unloading the driver
|
||||
|
||||
sudo kextunload -b com.apple.driver.AppleUSBFTDI
|
||||
|
||||
4. Run OpenOCD (paths are given for downloadable OpenOCD archive)::
|
||||
4. Run OpenOCD::
|
||||
|
||||
bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
Or, if OpenOCD was built from source::
|
||||
|
||||
src/openocd -s tcl -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
bin/openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
5. In another terminal window, load FTDI serial port driver again::
|
||||
|
||||
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
|
||||
|
||||
.. include:: ./windows-openocd-note.rst
|
||||
|
||||
.. note::
|
||||
|
||||
If you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if WROVER KIT was reconnected or power was toggled.
|
||||
|
||||
@@ -12,7 +12,7 @@ GDB. The document is structured as follows:
|
||||
:ref:`jtag-debugging-selecting-jtag-adapter`
|
||||
What are the criteria and options to select JTAG adapter hardware.
|
||||
:ref:`jtag-debugging-setup-openocd`
|
||||
Procedure to install OpenOCD using prebuilt software packages for :doc:`Windows <setup-openocd-windows>`, :doc:`Linux <setup-openocd-linux>` and :doc:`MacOS <setup-openocd-macos>` operating systems.
|
||||
Procedure to install OpenOCD and verify that it is installed.
|
||||
:ref:`jtag-debugging-configuring-esp32-target`
|
||||
Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target.
|
||||
:ref:`jtag-debugging-launching-debugger`
|
||||
@@ -84,45 +84,28 @@ The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS a
|
||||
Setup of OpenOCD
|
||||
----------------
|
||||
|
||||
This step covers installation of OpenOCD binaries. If you like to build OpenOCS from sources then refer to section :ref:`jtag-debugging-building-openocd`. All OpenOCD files will be placed in ``~/esp/openocd-esp32`` directory. You may choose any other directory, but need to adjust respective paths used in examples.
|
||||
.. highlight:: bash
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
If you have already set up ESP-IDF with CMake build system according to the :doc:`Getting Started Guide <../../get-started/index>`, then OpenOCD is already installed. After :ref:`setting up the environment <get-started-set-up-env>` in your terminal, you should be able to run OpenOCD. Check this by executing the following command::
|
||||
|
||||
Windows <setup-openocd-windows>
|
||||
Linux <setup-openocd-linux>
|
||||
MacOS <setup-openocd-macos>
|
||||
openocd --version
|
||||
|
||||
Pick up your OS below and follow provided instructions to setup OpenOCD.
|
||||
.. highlight:: none
|
||||
|
||||
+-------------------+-------------------+-------------------+
|
||||
| |windows-logo| | |linux-logo| | |macos-logo| |
|
||||
+-------------------+-------------------+-------------------+
|
||||
| `Windows`_ | `Linux`_ | `Mac OS`_ |
|
||||
+-------------------+-------------------+-------------------+
|
||||
The output should be as follows (although the version may be more recent than listed here)::
|
||||
|
||||
.. |windows-logo| image:: ../../../_static/windows-logo.png
|
||||
:target: ../jtag-debugging/setup-openocd-windows.html
|
||||
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
|
||||
Licensed under GNU GPL v2
|
||||
For bug reports, read
|
||||
http://openocd.org/doc/doxygen/bugs.html
|
||||
|
||||
.. |linux-logo| image:: ../../../_static/linux-logo.png
|
||||
:target: ../jtag-debugging/setup-openocd-linux.html
|
||||
You may also verify that OpenOCD knows where its configuration scripts are located by printing the value of ``OPENOCD_SCRIPTS`` environment variable, by typing ``echo $OPENOCD_SCRIPTS`` (for Linux and macOS) or ``echo %OPENOCD_SCRIPTS%`` (for Windows). If a valid path is printed, then OpenOCD is set up correctly.
|
||||
|
||||
.. |macos-logo| image:: ../../../_static/macos-logo.png
|
||||
:target: ../jtag-debugging/setup-openocd-macos.html
|
||||
|
||||
.. _Windows: ../jtag-debugging/setup-openocd-windows.html
|
||||
.. _Linux: ../jtag-debugging/setup-openocd-linux.html
|
||||
.. _Mac OS: ../jtag-debugging/setup-openocd-macos.html
|
||||
|
||||
After installation is complete, get familiar with two key directories inside ``openocd-esp32`` installation folder:
|
||||
|
||||
* ``bin`` containing OpenOCD executable
|
||||
* ``share\openocd\scripts`` containing configuration files invoked together with OpenOCD as command line parameters
|
||||
If any of these steps do not work, please go back to the :ref:`setting up the tools <get-started-set-up-tools>` section of the Getting Started Guide.
|
||||
|
||||
.. note::
|
||||
|
||||
Directory names and structure above are specific to binary distribution of OpenOCD. They are used in examples of invoking OpenOCD throughout this guide. Directories for OpenOCD build from sources are different, so the way to invoke OpenOCD. For details see :ref:`jtag-debugging-building-openocd`.
|
||||
|
||||
It is also possible to build OpenOCD from source. Please refer to :ref:`jtag-debugging-building-openocd` section for details.
|
||||
|
||||
.. _jtag-debugging-configuring-esp32-target:
|
||||
|
||||
@@ -157,23 +140,20 @@ Once target is configured and connected to computer, you are ready to launch Ope
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
Open terminal, go to directory where OpenOCD is installed and start it up::
|
||||
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS)::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
.. note::
|
||||
|
||||
The files provided after ``-f`` above, are specific for ESP-WROVER-KIT with :ref:`esp-modules-and-boards-esp32-wroom-32` module. You may need to provide different files depending on used hardware, For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
|
||||
.. include:: ./windows-openocd-note.rst
|
||||
The files provided after ``-f`` above are specific for ESP-WROVER-KIT with :ref:`esp-modules-and-boards-esp32-wroom-32` module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
You should now see similar output (this log is for ESP-WROVER-KIT)::
|
||||
|
||||
user-name@computer-name:~/esp/openocd-esp32$ bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
Open On-Chip Debugger 0.10.0-dev-ged7b1a9 (2017-07-10-07:16)
|
||||
user-name@computer-name:~/esp/esp-idf$ openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04)
|
||||
Licensed under GNU GPL v2
|
||||
For bug reports, read
|
||||
http://openocd.org/doc/doxygen/bugs.html
|
||||
@@ -201,10 +181,7 @@ Build and upload your application to ESP32 as usual, see :ref:`get-started-build
|
||||
|
||||
Another option is to write application image to flash using OpenOCD via JTAG with commands like this::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "program_esp32 filename.bin 0x10000 verify exit"
|
||||
|
||||
.. include:: ./windows-openocd-note.rst
|
||||
openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "program_esp32 filename.bin 0x10000 verify exit"
|
||||
|
||||
OpenOCD flashing command ``program_esp32`` has the following format:
|
||||
|
||||
@@ -268,13 +245,27 @@ Please refer to separate documents listed below, that describe build process.
|
||||
Linux <building-openocd-linux>
|
||||
MacOS <building-openocd-macos>
|
||||
|
||||
.. note::
|
||||
The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
Examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`. To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and the path to configuration files to ``-s tcl``.
|
||||
.. highlight:: bash
|
||||
|
||||
Example of invoking OpenOCD build locally from sources::
|
||||
To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS::
|
||||
|
||||
src/openocd -s tcl -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
cd ~/esp/openocd-esp32
|
||||
export OPENOCD_SCRIPTS=$PWD/tcl
|
||||
|
||||
For Windows::
|
||||
|
||||
cd %USERPROFILE%\esp\openocd-esp32
|
||||
set "OPENOCD_SCRIPTS=%CD%\tcl"
|
||||
|
||||
Example of invoking OpenOCD build locally from sources, for Linux and macOS::
|
||||
|
||||
src/openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
and Windows::
|
||||
|
||||
src\openocd -f interface\ftdi\esp32_devkitj_v1.cfg -f board\esp-wroom-32.cfg
|
||||
|
||||
|
||||
.. _jtag-debugging-tips-and-quirks:
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
************************
|
||||
Set up OpenOCD for Linux
|
||||
************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Set up OpenOCD
|
||||
==============
|
||||
|
||||
OpenOCD for 64-bit Linux is available for download from Github:
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
Download latest release archive with `linux64` in its name, for example `openocd-esp32-linux64-0.10.0-esp32-20180418.tar.gz`.
|
||||
|
||||
Extract the downloaded file in ``~/esp/`` directory::
|
||||
|
||||
cd ~/esp
|
||||
tar -xzf ~/Downloads/openocd-esp32-linux64-<version>.tar.gz
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-linux
|
||||
|
||||
@@ -1,39 +0,0 @@
|
||||
************************
|
||||
Set up OpenOCD for MacOS
|
||||
************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Install libusb
|
||||
==============
|
||||
|
||||
Use `Homebrew <https://brew.sh/>`_ or `Macports <https://www.macports.org/>`_ to install `libusb` package.
|
||||
|
||||
Set up OpenOCD
|
||||
==============
|
||||
|
||||
OpenOCD for MacOS is available for download from Github:
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
Download latest release archive with `macos` in its name, for example `openocd-esp32-macos-0.10.0-esp32-20180418.tar.gz`.
|
||||
|
||||
Extract the downloaded file in ``~/esp/`` directory::
|
||||
|
||||
cd ~/esp
|
||||
tar -xzf ~/Downloads/openocd-esp32-macos-<version>.tar.gz
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-macos
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
**************************
|
||||
Set up OpenOCD for Windows
|
||||
**************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
IDF Tools Installer
|
||||
===================
|
||||
|
||||
If you are using CMake build system and followed the :doc:`/get-started/windows-setup` with the ``ESP-IDF Tools Installer`` V1.2 or newer, then by default you will already have ``openocd`` installed.
|
||||
|
||||
``ESP-IDF Tools Installer`` adds ``openocd`` to the ``PATH`` so that it can be run from any directory.
|
||||
|
||||
Set up OpenOCD
|
||||
==============
|
||||
|
||||
|
||||
OpenOCD for Windows is available for download from Github:
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
Download latest release archive with `win32` in its name, for example `openocd-esp32-macos-0.10.0-win32-20180418.zip`.
|
||||
|
||||
Extract the downloaded file in ``~/esp/`` directory.
|
||||
|
||||
cd ~/esp
|
||||
unzip /c/Users/<user>/Downloads/openocd-esp32-win32-<version>.zip
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-windows
|
||||
@@ -36,7 +36,7 @@ Offset should be in hex format. To reset to the default behaviour you can specif
|
||||
|
||||
Since GDB requests memory map from OpenOCD only once when connecting to it, this command should be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case command line should look like below:
|
||||
|
||||
``bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "init; halt; esp32 appimage_offset 0x210000"``
|
||||
``openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg -c "init; halt; esp32 appimage_offset 0x210000"``
|
||||
|
||||
Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be less handy.
|
||||
|
||||
@@ -259,17 +259,13 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
|
||||
|
||||
::
|
||||
|
||||
bin/openocd -l openocd_log.txt -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
openocd -l openocd_log.txt -d 3 -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d 3`` is set. If you still like to see the log on the screen, then use another command instead:
|
||||
|
||||
::
|
||||
|
||||
bin/openocd -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg 2>&1 | tee openocd.log
|
||||
|
||||
.. note::
|
||||
|
||||
See :ref:`jtag-debugging-building-openocd` for slightly different command format, when running OpenOCD built from sources.
|
||||
openocd -d 3 -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg 2>&1 | tee openocd.log
|
||||
|
||||
Debugger:
|
||||
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
.. note::
|
||||
|
||||
If you installed openocd on Windows using the ESP-IDF Tools Installer, can run ``openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg`` without needing to change directory first, and without the ``-s share/openocd/scripts`` argument.
|
||||
Reference in New Issue
Block a user