From 139d5d130b65529f5e9d33c3297228d6521caa9d Mon Sep 17 00:00:00 2001 From: Erhan Kurubas Date: Mon, 10 Nov 2025 13:12:43 +0100 Subject: [PATCH] docs(jtag): document program_esp_bins command --- docs/en/api-guides/jtag-debugging/index.rst | 32 +++++++++++++++++-- .../zh_CN/api-guides/jtag-debugging/index.rst | 31 +++++++++++++++++- 2 files changed, 60 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 2b0439fc6c..b2a858e761 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -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 [verify] [reset] [exit] [compress] [encrypt]`` +``program_esp [verify] [reset] [exit] [compress] [encrypt] [no_clock_boost] [restore_clock] [skip_loaded]`` - ``image_file`` - Path to program image file. - ``offset`` - Offset in flash bank to write image. @@ -232,10 +232,38 @@ OpenOCD flashing command ``program_esp`` has the following format: - ``encrypt`` - Optional. Encrypt binary before writing to flash. Same functionality with ``idf.py encrypted-flash`` - ``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. + - ``skip_loaded`` - Optional. Skip flashing if the binary is already loaded. Disabled by default. + +Alternative Method: Using program_esp_bins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For convenience when working with ESP-IDF projects, OpenOCD provides an alternative command ``program_esp_bins`` that can flash multiple binaries in a single command by reading the build configuration from the ``flasher_args.json`` file generated during the ESP-IDF build process. + +This method is particularly useful because: + +* It automatically reads all the binary files and their flash addresses from the build output +* It handles encrypted partitions automatically based on the project configuration +* It eliminates the need to manually specify addresses for each binary (bootloader, partition table, application, etc.) + +Basic usage: + +.. code-block:: bash + + openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp_bins build flasher_args.json verify exit" + +Command Format +"""""""""""""" + +The OpenOCD flashing command ``program_esp_bins`` has the following format: + +``program_esp_bins [verify] [reset] [exit] [compress] [no_clock_boost] [restore_clock] [skip_loaded]`` + + - ``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``). + - Other optional parameters work the same as ``program_esp`` command. See :ref:`jtag-upload-app-debug` section for details. You are now ready to start application debugging. Follow the steps described in the section below. - .. _jtag-debugging-launching-debugger: Launching Debugger diff --git a/docs/zh_CN/api-guides/jtag-debugging/index.rst b/docs/zh_CN/api-guides/jtag-debugging/index.rst index ef9511d28b..8d9e8d8e4b 100644 --- a/docs/zh_CN/api-guides/jtag-debugging/index.rst +++ b/docs/zh_CN/api-guides/jtag-debugging/index.rst @@ -221,7 +221,7 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG 其中 OpenOCD 的烧写命令 ``program_esp`` 格式如下： -``program_esp [verify] [reset] [exit] [compress] [encrypt]`` +``program_esp [verify] [reset] [exit] [compress] [encrypt] [no_clock_boost] [restore_clock] [skip_loaded]`` - ``image_file`` - 程序镜像文件存放的路径 - ``offset`` - 镜像烧写到 flash 中的偏移地址 @@ -232,6 +232,35 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG - ``encrypt`` - 烧写到 flash 前加密二进制文件，与 ``idf.py encrypted-flash`` 功能相同（可选） - ``no_clock_boost`` - 禁用在烧写前将目标时钟频率设置为其最大可能值（可选）。默认情况下禁用该选项，即默认启用时钟提升。 - ``restore_clock`` - 可选。烧写完成后将时钟频率恢复到初始值。默认情况下不启用。 +- ``skip_loaded`` - 可选。如果二进制文件已加载，则跳过烧写。默认情况下不启用。 + +替代方法：使用 program_esp_bins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +为方便 ESP-IDF 项目的使用，OpenOCD 提供了一个替代命令 ``program_esp_bins``，该命令可以通过读取 ESP-IDF 构建过程中生成的 ``flasher_args.json`` 文件中的构建配置，在单个命令中烧写多个二进制文件。 + +该方法特别有用，因为： + +* 它会自动从构建输出中读取所有二进制文件及其 flash 地址 +* 它会根据项目配置自动处理加密分区 +* 它无需手动指定每个二进制文件（引导加载程序、分区表、应用程序等）的地址 + +基本用法： + +.. code-block:: bash + + openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp_bins build flasher_args.json verify exit" + +命令格式 +"""""""""""""" + +OpenOCD 烧写命令 ``program_esp_bins`` 格式如下： + +``program_esp_bins [verify] [reset] [exit] [compress] [no_clock_boost] [restore_clock] [skip_loaded]`` + + - ``build_dir`` - 包含 ``flasher_args.json`` 文件的构建目录路径。 + - ``json_file`` - 包含 flash 配置的 JSON 文件名称（通常为 ``flasher_args.json``）。 + - 其他可选参数与 ``program_esp`` 命令相同。详情请参阅 :ref:`jtag-upload-app-debug` 章节。 现在可以调试应用程序了，请按照以下章节中的步骤进行操作。