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 423a177dc1..4c19ae46f5 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst @@ -3,19 +3,21 @@ 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 :ref:`jtag-debugging-setup-openocd`. +.. note:: -.. highlight:: bash + This document outlines how to build a binary of OpenOCD from its source files instead of downloading the pre-built binary. For a quick setup, users can download a pre-built binary of OpenOCD from `Espressif GitHub `_ instead of compiling it themselves (see :ref:`jtag-debugging-setup-openocd` for more details). .. note:: - Following instructions are assumed to be runned in MSYS2 environment with MINGW32 subsystem! + All code snippets in this document are assumed to be running in an MSYS2 shell with the MINGW32 subsystem. Install Dependencies ==================== -Install packages that are required to compile OpenOCD:: +Install packages that are required to compile OpenOCD: + +.. code-block:: bash pacman -S --noconfirm --needed autoconf automake git make \ mingw-w64-i686-gcc \ @@ -29,31 +31,40 @@ Install packages that are required to compile OpenOCD:: Download Sources of OpenOCD =========================== -The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif's GitHub under https://github.com/espressif/openocd-esp32. These source files can be pulled via Git using the following commands: + +.. code-block:: bash cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git - The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory. Downloading libusb ================== -Build and export variables for a following OpenOCD compilation:: +The libusb library is also required when building OpenOCD. The following commands will download a particular release of libusb and uncompress it to the current directory. + +.. code-block:: bash wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z 7z x -olibusb ./libusb-1.0.22.7z + +We now need to export the following variables such that the libusb library gets linked into the OpenOCD build. + +.. code-block:: bash + export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0" export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll" - Build OpenOCD ============= -Proceed with configuring and building OpenOCD:: +The following commands will configure OpenOCD then build it. + +.. code-block:: bash cd ~/esp/openocd-esp32 export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error" @@ -64,7 +75,12 @@ Proceed with configuring and building OpenOCD:: cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src -Optionally you can add ``make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten. Also you could use ``export DESTDIR="/custom/install/dir"; make install``. +Once the build is completed, the OpenOCD binary will be placed in ``~/esp/openocd-esp32/src/``. + +You can then optionally call ``make install``. This will copy the OpenOCD binary to a user specified location. + +- This location can be specified when OpenOCD is configured, or by setting ``export DESTDIR="/custom/install/dir"`` before calling ``make install``. +- If you have an existing OpenOCD (from e.g. another development platform), you may want to skip this call as your existing OpenOCD may get overwritten. .. note:: @@ -81,7 +97,9 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will Full Listing ============ -A complete described previously process is provided below for the faster execution, e.g. as a shell script:: +For greater convenience, all of commands called throughout the OpenOCD build process have been listed in the code snippet below. Users can copy this code snippet into a shell script then execute it: + +.. code-block:: bash pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip cd ~/esp @@ -106,8 +124,7 @@ A complete described previously process is provided below for the faster executi # cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin - Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. \ No newline at end of file diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst index 0d28f2b4fb..364eb2364d 100644 --- a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst @@ -2,7 +2,7 @@ Configure Other JTAG Interface ============================== :link_to_translation:`zh_CN:[中文]` -Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working. +For guidance about which JTAG interface to select to enable operation with OpenOCD and {IDF_TARGET_NAME}, refer to section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the three configuration steps below to get it working. .. only:: SOC_USB_SERIAL_JTAG_SUPPORTED @@ -14,34 +14,35 @@ Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what Burning eFuses is an irreversible operation, so consider both options below before starting the process. - - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be useable, i.e. flashing and monitoring over USB CDC will still work. + - Burning ``DIS_USB_JTAG`` eFuse will permanently disable the connection between USB_SERIAL_JTAG and the JTAG port of the CPU. JTAG interface can then be connected to |jtag-gpio-list|. Note that USB CDC functionality of USB_SERIAL_JTAG will still be usable, i.e. flashing and monitoring over USB CDC will still work. - Burning ``JTAG_SEL_ENABLE`` eFuse will enable selection of JTAG interface by a strapping pin, |jtag-sel-gpio|. If the strapping pin is low when {IDF_TARGET_NAME} is reset, JTAG interface will use |jtag-gpio-list|. If the strapping pin is high, USB_SERIAL_JTAG will be used as the JTAG interface. + Configure Hardware ^^^^^^^^^^^^^^^^^^ -1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication. +1. Identify all pins/signals on JTAG interface and {IDF_TARGET_NAME} board that should be connected to establish communication. .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: jtag-pins :end-before: --- -2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation. +2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other hardware that may disturb JTAG operation. -3. Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface. +3. Connect identified pin/signals of {IDF_TARGET_NAME} and JTAG interface. Configure Drivers ^^^^^^^^^^^^^^^^^ -You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details. + +You may need to install driver software to make JTAG work with computer. Refer to documentation of your JTAG adapter for related details. Connect ^^^^^^^ -Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer. +Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if the JTAG interface is visible on the computer. -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`. - +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`. \ No newline at end of file diff --git a/docs/en/hw-reference/esp32/get-started-devkitc.rst b/docs/en/hw-reference/esp32/get-started-devkitc.rst index c1b1dcd158..2572fd5a50 100644 --- a/docs/en/hw-reference/esp32/get-started-devkitc.rst +++ b/docs/en/hw-reference/esp32/get-started-devkitc.rst @@ -9,7 +9,7 @@ This guide shows how to start using the ESP32-DevKitC V4 development board. What You Need ------------- -* ESP32-DevKitC V4 board +* :ref:`ESP32-DevKitC V4 board ` * USB A / micro USB B cable * Computer running Windows, Linux, or macOS @@ -177,13 +177,12 @@ The component C15 may cause the following issues on earlier ESP32-DevKitC V4 boa * The board may boot into Download mode * If you output clock on GPIO0, C15 may impact the signal -In case these issues occur, please remove the component. The figure below shows C15 highlighted in yellow. +In case these issues occur, please remove the component. The figure below shows the location of C15 highlighted in yellow. .. figure:: ../../../_static/esp32-devkitc-c15-location.png :align: center :alt: Location of C15 (colored yellow) on ESP32-DevKitC V4 board - :figclass: align-center :width: 30% Location of C15 (yellow) on ESP32-DevKitC V4 board @@ -211,28 +210,19 @@ Board Dimensions Related Documents ----------------- -* `ESP32-DevKitC V4 schematics`_ (PDF) -* `ESP32 Datasheet`_ (PDF) -* `ESP32-WROOM-DA Datasheet`_ (PDF) -* `ESP32-WROOM-32 Datasheet`_ (PDF) -* `ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet`_ (PDF) -* `ESP32-WROVER Datasheet`_ (PDF) -* `ESP32-WROVER-B Datasheet`_ (PDF) -* `ESP Product Selector`_ +* `ESP32-DevKitC V4 schematics `_ (PDF) +* `ESP32 Datasheet `_ (PDF) +* `ESP32-WROOM-32 Datasheet `_ (PDF) +* `ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet `_ (PDF) +* `ESP32-WROOM-DA Datasheet `_ (PDF) +* `ESP32-WROVER Datasheet `_ (PDF) +* `ESP32-WROVER-B Datasheet `_ (PDF) +* `ESP Product Selector `_ For further design documentation for the board, please contact us at `sales@espressif.com `_. -.. _ESP32-DevKitC V4 schematics: https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf -.. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf -.. _ESP32-WROOM-32 Datasheet: https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf -.. _ESP32-WROOM-32D and ESP32-WROOM-32U Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf -.. _ESP32-WROVER Datasheet: https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf -.. _ESP32-WROVER-B Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_en.pdf -.. _ESP32-WROOM-DA Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-wroom-da_datasheet_en.pdf -.. _ESP Product Selector: https://products.espressif.com/#/product-selector?names= - .. toctree:: :hidden: - get-started-devkitc-v2 + get-started-devkitc-v2 \ No newline at end of file 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 25f8d684ca..e96a859cc6 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,56 +3,84 @@ Windows 环境下从源码编译 OpenOCD ******************************** :link_to_translation:`en:[English]` -除了从 `Espressif 官方 `_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。 +.. note:: + 本文介绍了如何从 OpenOCD 源文件构建二进制文件。如果您想要更快速地构建，也可以从 `乐鑫 GitHub `_ 直接下载 OpenOCD 的预构建二进制文件，而无需自己编译（详细信息，请参阅 :ref:`jtag-debugging-setup-openocd`）。 -.. highlight:: bash +.. note:: -下载 OpenOCD 源码 -================= - -支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码:: - - cd ~/esp - git clone --recursive https://github.com/espressif/openocd-esp32.git - -克隆后的源代码被保存在 ``~/esp/openocd-esp32`` 目录中。 + 本文涉及的命令行操作均在装有 MINGW32 子系统的 MSYS2 shell 环境中进行了验证。 安装依赖的软件包 ================ -安装编译 OpenOCD 所需的软件包。 +安装编译 OpenOCD 所需的软件包： -.. note:: +.. code-block:: bash - 依次安装以下软件包，检查安装是否成功，然后继续下一个软件包的安装。在进行下一步操作之前，要先解决当前报告的问题。 + pacman -S --noconfirm --needed autoconf automake git make \ + mingw-w64-i686-gcc \ + mingw-w64-i686-toolchain \ + mingw-w64-i686-libtool \ + mingw-w64-i686-pkg-config \ + mingw-w64-cross-winpthreads-git \ + p7zip -:: - pacman -S libtool - pacman -S autoconf - pacman -S automake - pacman -S texinfo - pacman -S mingw-w64-i686-libusb-compat-git - pacman -S pkg-config +下载 OpenOCD 源码 +================= -.. note:: +支持 {IDF_TARGET_NAME} 的 OpenOCD 源码可以从乐鑫官方 GitHub 获取，网址为 https://github.com/espressif/openocd-esp32。您可以在 Git 中使用以下命令来拉取源代码： - 安装 ``pkg-config`` 会破坏 esp-idf 的工具链，因而在 OpenOCD 构建完成后，应将其卸载。详见文末进一步说明。如果想要再次构建 OpenOCD，你需要再次运行 ``pacman -S pkg-config``。此步骤安装的其他软件包（在 ``pkg-config`` 之前）并不会出现这一问题。 +.. code-block:: bash + + cd ~/esp + git clone --recursive https://github.com/espressif/openocd-esp32.git + +克隆后的源代码保存在 ``~/esp/openocd-esp32`` 目录下。 + + +下载 libusb +================ + +构建 OpenOCD 需使用 libusb 库。请执行以下命令来下载特定版本的 libusb，并将其解压至当前目录。 + +.. code-block:: bash + + wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z + 7z x -olibusb ./libusb-1.0.22.7z + +现在需要导出以下变量，以便将 libusb 库与 OpenOCD 构建相关联。 + +.. code-block:: bash + + export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0" + export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll" 构建 OpenOCD ============ -配置和构建 OpenOCD 的流程如下:: +配置和构建 OpenOCD，请参考以下命令： + +.. code-block:: bash cd ~/esp/openocd-esp32 + export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error" ./bootstrap - ./configure + ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32 make + cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src + cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src -你可以选择最后再执行 ``sudo make install`` ，如果你已经安装过别的开发平台的 OpenOCD，请跳过这个步骤，因为它可能会覆盖掉原来的 OpenOCD。 + +构建完成后，OpenOCD 的二进制文件将被保存于 ``~/esp/openocd-esp32/src/`` 目录下。 + +您也可以调用 ``make install``，将其复制到指定位置。 + +- 您可以在配置 OpenOCD 时指定这一位置，也可以在调用 ``make install`` 前设置 ``export DESTDIR="/custom/install/dir"``。 +- 如果您已经安装过其他开发平台的 OpenOCD，请跳过此步骤，否则原来的 OpenOCD 可能会被覆盖。 .. note:: @@ -61,15 +89,42 @@ Windows 环境下从源码编译 OpenOCD * 如果 ``./configure`` 成功运行，JTAG 被使能的信息会被打印在 ``OpenOCD configuration summary`` 下面。 * 如果您的设备信息未显示在日志中，请根据 ``../openocd-esp32/doc/INSTALL.txt`` 文中的描述使用 ``./configure`` 启用它。 * 有关编译 OpenOCD 的详细信息，请参阅 ``openocd-esp32/README.Windows``。 + * 请记得将 `libusb-1.0.dll` 和 `libwinpthread-1.dll` 从 ``~/esp/openocd-esp32/src`` 复制到 `OOCD_INSTALLDIR/bin`。 -一旦 ``make`` 过程成功完成，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录中。 +一旦 ``make`` 过程完成，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录下。 -如安装依赖步骤所述，最后还需要移除 ``pkg-config`` 软件包:: - pacman -Rs pkg-config +完整编译过程 +============== + +OpenOCD 编译过程中所调用的所有命令都已包含在以下代码片段中，您可以将其复制到 shell 脚本中，以便快速执行: + +.. code-block:: bash + + pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip + cd ~/esp + git clone --recursive https://github.com/espressif/openocd-esp32.git + + wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z + 7z x -olibusb ./libusb-1.0.22.7z + export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll" + + export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error" + cd ~/esp/openocd-esp32 + ./bootstrap + ./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32 + make + cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src + cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src + + # # optional + # export DESTDIR="$PWD" + # make install + # cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin + # cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin 下一步 ====== -想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。 +想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。 \ No newline at end of file diff --git a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst index ad453cc3d3..69e998acbd 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/configure-other-jtag.rst @@ -5,23 +5,38 @@ 关于适配 OpenOCD 和 {IDF_TARGET_NAME} 的 JTAG 接口选择问题，请参考 :ref:`jtag-debugging-selecting-jtag-adapter` 章节，确保 JTAG 适配器能够与 OpenOCD 和 {IDF_TARGET_NAME} 一同工作。然后按照以下三个步骤进行设置，使其正常工作。 +.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED + + 配置 eFuses + ^^^^^^^^^^^^^^^^ + + {IDF_TARGET_NAME} JTAG 接口默认连接至 :doc:`内置 USB_SERIAL_JTAG 外设 `。要使用外部 JTAG 适配器，需将 JTAG 接口切换至 GPIO 管脚。您可以使用 `espefuse.py` 工具来烧录 eFuse，以完成接口转换。 + + 烧录 eFuse 是一项不可逆的操作，所以在开始之前，请考虑以下两点： + + - 烧录 `DIS_USB_JTAG` eFuse 后，USB_SERIAL_JTAG 和 CPU 的 JTAG 接口之间的连接将被永久禁用，此后您可以将 JTAG 接口连接到 |jtag-gpio-list|。注意，烧录后，USB_SERIAL_JTAG 的 USB CDC 功能仍然可用，即仍然可以通过 USB CDC 进行烧录和 log 查看。 + + - 烧录 ``JTAG_SEL_ENABLE`` eFuse 后，JTAG 接口的选择将由 strapping 管脚 |jtag-sel-gpio| 来决定。{IDF_TARGET_NAME} 复位时，如果该 strapping 管脚为低电平，JTAG 接口将使用 |jtag-gpio-list|，如果为高电平，USB_SERIAL_JTAG 将被用作 JTAG 接口。 + + 配置硬件 ^^^^^^^^ -1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的引脚/信号。 +1. 找到 JTAG 接口和 {IDF_TARGET_NAME} 板上需要相互连接并建立通信的所有管脚或信号。 .. include:: {IDF_TARGET_PATH_NAME}.inc :start-after: jtag-pins :end-before: --- -2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的的引脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。 +2. 检查 {IDF_TARGET_NAME} 上用于 JTAG 通信的管脚是否被连接到了其它硬件上，这可能会影响 JTAG 的工作。 -3. 连接 {IDF_TARGET_NAME} 和 JTAG 接口上的引脚/信号。 +3. 连接 {IDF_TARGET_NAME} 和 JTAG 接口上的管脚或信号。 配置驱动 ^^^^^^^^ -你可能还需要安装软件驱动，才能使 JTAG 在计算机上正常工作，请参阅你所使用的 JTAG 适配器的有关文档，获取相关详细信息。 + +您可能还需要安装软件驱动，才能使 JTAG 在计算机上正常工作，请参阅您所使用的 JTAG 适配器的有关文档，获取相关详细信息。 连接 @@ -30,5 +45,4 @@ 将 JTAG 接口连接到计算机，打开 {IDF_TARGET_NAME} 和 JTAG 接口板上的电源，然后检查计算机是否可以识别到 JTAG 接口。 -要继续设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 - +要继续设置调试环境，请前往 :ref:`jtag-debugging-run-openocd` 章节。 \ No newline at end of file diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc index 948a8e5c0f..85adfe2778 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32c3.inc @@ -7,7 +7,6 @@ .. These code blocks can be moved back to the main .rst files, with target-specific .. file names being replaced by substitutions. - .. run-openocd :: @@ -22,21 +21,25 @@ :: - user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg - Open On-Chip Debugger v0.10.0-esp32-20200420 (2020-04-20-16:15) + user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32c3-builtin.cfg + Open On-Chip Debugger v0.10.0-esp32-20201202-26-g05a036c2 (2021-03-15-17:18) Licensed under GNU GPL v2 For bug reports, read - http://openocd.org/doc/doxygen/bugs.html - none separate - adapter speed: 20000 kHz + http://openocd.org/doc/doxygen/bugs.html + Info : only one transport option; autoselect 'jtag' + Warn : Transport "jtag" was already selected force hard breakpoints - Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling" - Info : clock speed 20000 kHz - Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F). + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255 + Info : clock speed 40000 kHz + Info : JTAG tap: esp32c3.cpu tap/device found: 0x00005c25 (mfg: 0x612 (Espressif Systems), part: 0x0005, ver: 0x0) + Info : datacount=2 progbufsize=16 + Info : Examined RISC-V core; found 1 harts + Info : hart 0: XLEN=32, misa=0x40101104 + Info : Listening on port 3333 for gdb connections -.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg`` +.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32c3-builtin.cfg`` --- @@ -44,7 +47,7 @@ :: - openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit" + openocd -f board/esp32c3-builtin.cfg -c "program_esp filename.bin 0x10000 verify exit" --- @@ -52,7 +55,7 @@ .. code-block:: bash - src/openocd -f board/esp32s2-kaluga-1.cfg + src/openocd -f board/esp32c3-builtin.cfg --- @@ -60,13 +63,13 @@ .. code-block:: batch - src\openocd -f board/esp32s2-kaluga-1.cfg + src\openocd -f board/esp32c3-builtin.cfg --- .. idf-py-openocd-default-cfg -.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg`` +.. |idf-py-def-cfg| replace:: ``-f board/esp32c3-builtin.cfg`` --- @@ -74,26 +77,28 @@ :: - openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp appimage_offset 0x210000" + openocd -f board/esp32c3-builtin.cfg -c "init; halt; esp appimage_offset 0x210000" --- .. openocd-cfg-files -.. list-table:: ESP32-S2 相关的 OpenOCD 配置文件 +.. list-table:: ESP32-C3 相关的 OpenOCD 配置文件 :widths: 25 75 :header-rows: 1 - * - 名字 + * - 名称 - 描述 - * - ``board/esp32s2-kaluga-1.cfg`` - - ESP32-S2-Kaluga-1 开发板配置文件，内部已包含 ESP32-S2 目标配置和 JTAG 适配器配置 - * - ``target/esp32s2.cfg`` - - ESP32-S2 目标配置文件，可以和某个 ``interface/`` 下的配置文件一同使用 - * - ``interface/ftdi/esp32s2_kaluga_v1.cfg`` - - 适用于 ESP32-S2-Kaluga-1 开发板的 JTAG 适配器配置文件 + * - ``board/esp32c3-builtin.cfg`` + - 通过内置 USB 连接的 ESP32-C3 系列开发板配置文件，包含 ESP32-C3 目标配置和 JTAG 适配器配置。 + * - ``board/esp32c3-ftdi.cfg`` + - 通过与 ESP-Prog 兼容的 FTDI 对 ESP32-C3 调试的配置文件，包括 ESP32-C3 目标配置和 JTAG 适配器配置。 + * - ``target/esp32c3.cfg`` + - ESP32-C3 目标配置文件。可以和某个 ``interface/`` 下的配置文件一同使用。 + * - ``interface/esp_usb_jtag.cfg`` + - 适用于 ESP32-C3 的 JTAG 适配器配置文件。 * - ``interface/ftdi/esp32_devkitj_v1.cfg`` - - 适用于 ESP-Prog 板子的 JTAG 适配器配置文件 + - 适用于 ESP-Prog 的 JTAG 适配器配置文件。 --- @@ -105,28 +110,31 @@ .. jtag-pins -.. list-table:: ESP32-S2 引脚和 JTAG 接口信号 +.. list-table:: ESP32-C3 管脚和 JTAG 接口信号 :widths: 25 75 :header-rows: 1 - * - ESP32-S2 引脚 + * - ESP32-C3 管脚 - JTAG 信号 - * - MTDO / GPIO40 + * - MTDO / GPIO7 - TDO - * - MTDI / GPIO41 + * - MTDI / GPIO5 - TDI - * - MTCK / GPIO39 + * - MTCK / GPIO6 - TCK - * - MTMS / GPIO42 + * - MTMS / GPIO4 - TMS +.. |jtag-sel-gpio| replace:: GPIO10 +.. |jtag-gpio-list| replace:: GPIO4-GPIO7 + --- .. run-openocd-d3 :: - openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg + openocd -l openocd_log.txt -d3 -f board/esp32c3-builtin.cfg --- @@ -134,7 +142,7 @@ :: - openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log + openocd -d3 -f board/esp32c3-builtin.cfg 2>&1 | tee openocd.log --- @@ -142,19 +150,19 @@ :: - xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" + riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" --- .. devkit-defs -.. |devkit-name| replace:: ESP-S2-Kaluga-1 -.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/index>` +.. |devkit-name| replace:: ESP32-C3 +.. |devkit-name-with-link| replace:: :doc:`ESP32-C3 <../../hw-reference/index>` --- .. devkit-hw-config -* 开箱即用，ESP32-S2-Kaluga-1 不需要任何其他硬件配置即可进行 JTAG 调试。 但是，如果遇到问题，请检查 “JTAG” DIP 开关的 2～5 号是否在 “ON” 的位置。 +* 开箱即用，ESP32-C3 不需要任何其他硬件配置即可进行 JTAG 调试。 --- diff --git a/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc b/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc index a3f421da95..39a9ec404a 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc +++ b/docs/zh_CN/api-guides/jtag-debugging/esp32s3.inc @@ -129,6 +129,9 @@ * - MTMS - TMS +.. |jtag-sel-gpio| replace:: GPIO3 +.. |jtag-gpio-list| replace:: GPIO39-GPIO42 + --- .. run-openocd-d3 diff --git a/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst b/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst index 78ff1621b7..5fe3ef3e2d 100644 --- a/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst +++ b/docs/zh_CN/hw-reference/esp32/get-started-devkitc.rst @@ -5,6 +5,7 @@ ESP32-DevKitC V4 入门指南 本指南介绍了如何开始使用 ESP32-DevKitC V4 开发板。 + 准备工作 ----------- @@ -35,7 +36,6 @@ ESP32-DevKitC V4 是 `乐鑫 `_ 一款基于 ESP32 的小 - `ESP32-WROVER-IE `_ - `ESP32-WROOM-DA `_ - - 可选排针或排母 详情请见 `乐鑫产品选型工具 `__。 @@ -82,7 +82,7 @@ ESP32-DevKitC V4 开发板的主要组件、接口及控制方式见下。 .. note:: - 管脚 GPIO16 和 GPIO17 仅适用于板载 ESP32-WROOM 系列和 ESP32-SOLO-1 的开发板，保留内部使用。 + 管脚 GPIO16 和 GPIO17 仅适用于板载 ESP32-WROOM 系列和 ESP32-SOLO-1 的开发板，板载 ESP32-WROVER 系列开发板的管脚 GPIO16 和 GPIO17 保留内部使用。 电源选项 @@ -195,6 +195,7 @@ ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。 现在，请前往 :doc:`../../get-started/index` 中的 :ref:`get-started-step-by-step` 章节，查看如何设置开发环境，并尝试将示例项目烧录至您的开发板。 + 开发板尺寸 ------------- @@ -213,12 +214,15 @@ ESP32-DevKitC V4 上电前，请首先确认开发板完好无损。 * `《ESP32 技术规格书》 `_ (PDF) * `《ESP32-WROOM-32 技术规格书》 `_ (PDF) * `《ESP32-WROOM-32D & ESP32-WROOM-32U 技术规格书》 `_ (PDF) +* `《ESP32-WROOM-DA 技术规格书》 `_ (PDF) * `《ESP32-WROVER 技术规格书》 `_ (PDF) * `《ESP32-WROVER-B 技术规格书》 `_ (PDF) -* `《ESP32-WROOM-DA 技术规格书》 `_ (PDF) -* `乐鑫产品选型工具 `__ +* `乐鑫产品选型工具 `_ + +有关本开发板的更多设计文档，请联系我们的商务部门 `sales@espressif.com `_。 + .. toctree:: :hidden: - get-started-devkitc-v2 + get-started-devkitc-v2 \ No newline at end of file