docs(jtag-debugging): update OpenOCD flashing documentation

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 <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``).

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

@@ -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`.