mirror of
https://github.com/espressif/esp-idf.git
synced 2026-06-04 20:26:38 +03:00
docs(jtag-debugging): update OpenOCD flashing documentation
This commit is contained in:
Samuel Obuch
@@ -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`.
|
||||
|
||||
|
||||
@@ -221,7 +221,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
|
||||
|
||||
其中 OpenOCD 的烧写命令 ``program_esp`` 格式如下：
|
||||
|
||||
``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`` - 程序镜像文件存放的路径
|
||||
- ``offset`` - 镜像烧写到 flash 中的偏移地址
|
||||
@@ -233,6 +233,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
|
||||
- ``no_clock_boost`` - 禁用在烧写前将目标时钟频率设置为其最大可能值（可选）。默认情况下禁用该选项，即默认启用时钟提升。
|
||||
- ``restore_clock`` - 可选。烧写完成后将时钟频率恢复到初始值。默认情况下不启用。
|
||||
- ``no_skip_loaded`` - 可选。烧写前不检查该二进制文件是否已被加载，默认情况下不启用。
|
||||
- ``force`` - 可选。禁用从镜像文件中检测到的芯片类型和版本范围的目标兼容性检查。此检查默认启用。
|
||||
|
||||
替代方法：使用 ``program_esp_bins``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -256,7 +257,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
|
||||
|
||||
OpenOCD 烧录命令 ``program_esp_bins`` 格式如下：
|
||||
|
||||
``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`` - 包含 ``flasher_args.json`` 文件的构建目录路径。
|
||||
- ``json_file`` - 包含 flash 配置的 JSON 文件名称（通常为 ``flasher_args.json``）。
|
||||
|
||||
@@ -129,7 +129,7 @@ GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情
|
||||
在启动时，调试器发出一系列命令来复位芯片并使其在特定的代码行停止运行。这个命令序列（如下所示）支持自定义，用户可以选择在最方便合适的代码行开始调试工作。
|
||||
|
||||
* ``set remote hardware-watchpoint-limit {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM}`` — 限制 GDB 使用芯片支持的硬件观察点数量，{IDF_TARGET_NAME} 支持 {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} 个观察点。更多详细信息，请查阅 `GDB 配置远程目标 <https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html>`_ 。
|
||||
* ``mon reset halt`` — 复位芯片并使 CPU 停止运行。
|
||||
* ``mon reset halt`` — 复位芯片并使 CPU 停止运行。目标必须先复位以禁用内存保护，这对于启用 FLASH 支持是必要的。如果不希望复位，可在 OpenOCD 命令行中添加额外参数 ``-c 'set ESP_FLASH_SIZE 0'`` 来禁用 FLASH 支持，详见 :ref:`jtag-debugging-tip-openocd-config-vars`。或者，可以通过配置选项 :ref:`CONFIG_ESP_SYSTEM_MEMPROT` 关闭内存保护。
|
||||
* ``maintenance flush register-cache`` — monitor (``mon``) 命令无法通知 GDB 目标状态已经更改，GDB 会假设在 ``mon reset halt`` 之前所有的任务堆栈仍然有效。实际上，复位后目标状态将发生变化。执行 ``maintenance flush register-cache`` 是一种强制 GDB 从目标获取最新状态的方法。
|
||||
* ``thb app_main`` — 在 ``app_main`` 处插入一个临时的硬件断点，如果有需要，可以将其替换为其他函数名。
|
||||
* ``c`` — 恢复程序运行，它将会在 ``app_main`` 的断点处停止运行。
|
||||
@@ -192,7 +192,7 @@ TCL 语言中为变量赋值的语法是:
|
||||
* - ``ESP_RTOS``
|
||||
- 设置成 ``none`` 可以关闭 OpenOCD 对 RTOS 的支持，这样的话，你将无法在 GDB 中查看到线程列表。这个功能在调试 FreeRTOS 本身的时候会很有用，可以单步调试调度器的代码。
|
||||
* - ``ESP_FLASH_SIZE``
|
||||
- 设置成 ``0`` 可以关闭对 flash 断点的支持。
|
||||
- 设置成 ``0`` 可以关闭对 flash 断点的支持。如果设置为 ``0``，GDB 连接时不会复位目标。
|
||||
* - ``ESP_SEMIHOST_BASEDIR``
|
||||
- 设置 semihosting 在主机端的默认目录。
|
||||
* - ``ESP_ONLYCPU``
|
||||
@@ -257,10 +257,7 @@ JTAG 与 flash 加密和安全引导
|
||||
|
||||
Kconfig 配置项 :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` 可以改变这个默认行为，使得用户即使开启了安全引导或者 flash 加密，仍会保留 JTAG 的功能。
|
||||
|
||||
然而，因为设置 :ref:`软件断点 <jtag-debugging-tip-where-breakpoints>` 的需要，OpenOCD 会尝试自动读写 flash 中的内容，这会带来两个问题：
|
||||
|
||||
- 软件断点和 flash 加密是不兼容的，目前 OpenOCD 尚不支持对 flash 中的内容进行加密和解密。
|
||||
- 如果开启了安全引导功能，设置软件断点会改变被签名的程序的摘要，从而使得签名失效。这也意味着，如果设置了软件断点，系统会在下次重启时的签名验证阶段失败，导致无法启动。
|
||||
然而，为了设置 :ref:`软件断点 <jtag-debugging-tip-where-breakpoints>`，OpenOCD 可能会尝试自动读写 flash。设置软件断点会改变被签名程序的摘要并使签名失效。这意味着如果启用了安全引导、设置了软件断点，然后进行复位，签名验证将在启动时失败。
|
||||
|
||||
关闭 JTAG 的软件断点功能，可以在启动 OpenOCD 时在命令行额外加一项配置参数 ``-c 'set ESP_FLASH_SIZE 0'``，请参考 :ref:`jtag-debugging-tip-openocd-config-vars`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user