mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
Merge branch 'feature/update-openocd-to-v0.12.0-esp32-20260424' into 'master'
feat(tools): update openocd version to v0.12.0-esp32-20260424 Closes OCD-892, OCD-1371, and DOC-14459 See merge request espressif/esp-idf!48003
This commit is contained in:
Erhan Kurubas
@@ -3,7 +3,7 @@ Configure Other JTAG Interfaces
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE"}
|
||||
{IDF_TARGET_JTAG_SEL_EFUSE:default="Not Updated!", esp32s3="STRAP_JTAG_SEL", esp32c6="JTAG_SEL_ENABLE", esp32h2="JTAG_SEL_ENABLE", esp32p4="JTAG_SEL_ENABLE", esp32c5="JTAG_SEL_ENABLE", esp32c61="JTAG_SEL_ENABLE", esp32h4="JTAG_SEL_ENABLE", esp32h21="JTAG_SEL_ENABLE", esp32s31="JTAG_SEL_ENABLE"}
|
||||
|
||||
For guidance about which JTAG interface to select when using OpenOCD with {IDF_TARGET_NAME}, refer to the section :ref:`jtag-debugging-selecting-jtag-adapter`. Then follow the configuration steps below to get it working.
|
||||
|
||||
|
||||
@@ -99,7 +99,7 @@
|
||||
- Board configuration file for ESP32-S3 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
|
||||
* - ``target/esp32s3.cfg``
|
||||
- ESP32-S3 target configuration file. Can be used together with one of the ``interface/`` configuration files.
|
||||
* - ``interface/ftdi/esp_usb_jtag.cfg``
|
||||
* - ``interface/esp_usb_jtag.cfg``
|
||||
- JTAG adapter configuration file for ESP32-S3 builtin USB JTAG.
|
||||
* - ``interface/ftdi/esp_ftdi.cfg``
|
||||
- JTAG adapter configuration file for ESP-Prog debug adapter board.
|
||||
|
||||
@@ -23,24 +23,32 @@
|
||||
::
|
||||
|
||||
user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s31-builtin.cfg
|
||||
Open On-Chip Debugger v0.10.0-esp32-20210902 (2021-10-05-23:44)
|
||||
Open On-Chip Debugger v0.12.0-esp32-20260424 (2026-04-24-15:13)
|
||||
Licensed under GNU GPL v2
|
||||
For bug reports, read
|
||||
https://openocd.org/doc/doxygen/bugs.html
|
||||
debug_level: 2
|
||||
|
||||
Info : only one transport option; autoselect 'jtag'
|
||||
Warn : Transport "jtag" was already selected
|
||||
http://openocd.org/doc/doxygen/bugs.html
|
||||
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
|
||||
Info : esp_usb_jtag: capabilities descriptor set to 0x2000
|
||||
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: esp32s31.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
Info : JTAG tap: esp32s31.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
|
||||
Info : esp32s31.cpu0: Debug controller was reset.
|
||||
Info : esp32s31.cpu0: Core was reset.
|
||||
Info : esp32s31.cpu1: Debug controller was reset.
|
||||
Info : esp32s31.cpu1: Core was reset.
|
||||
Info : esp_usb_jtag: serial (30:ED:A0:ED:77:E4)
|
||||
Info : esp_usb_jtag: Device found. Base speed 24000KHz, div range 1 to 255
|
||||
Info : clock speed 24000 kHz
|
||||
Info : JTAG tap: esp32s31.tap0 tap/device found: 0x00003c25 (mfg: 0x612 (Espressif Systems), part: 0x0003, ver: 0x0)
|
||||
Info : JTAG tap: esp32s31.tap1 tap/device found: 0x00020c25 (mfg: 0x612 (Espressif Systems), part: 0x0020, ver: 0x0)
|
||||
Info : [esp32s31.hp.cpu0] datacount=1 progbufsize=2
|
||||
Info : [esp32s31.hp.cpu0] Core 0 made part of halt group 1.
|
||||
Info : [esp32s31.hp.cpu0] Examined RISC-V core
|
||||
Info : [esp32s31.hp.cpu0] XLEN=32, misa=0x40943127
|
||||
Info : [esp32s31.hp.cpu0] Chip revision v0.0
|
||||
Info : [esp32s31.hp.cpu0] Examination succeed
|
||||
Info : [esp32s31.hp.cpu1] datacount=1 progbufsize=2
|
||||
Info : [esp32s31.hp.cpu1] Core 1 made part of halt group 1.
|
||||
Info : [esp32s31.hp.cpu1] Examined RISC-V core
|
||||
Info : [esp32s31.hp.cpu1] XLEN=32, misa=0x40943127
|
||||
Info : [esp32s31.hp.cpu1] Chip revision v0.0
|
||||
Info : [esp32s31.hp.cpu1] Examination succeed
|
||||
Info : [esp32s31.hp.cpu0] starting gdb server on 3333
|
||||
Info : Listening on port 3333 for gdb connections
|
||||
|
||||
.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s31-builtin.cfg``
|
||||
@@ -99,7 +107,7 @@
|
||||
- Board configuration file for ESP32-S31 for via externally connected FTDI-based probe like ESP-Prog, includes target and adapter configuration.
|
||||
* - ``target/esp32s31.cfg``
|
||||
- ESP32-S31 target configuration file. Can be used together with one of the ``interface/`` configuration files.
|
||||
* - ``interface/ftdi/esp_usb_jtag.cfg``
|
||||
* - ``interface/esp_usb_jtag.cfg``
|
||||
- JTAG adapter configuration file for ESP32-S31 builtin USB JTAG.
|
||||
* - ``interface/ftdi/esp_ftdi.cfg``
|
||||
- JTAG adapter configuration file for ESP-Prog debug adapter board.
|
||||
@@ -120,17 +128,17 @@
|
||||
|
||||
* - ESP32-S31 Pin
|
||||
- JTAG Signal
|
||||
* - MTDO / GPIO40
|
||||
* - MTDO / GPIO54
|
||||
- TDO
|
||||
* - MTDI / GPIO41
|
||||
* - MTDI / GPIO56
|
||||
- TDI
|
||||
* - MTCK / GPIO39
|
||||
* - MTCK / GPIO55
|
||||
- TCK
|
||||
* - MTMS / GPIO42
|
||||
* - MTMS / GPIO57
|
||||
- TMS
|
||||
|
||||
.. |jtag-sel-gpio| replace:: GPIO3
|
||||
.. |jtag-gpio-list| replace:: GPIO39-GPIO42
|
||||
.. |jtag-sel-gpio| replace:: GPIO37
|
||||
.. |jtag-gpio-list| replace:: GPIO54-GPIO57
|
||||
|
||||
---
|
||||
|
||||
@@ -154,7 +162,7 @@
|
||||
|
||||
::
|
||||
|
||||
xtensa-esp32s31-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
|
||||
riscv32-esp-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
|
||||
|
||||
---
|
||||
|
||||
@@ -167,6 +175,6 @@
|
||||
|
||||
.. devkit-hw-config
|
||||
|
||||
* Out of the box, ESP32-S31 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-S31 doesn't need any additional hardware configuration for JTAG debugging.
|
||||
|
||||
---
|
||||
|
||||
@@ -184,7 +184,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
|
||||
:start-after: run-openocd
|
||||
:end-before: ---
|
||||
|
||||
{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg"}
|
||||
{IDF_TARGET_FTDI_CONFIG:default="Not Updated!", esp32s3="board/esp32s3-ftdi.cfg", esp32c3="board/esp32c3-ftdi.cfg", esp32c6="board/esp32c6-ftdi.cfg", esp32h2="board/esp32h2-ftdi.cfg", esp32h21="board/esp32h21-ftdi.cfg", esp32h4="board/esp32h4-ftdi.cfg", esp32p4="board/esp32p4-ftdi.cfg", esp32c5="board/esp32c5-ftdi.cfg", esp32c61="board/esp32c61-ftdi.cfg", esp32s31="board/esp32s31-ftdi.cfg}
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -221,7 +221,7 @@ Another option is to write application image to flash using OpenOCD via JTAG wit
|
||||
|
||||
OpenOCD flashing command ``program_esp`` has the following format:
|
||||
|
||||
``program_esp <image_file> <offset> [verify] [reset] [exit] [compress] [encrypt] [no_clock_boost] [restore_clock] [no_skip_loaded]``
|
||||
``program_esp <image_file> <offset> [verify] [reset] [exit] [compress] [encrypt] [no_clock_boost] [restore_clock] [no_skip_loaded] [force]``
|
||||
|
||||
- ``image_file`` - Path to program image file.
|
||||
- ``offset`` - Offset in flash bank to write image.
|
||||
@@ -233,6 +233,7 @@ OpenOCD flashing command ``program_esp`` has the following format:
|
||||
- ``no_clock_boost`` - Optional. Disable setting target clock frequency to its maximum possible value before programming. Clock boost is enabled by default.
|
||||
- ``restore_clock`` - Optional. Restore clock frequency to its initial value after programming. Disabled by default.
|
||||
- ``no_skip_loaded`` - Optional. Do not check whether the binary is already loaded before flashing. Disabled by default.
|
||||
- ``force`` - Optional. Disable checks for target compatibility with the chip type and revision range detected from the image file. Checks are enabled by default.
|
||||
|
||||
Alternative Method: Using ``program_esp_bins``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -256,7 +257,7 @@ Command Format
|
||||
|
||||
The OpenOCD flashing command ``program_esp_bins`` has the following format:
|
||||
|
||||
``program_esp_bins <build_dir> <json_file> [verify] [reset] [exit] [compress] [no_clock_boost] [restore_clock] [no_skip_loaded]``
|
||||
``program_esp_bins <build_dir> <json_file> [verify] [reset] [exit] [compress] [no_clock_boost] [restore_clock] [no_skip_loaded] [force]``
|
||||
|
||||
- ``build_dir`` - Path to the build directory containing the ``flasher_args.json`` file.
|
||||
- ``json_file`` - Name of the JSON file containing flash configuration (typically ``flasher_args.json``).
|
||||
|
||||
@@ -129,7 +129,7 @@ What Is the Meaning of Debugger's Startup Commands?
|
||||
On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient/appropriate line and start debugging.
|
||||
|
||||
* ``set remote hardware-watchpoint-limit {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM}`` — Restrict GDB to using available hardware watchpoints supported by the chip, {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
|
||||
* ``mon reset halt`` — reset the chip and keep the CPUs halted
|
||||
* ``mon reset halt`` — reset the chip and keep the CPUs halted. Target has to be reset to disable memory protection, which is required to enable flash support. If reset is not desirable, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line to disable flash support, see :ref:`jtag-debugging-tip-openocd-config-vars`. Alternatively, disable memory protection using the config option :ref:`CONFIG_ESP_SYSTEM_MEMPROT`.
|
||||
* ``maintenance flush register-cache`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``maintenance flush register-cache`` is a way to force GDB to get new state from the target.
|
||||
* ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required
|
||||
* ``c`` — resume the program. It will then stop at breakpoint inserted at ``app_main``.
|
||||
@@ -192,7 +192,7 @@ It is important to set the variable before including the ESP-specific configurat
|
||||
* - ``ESP_RTOS``
|
||||
- Set to ``none`` to disable RTOS support. In this case, thread list will not be available in GDB. Can be useful when debugging FreeRTOS itself, and stepping through the scheduler code.
|
||||
* - ``ESP_FLASH_SIZE``
|
||||
- Set to ``0`` to disable Flash breakpoints support.
|
||||
- Set to ``0`` to disable flash breakpoints support. If set to ``0``, target will not be reset when GDB connects.
|
||||
* - ``ESP_SEMIHOST_BASEDIR``
|
||||
- Set to the path (on the host) which will be the default directory for semihosting functions.
|
||||
* - ``ESP_ONLYCPU``
|
||||
@@ -257,10 +257,7 @@ By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debug
|
||||
|
||||
The project configuration option :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled).
|
||||
|
||||
However, OpenOCD may attempt to automatically read and write the flash in order to set :ref:`software breakpoints <jtag-debugging-tip-where-breakpoints>`. This has two problems:
|
||||
|
||||
- Software breakpoints are incompatible with Flash Encryption, OpenOCD currently has no support for encrypting or decrypting flash contents.
|
||||
- If Secure Boot is enabled, setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if a software breakpoint is set and then a reset occurs, the signature verification will fail on boot.
|
||||
However, OpenOCD may attempt to automatically read and write the flash in order to set :ref:`software breakpoints <jtag-debugging-tip-where-breakpoints>`. Setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if Secure Boot is enabled, a software breakpoint is set, and then a reset occurs, the signature verification will fail on boot.
|
||||
|
||||
To disable software breakpoints while using JTAG, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line, see :ref:`jtag-debugging-tip-openocd-config-vars`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user