Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: jtag-debugging: update for IDF Tools installation method

Browse source 
- 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 2019-08-15 18:37:52 +02:00
parent 5863509804
commit 209fdc1e05
13 changed files with 47 additions and 307 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/en/api-guides/jtag-debugging/configure-wrover.rst
View file

@ -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.

83
docs/en/api-guides/jtag-debugging/index.rst
View file

@ -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:

34
docs/en/api-guides/jtag-debugging/setup-openocd-linux.rst
View file

@ -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

39
docs/en/api-guides/jtag-debugging/setup-openocd-macos.rst
View file

@ -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

40
docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
View file

@ -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

10
docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
View file

@ -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:

3
docs/en/api-guides/jtag-debugging/windows-openocd-note.rst
View file

@ -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.

10
docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst
View file

@ -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 或者切换了电源的情况下才需要再次卸载驱动。

34
docs/zh_CN/api-guides/jtag-debugging/setup-openocd-linux.rst
View file

@ -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

39
docs/zh_CN/api-guides/jtag-debugging/setup-openocd-macos.rst
View file

@ -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

39
docs/zh_CN/api-guides/jtag-debugging/setup-openocd-windows.rst
View file

@ -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

10
docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst
View file

@ -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 端：

3
docs/zh_CN/api-guides/jtag-debugging/windows-openocd-note.rst
View file

@ -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`` 参数指定脚本文件的搜索路径。