Merge branch 'change/disable_stub_bins_v5.4' into 'release/v5.4'

change(esp_system): do not include openocd stub bins by default (v5.4)

See merge request espressif/esp-idf!34871

Author: mahavirj

components/esp_system/Kconfig

@@ -537,7 +537,7 @@ menu "ESP System Settings"
 
     config ESP_DEBUG_INCLUDE_OCD_STUB_BINS
         bool "Preload OpenOCD stub binaries to speed up debugging. 8K memory will be reserved"
-        default y
+        default n
         depends on SOC_DEBUG_HAVE_OCD_STUB_BINS
         help
             OpenOCD uses stub code to access flash during programming or when inserting and removing

docs/en/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -103,8 +103,20 @@ In order to achieve higher data rates and minimize number of dropped packets it
 3.  In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read from a memory range without physical memory being present there).
 4.  ESP-WROVER-KIT operates stable at 20 MHz or 26 MHz.
 
+.. only:: SOC_DEBUG_HAVE_OCD_STUB_BINS
 
-.. _jtag-debugging-tip-debugger-startup-commands:
+    .. _jtag-debugging-tip-improve-debugging-speed:
+
+    Improve Debugging Speed
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    Enabling :ref:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` allocates 8 KB of RAM and embeds pre-built stub binaries into RAM. This improves the overall debugging speed by eliminating the need to load the stub binaries at runtime. It is particularly beneficial when using flash breakpoints, as it reduces the latency of add/remove breakpoints. However, keep in mind that the increased RAM usage may reduce memory availability for other tasks.
+
+    .. _jtag-debugging-tip-debugger-startup-commands:
+
+.. only:: not SOC_DEBUG_HAVE_OCD_STUB_BINS
+
+    .. _jtag-debugging-tip-debugger-startup-commands:
 
 What Is the Meaning of Debugger's Startup Commands?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/en/api-guides/performance/ram-usage.rst

@@ -192,7 +192,6 @@ The following options will reduce IRAM usage of some ESP-IDF features:
     - Refer to the sdkconfig menu ``Auto-detect Flash chips``, and you can disable flash drivers which you do not need to save some IRAM.
     :SOC_GPSPI_SUPPORTED: - Enable :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`. Provided that :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` is not enabled and the heap functions are not incorrectly used from ISRs, this option is safe to enable in all configurations.
     :esp32c2: - Enable :ref:`CONFIG_BT_RELEASE_IRAM`. Release BT text section and merge BT data, bss & text into a large free heap region when ``esp_bt_mem_release`` is called. This makes Bluetooth unavailable until the next restart, but saving ~22 KB or more of IRAM.
-    :SOC_DEBUG_HAVE_OCD_STUB_BINS: - Disabling :ref:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` frees 8 KB IRAM but overall speed of debugging might be impacted due to the added overhead of runtime stub loading especially when using flash breakpoints.
 
 .. only:: esp32
 

docs/zh_CN/api-guides/jtag-debugging/tips-and-quirks.rst

@@ -103,8 +103,20 @@ GDB 具有 FreeRTOS 支持的 Python 扩展模块。在系统要求满足的情
 3.  在某些特殊情况下，如果你看到 DSR/DIR 错误（并且它并不是由 OpenOCD 试图从一个没有物理存储器映射的地址空间读取数据而导致的），请降低 JTAG 的工作频率。
 4.  ESP-WROVER-KIT 能够稳定运行在 20 MHz 或 26 MHz 频率下。
 
+.. only:: SOC_DEBUG_HAVE_OCD_STUB_BINS
 
-.. _jtag-debugging-tip-debugger-startup-commands:
+    .. _jtag-debugging-tip-improve-debugging-speed:
+
+    提高调试速度
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    启用 :ref:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` 将预先分配 8 KB 的 RAM, 且预编译的存根二进制文件将嵌入到 RAM 中，因此运行时将无需加载存根二进制文件，从而提高整体调试速度。在使用 flash 断点时，上述优化可以有效降低添加和删除断点的延迟。但要注意，RAM 使用量的增加可能会占用其他任务所需的内存。
+
+    .. _jtag-debugging-tip-debugger-startup-commands:
+
+.. only:: not SOC_DEBUG_HAVE_OCD_STUB_BINS
+
+    .. _jtag-debugging-tip-debugger-startup-commands:
 
 调试器的启动命令的含义
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/zh_CN/api-guides/performance/ram-usage.rst

@@ -192,7 +192,6 @@ IRAM 优化
     - 要禁用不需要的 flash 驱动程序，节省 IRAM 空间，请参阅 sdkconfig 菜单中的 ``Auto-detect Flash chips`` 选项。
     :SOC_GPSPI_SUPPORTED: - 启用 :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`。只要未启用 :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` 选项，且没有从 ISR 中错误地调用堆函数，就可以在所有配置中安全启用此选项。
     :esp32c2: - 启用 :ref:`CONFIG_BT_RELEASE_IRAM`。 蓝牙所使用的 data，bss 和 text 段已经被分配在连续的RAM区间。当调用 ``esp_bt_mem_release`` 时，这些段都会被添加到 Heap 中。 这将节省约 22 KB 的 RAM。但要再次使用蓝牙功能，需要重启程序。
-    :SOC_DEBUG_HAVE_OCD_STUB_BINS: - 禁用 :ref:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` 选项可以释放 8 KB 的 IRAM, 但由于运行时加载存根的额外开销，特别是在使用 flash 断点时，可能会影响调试的整体速度。
 
 .. only:: esp32