alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-09-20 00:36:01 -04:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'bugfix/doc_jtag_c3' into 'master'

Browse Source 
docs: Update JTAG debugging guides for ESP32-C3

Closes IDF-2133

See merge request espressif/esp-idf!13102
This commit is contained in:
Krzysztof Budzynski 2021-04-22 11:58:34 +00:00
commit 58424ccebf
7 changed files with 118 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/_static/jtag-debugging-overview.jpg vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 50 KiB

After

Width:  |  Height:  |  Size: 96 KiB

10
docs/conf_common.py
View File

@ -166,6 +166,10 @@ USB_DOCS = ['api-reference/peripherals/usb.rst',
'api-guides/usb-console.rst',
'api-guides/dfu.rst']
FTDI_JTAG_DOCS = ['api-guides/jtag-debugging/configure-ft2232h-jtag.rst']
BUILTIN_JTAG_DOCS = ['api-guides/jtag-debugging/configure-builtin-jtag.rst']
ULP_DOCS = ['api-guides/ulp.rst', 'api-guides/ulp_macros.rst']
RISCV_COPROC_DOCS = ['api-guides/ulp-risc-v.rst',]
@ -183,7 +187,7 @@ ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
'security/secure-boot-v1.rst',
'api-reference/peripherals/secure_element.rst',
'api-reference/peripherals/dac.rst',
'hw-reference/esp32/**'] + LEGACY_DOCS
'hw-reference/esp32/**'] + LEGACY_DOCS + FTDI_JTAG_DOCS
ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-guides/ulps2_instruction_set.rst',
@ -194,9 +198,9 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
'api-reference/peripherals/temp_sensor.rst',
'api-reference/system/async_memcpy.rst',
'api-reference/peripherals/touch_element.rst',
'api-reference/peripherals/dac.rst']
'api-reference/peripherals/dac.rst'] + FTDI_JTAG_DOCS
ESP32C3_DOCS = ['hw-reference/esp32c3/**']
ESP32C3_DOCS = ['hw-reference/esp32c3/**'] + BUILTIN_JTAG_DOCS
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,

36
docs/en/api-guides/jtag-debugging/configure-builtin-jtag.rst Normal file
View File

@ -0,0 +1,36 @@
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-defs
:end-before: ---
Configure {IDF_TARGET_NAME} built-in JTAG Interface
===================================================
{IDF_TARGET_NAME} has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable
connected to the D+/D- pins is necessary. The necessary connections are shown in the following section.
Configure Hardware
^^^^^^^^^^^^^^^^^^
.. list-table:: ESP32-C3 pins and USB signals
:widths: 25 75
:header-rows: 1
* - ESP32-C3 Pin
- USB Signal
* - GPIO18
- D-
* - GPIO19
- D+
* - 5V
- V_BUS
* - GND
- Ground
Please verify that the {IDF_TARGET_NAME} pins used for USB communication are not connected to some other HW that may disturb the JTAG operation.
Configure USB Drivers
^^^^^^^^^^^^^^^^^^^^^
JTAG communication should work out-of-box on Linux and macOS. Windows users might get `LIBUSB_ERROR_NOT_FOUND` errors.
This is a known issue and will be addressed soon.

81
docs/en/api-guides/jtag-debugging/esp32c3.inc
View File

@ -7,14 +7,13 @@
.. These code blocks can be moved back to the main .rst files, with target-specific
.. file names being replaced by substitutions.
.. run-openocd
::
openocd -f board/Xcfg
openocd -f board/esp32c3-builtin.cfg
.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 board
.. |run-openocd-device-name| replace:: ESP32-C3 through built-in USB connection
---
@ -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,24 +77,26 @@
::
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:: OpenOCD configuration files for ESP32-S2
.. list-table:: OpenOCD configuration files for ESP32-C3
:widths: 25 75
:header-rows: 1
* - Name
- Description
* - ``board/esp32s2-kaluga-1.cfg``
- Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
* - ``target/esp32s2.cfg``
- ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
* - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
- JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
* - ``board/esp32c3-builtin.cfg``
- Board configuration file for ESP32-C3 through built-in USB, includes target and adapter configuration.
* - ``board/esp32c3-ftdi.cfg``
- Board configuration file for ESP32-C3 debug through an ESP-Prog compatible FTDI, includes target and adapter configuration.
* - ``target/esp32c3.cfg``
- ESP32-C3 target configuration file. Can be used together with one of the ``interface/`` configuration files.
* - ``interface/esp_usb_jtag.cfg``
- JTAG adapter configuration file for ESP32-C3.
* - ``interface/ftdi/esp32_devkitj_v1.cfg``
- JTAG adapter configuration file for ESP-Prog boards.
@ -105,19 +110,19 @@
.. jtag-pins
.. list-table:: ESP32-S2 pins and JTAG signals
.. list-table:: ESP32-C3 pins and JTAG signals
:widths: 25 75
:header-rows: 1
* - ESP32-S2 Pin
* - ESP32-C3 Pin
- JTAG Signal
* - MTDO / GPIO40
* - MTDO / GPIO7
- TDO
* - MTDI / GPIO41
* - MTDI / GPIO5
- TDI
* - MTCK / GPIO39
* - MTCK / GPIO6
- TCK
* - MTMS / GPIO42
* - MTMS / GPIO4
- TMS
---
@ -126,7 +131,7 @@
::
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 +139,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 +147,19 @@
::
xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
---
.. devkit-defs
.. |devkit-name| replace:: ESP-S2-Kaluga-1
.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>`
.. |devkit-name| replace:: ESP32-C3
.. |devkit-name-with-link| replace:: :doc:`ESP32-C3 <../../hw-reference/modules-and-boards>`
---
.. devkit-hw-config
* Out of the box, ESP32-S2-Kaluga-1 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position.
* Out of the box, ESP32-C3 doesn't need any additional hardware configuration for JTAG debugging.
---

30
docs/en/api-guides/jtag-debugging/index.rst
View File

@ -66,7 +66,17 @@ Under "Application Loading and Monitoring" there is another software and hardwar
Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
.. only:: not esp32c3
If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
.. only:: esp32c3
The connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the {IDF_TARGET_NAME} chip itself, which provides two USB channels, one for JTAG and one for the USB terminal connection. The USB cable should be connected the D+/D- USB pins of {IDF_TARGET_NAME} and not to the serial RxD/TxD throught an USB-to-UART chip. The proper connection is explained later in subsection :ref:`jtag-debugging-configuring-target`.
.. note::
Debugging through the USB interface implemented in {IDF_TARGET_NAME} requires to have a chip with revision 3 or newer. Please use other debugging options (e.g. with ESP-Prog) for chip revision 1 and 2. The easiest way to determine the chip revision is to look for the `Chip is ESP32-C3 (revision 3)` message near the end of a successful chip flashing done by `idf.py flash`.
Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
@ -76,7 +86,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
Selecting JTAG Adapter
----------------------
The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
.. only:: not esp32c3
The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already built in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
.. only:: esp32c3
The quickest and most convenient way to start with JTAG debugging is through an USB cable connected to the D+/D- USB pins of {IDF_TARGET_NAME}. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}.
If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
@ -84,6 +100,7 @@ On the software side, OpenOCD supports a fair amount of JTAG adapters. See http:
The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal.
`ESP-Prog <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`_ is an example for using an external board for debugging by connecting it to the JTAG pins of {IDF_TARGET_NAME}.
.. _jtag-debugging-setup-openocd:
@ -133,7 +150,9 @@ This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the tw
.. toctree::
:maxdepth: 1
configure-ft2232h-jtag
:esp32: configure-ft2232h-jtag
:esp32s2: configure-ft2232h-jtag
:esp32c3: configure-builtin-jtag
configure-other-jtag
@ -156,6 +175,11 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
.. only:: esp32c3
For example, ``board/esp32c3-ftdi.cfg`` can be used for a custom board with an FT2232H or FT232H chip used for JTAG connection,
or with ESP-Prog.
.. highlight:: none
You should now see similar output (this log is for |run-openocd-device-name|):

1
docs/zh_CN/api-guides/jtag-debugging/configure-builtin-jtag.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../../en/api-guides/jtag-debugging/configure-builtin-jtag.rst

6
docs/zh_CN/api-guides/jtag-debugging/index.rst
View File

@ -133,7 +133,9 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
.. toctree::
:maxdepth: 1
configure-ft2232h-jtag
:esp32: configure-ft2232h-jtag
:esp32s2: configure-ft2232h-jtag
:esp32c3: configure-builtin-jtag
configure-other-jtag
@ -302,4 +304,4 @@ Windows 用户:
- :doc:`debugging-examples`
- :doc:`tips-and-quirks`
- :doc:`../app_trace`
- `ESP-Prog 调试板介绍 <https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`__
- `ESP-Prog 调试板介绍 <https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`__