From 7237e6fab72ff37b755476de5c03b5fc82323099 Mon Sep 17 00:00:00 2001 From: suda-morris <362953310@qq.com> Date: Fri, 16 Aug 2019 15:34:49 +0800 Subject: [PATCH] docs: jtag-debugging: update translation --- .../jtag-debugging/building-openocd-linux.rst | 2 +- .../jtag-debugging/building-openocd-macos.rst | 2 +- .../building-openocd-windows.rst | 2 +- .../jtag-debugging/building-openocd-linux.rst | 2 +- .../jtag-debugging/building-openocd-macos.rst | 2 +- .../building-openocd-windows.rst | 2 +- .../zh_CN/api-guides/jtag-debugging/index.rst | 85 +++++++++---------- docs/zh_CN/get-started/index.rst | 2 + 8 files changed, 47 insertions(+), 52 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 index 754c1c5cf7..846161881c 100644 --- 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 `_. 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 `_. 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 index ab5656661f..0edb05149d 100644 --- 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 `_. 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 `_. 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 index 2452235176..3163c640f8 100644 --- 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 `_. 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 `_. 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/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/zh_CN/api-guides/jtag-debugging/building-openocd-linux.rst index f237599b69..9041dd1195 100644 --- 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 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-linux` 章节查阅。 +除了从 `Espressif 官方 `_ 直接下载 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 index 95c42b7e36..376aba6ba7 100644 --- 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 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-macos` 章节查阅。 +除了从 `Espressif 官方 `_ 直接下载 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 index a9a44c842e..1a554b7515 100644 --- 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 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :doc:`setup-openocd-windows` 章节查阅。 +除了从 `Espressif 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。 .. highlight:: bash diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index 8d525a77ca..ba73268537 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -11,7 +11,7 @@ JTAG 调试 :ref:`jtag-debugging-selecting-jtag-adapter` 介绍有关 JTAG 硬件适配器的选择及参照标准。 :ref:`jtag-debugging-setup-openocd` - 介绍如何在 :doc:`Windows `，:doc:`Linux ` 和 :doc:`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:`设置开发环境 ` 结束后，你应该能够在终端中运行如下 OpenOCD 命令:: - Windows - Linux - 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:`设置安装工具 ` 章节的说明。 .. 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:`设置好开发环境 ` ，然后运行如下命令，启动 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-WROVER-KIT 开发板的。您可能需要根据具体使用的硬件而提供不同的配置文件，相关指导请参阅 :ref:`jtag-debugging-tip-openocd-configure-target`。 - -.. include:: ./windows-openocd-note.rst + 上述命令中 ``-f`` 选项后跟的配置文件专用于板载 :ref:`ESP-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 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: diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 9f0a9ee900..06428eb994 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -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: 第三步：设置环境变量 ===========================