Skip to content

Commit

Permalink
Merge branch 'doc/jtag_debug_zh_CN' into 'master'
Browse files Browse the repository at this point in the history 
zh_CN translation of JTAG debugging

See merge request idf/esp-idf!3709
  • Loading branch information
@projectgus
projectgus committed Mar 11, 2019
2 parents 9679be1 + 5b93819 commit 79ca95d
Show file tree
Hide file tree
Showing 27 changed files with 2,147 additions and 152 deletions.
Binary file added docs/_static/jtag-debugging-overview_zh.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 2 additions & 1 deletion docs/en/api-guides/jtag-debugging/building-openocd-linux.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
***************************************
Building OpenOCD from Sources for Linux
***************************************
:link_to_translation:`zh_CN:[中文]`

The following instructions are alternative to downloading binary OpenOCD from Espressif website. 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 :doc:`setup-openocd-linux`.


.. highlight:: bash
Expand Down
7 changes: 4 additions & 3 deletions docs/en/api-guides/jtag-debugging/building-openocd-macos.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
***************************************
Building OpenOCD from Sources for MacOS
***************************************
:link_to_translation:`zh_CN:[中文]`

The following instructions are alternative to downloading binary OpenOCD from Espressif website. 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 :doc:`setup-openocd-macos`.

.. highlight:: bash

Expand All @@ -22,7 +23,7 @@ Install Dependencies

Install packages that are required to compile OpenOCD using Homebrew::

brew install automake libtool libusb wget [email protected] pkg-config
brew install automake libtool libusb wget [email protected] pkg-config

Build OpenOCD
=============
Expand Down Expand Up @@ -51,4 +52,4 @@ Next Steps

To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`.



19 changes: 10 additions & 9 deletions docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
*****************************************
Building OpenOCD from Sources for Windows
*****************************************
:link_to_translation:`zh_CN:[中文]`

The following instructions are alternative to downloading binary OpenOCD from Espressif website. 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 :doc:`setup-openocd-windows`.


.. highlight:: bash
Expand All @@ -29,16 +30,16 @@ Install packages that are required to compile OpenOCD:

::

pacman -S libtool
pacman -S autoconf
pacman -S automake
pacman -S texinfo
pacman -S mingw-w64-i686-libusb-compat-git
pacman -S pkg-config
pacman -S libtool
pacman -S autoconf
pacman -S automake
pacman -S texinfo
pacman -S mingw-w64-i686-libusb-compat-git
pacman -S pkg-config

.. note::

Installation of ``pkg-config`` is breaking operation of esp-idf toolchain. After building of OpenOCD it should be uninstalled. It be covered at the end of this instruction. To build OpenOCD again, you will need to run ``pacman -S pkg-config`` once more. This issue does not concern other packages installed in this step (before ``pkg-config``).
Installation of ``pkg-config`` is breaking operation of esp-idf toolchain. After building of OpenOCD it should be uninstalled. It be covered at the end of this instruction. To build OpenOCD again, you will need to run ``pacman -S pkg-config`` once more. This issue does not concern other packages installed in this step (before ``pkg-config``).


Build OpenOCD
Expand All @@ -65,7 +66,7 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will

Remove ``pkg-config``, as discussed during installation of dependencies::

pacman -Rs pkg-config
pacman -Rs pkg-config


Next Steps
Expand Down
1 change: 1 addition & 0 deletions docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
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 ESP32. Then follow three configuration steps below to get it working.

Expand Down
22 changes: 11 additions & 11 deletions docs/en/api-guides/jtag-debugging/configure-wrover.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
Configure WROVER JTAG Interface
===============================
:link_to_translation:`zh_CN:[中文]`

All versions of ESP32 WROVER KIT boards have JTAG functionality build in. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.
All versions of ESP-WROVER-KIT boards have JTAG functionality build in. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.


Configure Hardware
Expand Down Expand Up @@ -29,17 +30,17 @@ Configure Hardware
Configure USB Drivers
^^^^^^^^^^^^^^^^^^^^^

Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP32 WROVER KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP-WROVER-KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.

.. note:: ESP32 WROVER KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
.. note:: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.


Windows
"""""""

1. Using standard USB A / micro USB B cable connect ESP32 WROVER KIT to the computer. Switch the WROVER KIT on.
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the WROVER KIT on.

2. Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then then download them from http://www.ftdichip.com/Drivers/D2XX.htm and install manually.
2. Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then download them from http://www.ftdichip.com/Drivers/D2XX.htm and install manually.

3. Download Zadig tool (Zadig_X.X.exe) from http://zadig.akeo.ie/ and run it.

Expand All @@ -60,13 +61,13 @@ Windows

Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.

Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.


Linux
"""""

1. Using standard USB A / micro USB B cable connect ESP32 WROVER KIT board to the computer. Power on the board.
1. Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on the board.

.. highlight:: none

Expand All @@ -79,7 +80,7 @@ Linux
crw-rw---- 1 root dialout 188, 1 Jul 10 19:04 /dev/ttyUSB1


3. Following section "Permissions delegation" in OpenOCD's README, set up the access permissions to both USB ports.
3. Following section "Permissions delegation" in `OpenOCD's README <https://sourceforge.net/p/openocd/code/ci/master/tree/README>`_, set up the access permissions to both USB ports.

4. Log off and login, then cycle the power to the board to make the changes effective. In terminal enter again ``ls -l /dev/ttyUSB*`` command to verify, if group-owner has changed from ``dialout`` to ``plugdev``:

Expand All @@ -93,13 +94,13 @@ Linux

The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.

Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.


MacOS
"""""

On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel used for JTAG, OpenOCD will not be able to connect to to the chip. There are two ways around this:
On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel used for JTAG, OpenOCD will not be able to connect to the chip. There are two ways around this:

1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.

Expand Down Expand Up @@ -195,4 +196,3 @@ In a nutshell, this approach requires modification to FTDI driver configuration
After these steps, serial port and JTAG can be used at the same time.

To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.

Loading

0 comments on commit 79ca95d

Please sign in to comment.