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
espressif · Aug 20, 2019 · 02c7c38 · 02c7c38
2 parents 636c6a9 + 7237e6f
commit 02c7c38
Show file tree

Hide file tree

Showing 21 changed files with 94 additions and 359 deletions.
diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst
@@ -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

diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst
@@ -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
 

diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
@@ -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
 

diff --git a/docs/en/api-guides/jtag-debugging/configure-wrover.rst b/docs/en/api-guides/jtag-debugging/configure-wrover.rst
@@ -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.

diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst
@@ -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. 
-
-.. toctree::
-    :hidden:
-
-    Windows <setup-openocd-windows>
-    Linux <setup-openocd-linux> 
-    MacOS <setup-openocd-macos> 
-
-Pick up your OS below and follow provided instructions to setup OpenOCD.
+.. highlight:: bash
 
-+-------------------+-------------------+-------------------+
-| |windows-logo|    | |linux-logo|      | |macos-logo|      |
-+-------------------+-------------------+-------------------+
-| `Windows`_        | `Linux`_          | `Mac OS`_         |
-+-------------------+-------------------+-------------------+
+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-logo| image:: ../../../_static/windows-logo.png
-    :target: ../jtag-debugging/setup-openocd-windows.html
+    openocd --version
 
-.. |linux-logo| image:: ../../../_static/linux-logo.png
-    :target: ../jtag-debugging/setup-openocd-linux.html
+.. highlight:: none
 
-.. |macos-logo| image:: ../../../_static/macos-logo.png
-    :target: ../jtag-debugging/setup-openocd-macos.html
+The output should be as follows (although the version may be more recent than listed here)::
 
-.. _Windows: ../jtag-debugging/setup-openocd-windows.html
-.. _Linux: ../jtag-debugging/setup-openocd-linux.html
-.. _Mac OS: ../jtag-debugging/setup-openocd-macos.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
 
-After installation is complete, get familiar with two key directories inside ``openocd-esp32`` installation folder:
+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.
 
-* ``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`.
+
+.. highlight:: bash
+
+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::
+
+    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::
 
-    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``.
+    src/openocd -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
 
-    Example of invoking OpenOCD build locally from sources::
+and Windows::
 
-        src/openocd -s tcl -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
+    src\openocd -f interface\ftdi\esp32_devkitj_v1.cfg -f board\esp-wroom-32.cfg
 
 
 .. _jtag-debugging-tips-and-quirks:

diff --git a/docs/en/api-guides/jtag-debugging/setup-openocd-linux.rst b/docs/en/api-guides/jtag-debugging/setup-openocd-linux.rst
diff --git a/docs/en/api-guides/jtag-debugging/setup-openocd-macos.rst b/docs/en/api-guides/jtag-debugging/setup-openocd-macos.rst
diff --git a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
@@ -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:
 

diff --git a/docs/en/api-guides/jtag-debugging/windows-openocd-note.rst b/docs/en/api-guides/jtag-debugging/windows-openocd-note.rst
diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst
@@ -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

diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-macos.rst
@@ -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
 

diff --git a/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-windows.rst
@@ -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

diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-wrover.rst
@@ -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 或者切换了电源的情况下才需要再次卸载驱动。