Merge branch 'bugfix/openocd_ulp_install_instructions' into 'master'
docs: jtag-debugging: update for IDF Tools installation method Closes IDF-824 See merge request espressif/esp-idf!5803
This commit is contained in:
Ivan Grokhotkov
commit
02c7c3885e
|
|
@ -3,7 +3,7 @@ Building OpenOCD from Sources for Linux
|
|||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-linux`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Building OpenOCD from Sources for MacOS
|
|||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-macos`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Building OpenOCD from Sources for Windows
|
|||
*****************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-windows`.
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -3,7 +3,7 @@ Linux 环境下从源码编译 OpenOCD
|
|||
******************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-linux` 章节查阅。
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ MacOS 环境下从源码编译 OpenOCD
|
|||
******************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-macos` 章节查阅。
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Windows 环境下从源码编译 OpenOCD
|
|||
********************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-windows` 章节查阅。
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
|
|
|||
|
|
@ -121,20 +121,14 @@ MacOS
|
|||
|
||||
sudo kextunload -b com.apple.driver.AppleUSBFTDI
|
||||
|
||||
4. 运行 OpenOCD（以下路径为 Github 上可供下载的预编译后的 OpenOCD）::
|
||||
4. 运行 OpenOCD::
|
||||
|
||||
bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
如果 OpenOCD 是从源码编译得到的，那么路径需要做相应修改::
|
||||
|
||||
src/openocd -s tcl -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
|
||||
|
||||
5. 在另一个终端窗口，再一次加载 FTDI 串口驱动::
|
||||
|
||||
sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
|
||||
|
||||
.. include:: ./windows-openocd-note.rst
|
||||
|
||||
.. note::
|
||||
|
||||
如果你需要重启 OpenOCD，则无需再次卸载 FTDI 驱动程序，只需停止 OpenOCD 并再次启动它。只有在重新连接 ESP-WROVER-KIT 或者切换了电源的情况下才需要再次卸载驱动。
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ JTAG 调试
|
|||
:ref:`jtag-debugging-selecting-jtag-adapter`
|
||||
介绍有关 JTAG 硬件适配器的选择及参照标准。
|
||||
:ref:`jtag-debugging-setup-openocd`
|
||||
介绍如何在 :doc:`Windows <setup-openocd-windows>`，:doc:`Linux <setup-openocd-linux>` 和 :doc:`MacOS <setup-openocd-macos>` 操作系统上安装预编译好的 OpenOCD 软件包。
|
||||
介绍如何安装官方预编译好的 OpenOCD 软件包并验证是否安装成功。
|
||||
:ref:`jtag-debugging-configuring-esp32-target`
|
||||
介绍如何设置 OpenOCD 软件并安装 JTAG 硬件适配器，这两者共同组成最终的调试目标。
|
||||
:ref:`jtag-debugging-launching-debugger`
|
||||
|
|
@ -81,44 +81,28 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
|
|||
安装 OpenOCD
|
||||
------------
|
||||
|
||||
本节会介绍 OpenOCD 软件包的安装，如果你想从源码构建 OpenOCD，请参阅 :ref:`jtag-debugging-building-openocd`。默认所有 OpenOCD 相关的文件都会被存放到 ``~/esp/openocd-esp32`` 目录下，你也可以选择任何其它的目录，但相应地，你也需要调整本文档示例中使用的相对路径。
|
||||
.. highlight:: bash
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
如果你已经按照 :doc:`快速入门 <../../get-started/index>` 一文中的介绍安装好了 ESP-IDF 及其 CMake 构建系统，那么 OpenOCD 已经被默认安装到了你的开发系统中。在 :ref:`设置开发环境 <get-started-set-up-env>` 结束后，你应该能够在终端中运行如下 OpenOCD 命令::
|
||||
|
||||
Windows <setup-openocd-windows>
|
||||
Linux <setup-openocd-linux>
|
||||
MacOS <setup-openocd-macos>
|
||||
openocd --version
|
||||
|
||||
从下面选择你使用的操作系统，并按照提示进一步设置 OpenOCD。
|
||||
.. highlight:: none
|
||||
|
||||
+-------------------+-------------------+-------------------+
|
||||
| |windows-logo| | |linux-logo| | |macos-logo| |
|
||||
+-------------------+-------------------+-------------------+
|
||||
| `Windows`_ | `Linux`_ | `Mac OS`_ |
|
||||
+-------------------+-------------------+-------------------+
|
||||
终端会输出以下信息（实际版本号可能会比这里列出的更新）::
|
||||
|
||||
.. |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
|
||||
你还可以检查 ``OPENOCD_SCRIPTS`` 环境变量的值来确认 OpenOCD 配置文件的路径，Linux 和 macOS 用户可以在终端输入 ``echo $OPENOCD_SCRIPTS``，Windows 用户需要输入 ``echo %OPENOCD_SCRIPTS%``。如果终端打印了有效的路径，则表明 OpenOCD 已经被正确安装。
|
||||
|
||||
.. |macos-logo| image:: ../../../_static/macos-logo.png
|
||||
:target: ../jtag-debugging/setup-openocd-macos.html
|
||||
|
||||
.. _Windows: setup-openocd-windows.html
|
||||
.. _Linux: setup-openocd-linux.html
|
||||
.. _Mac OS: setup-openocd-macos.html
|
||||
|
||||
安装完成后，请熟悉一下 ``openocd-esp32`` 安装路径下的两个关键目录：
|
||||
|
||||
- ``bin`` 目录下包含了 OpenOCD 的可执行文件
|
||||
- ``share\openocd\scripts`` 目录下包含了一些配置文件，它们会作为命令行参数与 OpenOCD 一同被调用
|
||||
如果上述步骤没有成功执行，请返回快速入门手册，参考其中 :ref:`设置安装工具 <get-started-set-up-tools>` 章节的说明。
|
||||
|
||||
.. note::
|
||||
|
||||
上面的目录名称和结构特定于 OpenOCD 的二进制发行版，它们会被用在本指南中的 OpenOCD 示例中。从源码构建得到的 OpenOCD 存放的目录可能会不一样，所以调用 OpenOCD 的方式也会略有不同。更多详细信息请参阅 :ref:`jtag-debugging-building-openocd`。
|
||||
另外，我们还可以从源代码编译 OpenOCD 工具，相关详细信息请参阅 :ref:`jtag-debugging-building-openocd` 章节。
|
||||
|
||||
|
||||
.. _jtag-debugging-configuring-esp32-target:
|
||||
|
|
@ -154,23 +138,20 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
|
|||
|
||||
.. highlight:: bash
|
||||
|
||||
打开终端，进入安装目录并启动 OpenOCD::
|
||||
打开终端，按照快速入门中的指南 :ref:`设置好开发环境 <get-started-set-up-env>` ，然后运行如下命令，启动 OpenOCD（该命令在 Windows，Linux，和 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::
|
||||
|
||||
如上所示，``-f`` 后面的文件是特定于板载 :ref:`ESP-WROOM-32 <esp-modules-and-boards-esp32-wroom-32>` 模组的 ESP-WROVER-KIT 开发板的。您可能需要根据具体使用的硬件而提供不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
|
||||
|
||||
.. include:: ./windows-openocd-note.rst
|
||||
上述命令中 ``-f`` 选项后跟的配置文件专用于板载 :ref:`ESP-WROOM-32 <esp-modules-and-boards-esp32-wroom-32>` 模组的 ESP-WROVER-KIT 开发板。您可能需要根据具体使用的硬件而选择或修改不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
现在应该可以看到类似下面的输出（此日志来自 ESP-WROVER-KIT）::
|
||||
现在应该可以看到如下输入（此日志来自 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
|
||||
|
|
@ -198,10 +179,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
|
|||
|
||||
除此以外，还支持使用 OpenOCD 通过 JTAG 接口将应用程序镜像烧写到闪存中，命令如下::
|
||||
|
||||
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 的烧写命令 ``program_esp32`` 具有以下格式：
|
||||
|
||||
|
|
@ -265,13 +243,28 @@ ESP32 的工具链中带有 GNU 调试器（简称 GDB） ``xtensa-esp32-elf-gdb
|
|||
Linux <building-openocd-linux>
|
||||
MacOS <building-openocd-macos>
|
||||
|
||||
.. note::
|
||||
|
||||
本文档演示所使用的 OpenOCD 是 :ref:`jtag-debugging-setup-openocd` 章节中介绍的预编译好的二进制发行版，如果要使用本地从源代码构建得到的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并将配置文件的路径修改为 ``-s tcl``。
|
||||
本文档演示所使用的 OpenOCD 是 :ref:`jtag-debugging-setup-openocd` 章节中介绍的预编译好的二进制发行版。
|
||||
|
||||
具体使用示例如下::
|
||||
.. highlight:: bash
|
||||
|
||||
src/openocd -s tcl -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，这样 OpenOCD 才能找到配置文件。Linux 和 macOS 用户可以执行::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
export OPENOCD_SCRIPTS=$PWD/tcl
|
||||
|
||||
Windows 用户可以执行::
|
||||
|
||||
cd %USERPROFILE%\esp\openocd-esp32
|
||||
set "OPENOCD_SCRIPTS=%CD%\tcl"
|
||||
|
||||
运行本地编译的 OpenOCD 的示例如下（Linux 和 macOS 用户）::
|
||||
|
||||
src/openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
|
||||
|
||||
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 @@
|
|||
***************************
|
||||
在 Linux 环境下安装 OpenOCD
|
||||
***************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装 OpenOCD
|
||||
============
|
||||
|
||||
64 位 Linux 系统版本的 OpenOCD 可以直接从以下 Github 链接中下载：
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
下载文件名称包含 `linux64` 字样的最新发布的归档文件，例如 `openocd-esp32-linux64-0.10.0-esp32-20180418.tar.gz`。
|
||||
|
||||
将该文件解压缩到 ``~/esp/`` 目录下::
|
||||
|
||||
cd ~/esp
|
||||
tar -xzf ~/Downloads/openocd-esp32-linux64-<version>.tar.gz
|
||||
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
进一下配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。
|
||||
|
||||
|
||||
相关文档
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-linux
|
||||
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
***************************
|
||||
在 MacOS 环境下安装 OpenOCD
|
||||
***************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装 libusb
|
||||
===========
|
||||
|
||||
使用 `Homebrew <https://brew.sh/>`_ 或者 `Macports <https://www.macports.org/>`_ 来安装 `libusb` 软件包。
|
||||
|
||||
安装 OpenOCD
|
||||
============
|
||||
|
||||
MacOS 系统版本的 OpenOCD 可以直接从以下 Github 链接中下载：
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
下载文件名包含 `macos` 字样的最新发布的归档文件，例如 `openocd-esp32-macos-0.10.0-esp32-20180418.tar.gz`。
|
||||
|
||||
将该文件解压缩到 ``~/esp/`` 目录下::
|
||||
|
||||
cd ~/esp
|
||||
tar -xzf ~/Downloads/openocd-esp32-macos-<version>.tar.gz
|
||||
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
进一下配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。
|
||||
|
||||
|
||||
相关文档
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-macos
|
||||
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
*****************************
|
||||
在 Windows 环境下安装 OpenOCD
|
||||
*****************************
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
IDF 工具安装程序
|
||||
================
|
||||
|
||||
如果您正在使用 CMake 构建系统，并遵循 :doc:`/get-started/windows-setup` 章节的指导使用了 ``ESP-IDF Tools Installer`` 的 V1.2 及其以上版本，那么默认情况下您已经安装好了 ``OpenOCD`` 软件。
|
||||
|
||||
``ESP-IDF Tools Installer`` 会将 ``OpenOCD`` 添加到环境变量 ``PATH`` 中，这样你就可以在任何目录运行它。
|
||||
|
||||
安装 OpenOCD
|
||||
============
|
||||
|
||||
Windows 系统版本的 OpenOCD 可以直接从以下 Github 链接中下载：
|
||||
|
||||
https://github.com/espressif/openocd-esp32/releases
|
||||
|
||||
下载文件名包含 `win32` 字样的最新发布的归档文件，例如 `openocd-esp32-macos-0.10.0-win32-20180418.zip`。
|
||||
|
||||
将该文件解压缩到 ``~/esp/`` 目录下::
|
||||
|
||||
cd ~/esp
|
||||
unzip /c/Users/<user>/Downloads/openocd-esp32-win32-<version>.zip
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
进一下配置调试环境，请前往 :ref:`jtag-debugging-configuring-esp32-target` 章节。
|
||||
|
||||
|
||||
相关文档
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building-openocd-windows
|
||||
|
|
@ -35,7 +35,7 @@ ESP32 调试器支持 2 个硬件断点和 64 个软件断点。硬件断点是
|
|||
|
||||
由于 GDB 在连接 OpenOCD 时仅仅请求一次内存映射，所以可以在 TCL 配置文件中指定该命令，或者通过命令行传递给 OpenOCD。对于后者，命令行示例如下：
|
||||
|
||||
``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"``
|
||||
|
||||
另外还可以通过 OpenOCD 的 telnet 会话执行该命令，然后再连接 GDB， 不过这种方式似乎没有那么便捷。
|
||||
|
||||
|
|
@ -258,17 +258,13 @@ ESP32 的目标配置文件
|
|||
|
||||
::
|
||||
|
||||
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
|
||||
|
||||
这种方式会将日志输出到文件，但是它会阻止调试信息打印在终端上。当有大量信息需要输出的时候（比如调试等级提高到 ``-d 3``）这是个不错的选择。如果你仍然希望在屏幕上看到调试日志，请改用以下命令：
|
||||
|
||||
::
|
||||
|
||||
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::
|
||||
|
||||
如果运行的 OpenOCD 是从源码自行编译的，命令的格式会有些许不同，具体请参阅： :ref:`jtag-debugging-building-openocd`。
|
||||
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::
|
||||
|
||||
如果您在 Windows 上使用 ``ESP-IDF Tools Installer`` 安装的 OpenOCD，则无需切换目录即可运行 ``openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg`` ，也无需使用 ``-s share/openocd/scripts`` 参数指定脚本文件的搜索路径。
|
||||
|
|
@ -133,6 +133,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
|||
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
第二步：获取 ESP-IDF
|
||||
===========================
|
||||
|
|
@ -181,6 +182,7 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
|
|||
git submodule update --init
|
||||
|
||||
.. _get-started-setup-path:
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
第三步：设置环境变量
|
||||
===========================
|
||||
|
|
|
|||
Loading…
Reference in a new issue