docs: move target-specific parts of JTAG guide into include files

{esp32,esp32s2}.inc files contain most of the bits and code snippets
which are different between targets. These bits are included from the
rest of the source files.

Also included is an update to the section about OpenOCD configuration
variables and files. This section wasn't updated when some of the
files and variables got renamed.

docs/en/api-guides/jtag-debugging/configure-other-jtag.rst

@@ -10,41 +10,9 @@ Configure Hardware
 
 1.  Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
 
-.. only:: esp32
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-
+        :start-after: jtag-pins
-    +---+-----------------------+-------------+
+        :end-before: ---
-    |   | ESP32 Pin             | JTAG Signal |
-    +===+=======================+=============+
-    | 1 | CHIP_PU               | TRST_N      |
-    +---+-----------------------+-------------+
-    | 2 | MTDO / GPIO15         | TDO         |
-    +---+-----------------------+-------------+
-    | 3 | MTDI / GPIO12         | TDI         |
-    +---+-----------------------+-------------+
-    | 4 | MTCK / GPIO13         | TCK         |
-    +---+-----------------------+-------------+
-    | 5 | MTMS / GPIO14         | TMS         |
-    +---+-----------------------+-------------+
-    | 6 | GND                   | GND         |
-    +---+-----------------------+-------------+
-
-.. only:: esp32s2
-
-    +---+-----------------------+-------------+
-    |   | ESP32-S2 Pin          | JTAG Signal |
-    +===+=======================+=============+
-    | 1 | CHIP_PU               | TRST_N      |
-    +---+-----------------------+-------------+
-    | 2 | MTDO / GPIO40         | TDO         |
-    +---+-----------------------+-------------+
-    | 3 | MTDI / GPIO41         | TDI         |
-    +---+-----------------------+-------------+
-    | 4 | MTCK / GPIO39         | TCK         |
-    +---+-----------------------+-------------+
-    | 5 | MTMS / GPIO42         | TMS         |
-    +---+-----------------------+-------------+
-    | 6 | GND                   | GND         |
-    +---+-----------------------+-------------+
 
 2.  Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.
 

docs/en/api-guides/jtag-debugging/esp32.inc

@@ -0,0 +1,163 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+
+.. run-openocd
+
+::
+
+    openocd -f board/esp32-wrover-kit-3.3v.cfg
+
+.. |run-openocd-device-name| replace:: ESP-WROVER-KIT with ESP32-WROOM-32 module
+
+---
+
+.. run-openocd-output
+
+::
+
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
+    Open On-Chip Debugger  v0.10.0-esp32-20190708 (2019-07-08-11:04)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    none separate
+    adapter speed: 20000 kHz
+    force hard breakpoints
+    Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
+    Info : clock speed 20000 kHz
+    Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
+    Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
+    Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
+    Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
+
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32-wrover-kit-3.3v.cfg``
+
+---
+
+.. run-openocd-upload
+
+::
+
+    openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
+
+---
+
+.. run-openocd-src-linux
+
+.. code-block:: bash
+
+    src/openocd -f board/esp32-wrover-kit-3.3v.cfg
+
+---
+
+.. run-openocd-src-win
+
+.. code-block:: batch
+
+    src\openocd -f board\esp32-wrover-kit-3.3v.cfg
+
+---
+
+.. idf-py-openocd-default-cfg
+
+.. |idf-py-def-cfg| replace:: ``-f board/esp32-wrover-kit-3.3v.cfg``
+
+---
+
+.. run-openocd-appimage-offset
+
+::
+
+    openocd -f board/esp32-wrover-kit-3.3v.cfg -c "init; halt; esp32 appimage_offset 0x210000"
+
+---
+
+.. openocd-cfg-files
+
+.. list-table:: OpenOCD configuration files for ESP32
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Name
+      - Description
+    * - ``board/esp32-wrover-kit-3.3v.cfg``
+      - ESP-WROVER-KIT with a 3.3 V ESP32-WROOM-32 module or ESP32-WROVER-B / ESP32-WROVER-E module.
+    * - ``board/esp32-wrover-kit-1.8v.cfg``
+      - ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
+    * - ``board/esp32-ethernet-kit-3.3v.cfg``
+      - ESP-Ethernet-KIT with a 3.3 V ESP32-WROVER-B / ESP32-WROVER-E module.
+    * - ``target/esp32.cfg``
+      - ESP32 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+    * - ``target/esp32-solo-1.cfg``
+      - Target configuration file for ESP32-SOLO-1 module. Different from ``esp32.cfg`` in that it only configures one CPU.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-WROVER-KIT and ESP-Prog boards.
+
+---
+
+.. openocd-target-specific-config-vars
+
+.. list-table:: ESP32-specific OpenOCD variables
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Name
+      - Description
+    * - ``ESP32_FLASH_VOLTAGE``
+      - When using 1.8 V flash ESP32 based modules, set this variable to ``1.8``. Refer to :ref:`jtag-debugging-tip-code-flash-voltage`.
+    * - ``ESP32_ONLYCPU``
+      - For multi-core targets, can be set to ``1`` to only enable single core debugging.
+
+---
+
+.. jtag-pins
+
+.. list-table:: ESP32 JTAG pins
+    :widths: 25 75
+    :header-rows: 1
+
+    * - ESP32 Pin
+      - JTAG Signal
+    * - MTDO / GPIO15
+      - TDO
+    * - MTDI / GPIO12
+      - TDI
+    * - MTCK / GPIO13
+      - TCK
+    * - MTMS / GPIO14
+      - TMS
+    * - GND
+      - GND
+
+---
+
+.. run-openocd-d3
+
+::
+
+    openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
+
+---
+
+.. run-openocd-d3-tee
+
+::
+
+    openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
+
+---
+
+.. run-gdb-remotelog
+
+::
+
+    xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+
+---

docs/en/api-guides/jtag-debugging/esp32s2.inc

@@ -0,0 +1,147 @@
+.. This file gets included from other .rst files in this folder.
+.. It contains target-specific snippets.
+.. Comments and '---' lines act as delimiters.
+..
+.. This is necessary mainly because RST doesn't support substitutions
+.. (defined in RST, not in Python) inside code blocks. If that is ever implemented,
+.. These code blocks can be moved back to the main .rst files, with target-specific
+.. file names being replaced by substitutions.
+
+
+.. run-openocd
+
+::
+
+    openocd -f board/esp32s2-kaluga-1.cfg
+
+.. |run-openocd-device-name| replace:: ESP32-S2-Kaluga-1 board
+
+---
+
+.. run-openocd-output
+
+::
+
+    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32s2-kaluga-1.cfg
+    Open On-Chip Debugger  v0.10.0-esp32-20200420 (2020-04-20-16:15)
+    Licensed under GNU GPL v2
+    For bug reports, read
+            http://openocd.org/doc/doxygen/bugs.html
+    none separate
+    adapter speed: 20000 kHz
+    force hard breakpoints
+    Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
+    Info : clock speed 20000 kHz
+    Info : JTAG tap: esp32s2.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
+    Info : esp32s2: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
+    Info : esp32s2: Core was reset (pwrstat=0x5F, after clear 0x0F).
+
+.. |run-openocd-cfg-file-err| replace:: ``Can't find board/esp32s2-kaluga-1.cfg``
+
+---
+
+.. run-openocd-upload
+
+::
+
+    openocd -f board/esp32s2-kaluga-1.cfg -c "program_esp filename.bin 0x10000 verify exit"
+
+---
+
+.. run-openocd-src-linux
+
+.. code-block:: bash
+
+    src/openocd -f board/esp32s2-kaluga-1.cfg
+
+---
+
+.. run-openocd-src-win
+
+.. code-block:: batch
+
+    src\openocd -f board/esp32s2-kaluga-1.cfg
+
+---
+
+.. idf-py-openocd-default-cfg
+
+.. |idf-py-def-cfg| replace:: ``-f board/esp32s2-kaluga-1.cfg``
+
+---
+
+.. run-openocd-appimage-offset
+
+::
+
+    openocd -f board/esp32s2-kaluga-1.cfg -c "init; halt; esp32 appimage_offset 0x210000"
+
+---
+
+.. openocd-cfg-files
+
+.. list-table:: OpenOCD configuration files for ESP32
+    :widths: 25 75
+    :header-rows: 1
+
+    * - Name
+      - Description
+    * - ``board/esp32s2-kaluga-1.cfg``
+      - Board configuration file for ESP32-S2-Kaluga-1, includes target and adapter configuration.
+    * - ``target/esp32s2.cfg``
+      - ESP32-S2 target configuration file. Can be used together with one of the ``interface/`` configuration files.
+    * - ``interface/ftdi/esp32s2_kaluga_v1.cfg``
+      - JTAG adapter configuration file for ESP32-S2-Kaluga-1 board.
+    * - ``interface/ftdi/esp32_devkitj_v1.cfg``
+      - JTAG adapter configuration file for ESP-Prog boards.
+
+---
+
+.. openocd-target-specific-config-vars
+
+---
+
+---
+
+.. jtag-pins
+
+.. list-table:: OpenOCD configuration files for ESP32
+    :widths: 25 75
+    :header-rows: 1
+
+    * - ESP32-S2 Pin
+      - JTAG Signal
+    * - MTDO / GPIO40
+      - TDO
+    * - MTDI / GPIO41
+      - TDI
+    * - MTCK / GPIO39
+      - TCK
+    * - MTMS / GPIO42
+      - TMS
+
+---
+
+.. run-openocd-d3
+
+::
+
+    openocd -l openocd_log.txt -d3 -f board/esp32s2-kaluga-1.cfg
+
+---
+
+.. run-openocd-d3-tee
+
+::
+
+    openocd -d3 -f board/esp32s2-kaluga-1.cfg 2>&1 | tee openocd.log
+
+---
+
+.. run-gdb-remotelog
+
+::
+
+    xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+
+---

docs/en/api-guides/jtag-debugging/index.rst

@@ -144,35 +144,26 @@ Once target is configured and connected to computer, you are ready to launch Ope
 
 .. highlight:: bash
 
-Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS)::
+Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS):
 
-    openocd -f board/esp32-wrover-kit-3.3v.cfg
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: run-openocd
+   :end-before: ---
 
 .. note::
 
-    The files provided after ``-f`` above are specific for ESP-WROVER-KIT with esp32-wroom-32 module. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
+    The files provided after ``-f`` above are specific for |run-openocd-device-name|. You may need to provide different files depending on used hardware. For guidance see :ref:`jtag-debugging-tip-openocd-configure-target`.
 
 .. highlight:: none
 
-You should now see similar output (this log is for ESP-WROVER-KIT)::
+You should now see similar output (this log is for ESP-WROVER-KIT):
 
-    user-name@computer-name:~/esp/esp-idf$ openocd -f board/esp32-wrover-kit-3.3v.cfg
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-    Open On-Chip Debugger  v0.10.0-esp32-20190708 (2019-07-08-11:04)
+   :start-after: run-openocd-output
-    Licensed under GNU GPL v2
+   :end-before: ---
-    For bug reports, read
-            http://openocd.org/doc/doxygen/bugs.html
-    none separate
-    adapter speed: 20000 kHz
-    force hard breakpoints
-    Info : ftdi: if you experience problems at higher adapter clocks, try the command "ftdi_tdo_sample_edge falling"
-    Info : clock speed 20000 kHz
-    Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
-    Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
-    Info : esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F).
-    Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F).
 
 * If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory.
-* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path.
+* In case there is an error finding configuration files, e.g. |run-openocd-cfg-file-err|, check ``OPENOCD_SCRIPTS`` environment variable is set correctly. This variable is used by OpenOCD to look for the files specified after ``-f``. See :ref:`jtag-debugging-setup-openocd` section for details. Also check if the file is indeed under provided path.
 * If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on.
 
 
@@ -183,9 +174,11 @@ Upload application for debugging
 
 Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`.
 
-Another option is to write application image to flash using OpenOCD via JTAG with commands like this::
+Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
 
-    openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: run-openocd-upload
+   :end-before: ---
 
 OpenOCD flashing command ``program_esp`` has the following format:
 
@@ -251,26 +244,31 @@ Please refer to separate documents listed below, that describe build process.
 
 The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`.
 
-.. highlight:: bash
+To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS:
 
-To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS::
+.. code-block:: bash
 
     cd ~/esp/openocd-esp32
     export OPENOCD_SCRIPTS=$PWD/tcl
 
-For Windows::
+For Windows:
+
+.. code-block:: batch
 
     cd %USERPROFILE%\esp\openocd-esp32
     set "OPENOCD_SCRIPTS=%CD%\tcl"
 
-Example of invoking OpenOCD build locally from sources, for Linux and macOS::
+Example of invoking OpenOCD build locally from sources, for Linux and macOS:
 
-    src/openocd -f board/esp32-wrover-kit-3.3v.cfg
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: run-openocd-src-linux
+   :end-before: ---
 
-and Windows::
+and Windows:
-
-    src\openocd -f board\esp32-wrover-kit-3.3v.cfg
 
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: run-openocd-src-win
+   :end-before: ---
 
 .. _jtag-debugging-tips-and-quirks:
 

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

@@ -36,7 +36,11 @@ Offset should be in hex format. To reset to the default behaviour you can specif
 
     Since GDB requests memory map from OpenOCD only once when connecting to it, this command should be specified in one of the TCL configuration files, or passed to OpenOCD via its command line. In the latter case command line should look like below:
 
-    ``openocd -f board/esp32-wrover-kit-3.3v.cfg.cfg -c "init; halt; esp32 appimage_offset 0x210000"``
+    .. highlight:: bash
+
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+        :start-after: run-openocd-appimage-offset
+        :end-before: ---
 
     Another option is to execute that command via OpenOCD telnet session and then connect GDB, but it seems to be less handy.
 
@@ -79,9 +83,9 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task
 
     The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping.
 
-    To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
+    To handle this issue OpenOCD's board configuration file (e.g. ``board\esp32-wrover-kit-3.3v.cfg`` for ESP-WROVER-KIT board) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage.
 
-    Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash.
+    Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash. WROVER earlier than ESP32-WROVER-B use 1.8 V flash, while ESP32-WROVER-B and -E modules use 3.3 V flash.
 
 
     .. _jtag-debugging-tip-optimize-jtag-speed:
@@ -120,88 +124,65 @@ On startup, debugger is issuing sequence of commands to reset the chip and halt
 Configuration of OpenOCD for specific target
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-OpenOCD needs to be told what JTAG adapter to use and processor the JTAG adapter is connected to. To do so, use existing **board** configuration files located in OpenOCD's ``share/openocd/scripts/board`` folder.
+There are several kinds of OpenOCD configuration files (``*.cfg``). All configuration files are located in subdirectories of ``share/openocd/scripts`` directory of OpenOCD distribution (or ``tcl/scripts`` directory of the source repository). For the purposes of this guide, the most important ones are ``board``, ``interface`` and ``target``.
 
-For example, if you connect to ESP-WROVER-KIT with ESP-WROOM-32 module installed, use the following configuration files:
+* ``interface`` configuration files describe the JTAG adapter. Examples of JTAG adapters are ESP-Prog and J-Link.
+* ``target`` configuration files describe specific chips, or in some cases, modules.
+* ``board`` configuration files are provided for development boards with a built-in JTAG adapter. Such files include an ``interface`` configuration file to choose the adapter, and ``target`` configuration file to choose the chip/module.
 
-* ``board/esp32-wrover-kit-3.3v.cfg``
+The following configuration files are available for {IDF_TARGET_NAME}:
 
-Optionally prepare configuration by yourself. To do so, you can check existing files and modify them to match you specific hardware. Below is the summary of available configuration parameters for **board** configuration.
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+    :start-after: openocd-cfg-files
+    :end-before: ---
 
 
-.. highlight:: none
+If you are using one of the boards which have a pre-defined configuration file, you only need to pass one ``-f`` argument to OpenOCD, specifying that file.
 
-Adapter's clock speed
+If you are using a board not listed here, you need to specify both the interface configuration file and target configuration file.
-""""""""""""""""""""""
 
-::
+Custom configuration files
+""""""""""""""""""""""""""
 
-    adapter_khz 20000
+OpenOCD configuration files are written in TCL, and include a variety of choices for customization and scripting. This can be useful for non-standard debugging situations. Please refer to `OpenOCD Manual`_ for the TCL scripting reference.
 
-See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value.
+.. _jtag-debugging-tip-openocd-config-vars:
 
-.. only:: esp32
+OpenOCD configuration variables
+"""""""""""""""""""""""""""""""
 
-    Single core debugging
+The following variables can be optionally set before including the ESP-specific target configuration file. This can be done either in a custom configuration file, or from the command line.
-    """""""""""""""""""""
 
-    ::
+The syntax for setting a variable in TCL is:
 
-        set ESP32_ONLYCPU 1
+.. code-block:: tcl
 
-    Comment out this line for dual core debugging.
+    set VARIABLE_NAME value
 
+To set a variable from the command line (replace the name of .cfg file with the correct file for your board):
 
-Disable RTOS support
+.. code-block:: bash
-""""""""""""""""""""
 
-::
+    openocd -c 'set VARIABLE_NAME value' -f board/esp-xxxxx-kit.cfg
 
-    set ESP32_RTOS none
+It is important to set the variable before including the ESP-specific configuration file, otherwise the variable will not have effect. You can set multiple variables by repeating the ``-c`` option.
 
-Comment out this line to have RTOS support.
+.. list-table:: Common ESP-related OpenOCD variables
+    :widths: 25 75
+    :header-rows: 1
 
-.. only:: esp32
+    * - Variable
-
+      - Description
-    Power supply voltage of ESP32's SPI flash chip
+    * - ``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.
-
+    * - ``ESP_SEMIHOST_BASEDIR``
-        set ESP32_FLASH_VOLTAGE 1.8
+      - Set to the path (on the host) which will be the default directory for semihosting functions.
-
-    Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage`
-
-
-    Configuration file for ESP32 targets
-    """"""""""""""""""""""""""""""""""""
-
-    ::
-
-        source [find target/esp32.cfg]
-
-    .. note::
-
-        Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals.
-
-    Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows:
-
-        +---------------+---------------+---------------+
-        | Dual/single   | RTOS          | Target used   |
-        +===============+===============+===============+
-        | dual          | FreeRTOS      | esp32         |
-        +---------------+---------------+---------------+
-        | single        | FreeRTOS      | esp108 (*)    |
-        +---------------+---------------+---------------+
-        | dual          | none          | esp108        |
-        +---------------+---------------+---------------+
-        | single        | none          | esp108        |
-        +---------------+---------------+---------------+
-
-        (*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits.
-
-    Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter.
 
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+    :start-after: openocd-target-specific-config-vars
+    :end-before: ---
 
 .. _jtag-debugging-tip-reset-by-debugger:
 
@@ -218,39 +199,15 @@ Do not use JTAG pins for something else
 
 Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins:
 
-.. only:: esp32
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-
+    :start-after: jtag-pins
-    +---+-----------------------+-------------+
+    :end-before: ---
-    |   | ESP32 Pin             | JTAG Signal |
-    +===+=======================+=============+
-    | 1 | MTDO / GPIO15         | TDO         |
-    +---+-----------------------+-------------+
-    | 2 | MTDI / GPIO12         | TDI         |
-    +---+-----------------------+-------------+
-    | 3 | MTCK / GPIO13         | TCK         |
-    +---+-----------------------+-------------+
-    | 4 | MTMS / GPIO14         | TMS         |
-    +---+-----------------------+-------------+
-
-.. only:: esp32s2
-
-    +---+-----------------------+-------------+
-    |   | ESP32-S2 Pin          | JTAG Signal |
-    +===+=======================+=============+
-    | 1 | MTDO / GPIO40         | TDO         |
-    +---+-----------------------+-------------+
-    | 2 | MTDI / GPIO41         | TDI         |
-    +---+-----------------------+-------------+
-    | 3 | MTCK / GPIO39         | TCK         |
-    +---+-----------------------+-------------+
-    | 4 | MTMS / GPIO42         | TMS         |
-    +---+-----------------------+-------------+
 
 JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
 
 .. highlight:: none
 
-Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured MTDO / GPIO15 to be an input::
+Below is an excerpt from series of errors reported by GDB after the application stepped into the code that reconfigured MTDO pin to be an input::
 
     cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates target still busy!
     cpu0: xtensa_resume (line 431): DSR (FFFFFFFF) indicates DIR instruction generated an exception!
@@ -273,9 +230,7 @@ However, OpenOCD may attempt to automatically read and write the flash in order
 - 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.
 
-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. For example::
+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`.
-
-    openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg
 
 .. note::
 
@@ -312,23 +267,26 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
 
     OpenOCD:
 
-        ::
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-
+        :start-after: run-openocd-d3
-            openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
+        :end-before: ---
 
     Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d3`` is set. If you still like to see the log on the screen, then use another command instead:
 
-        ::
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-
+        :start-after: run-openocd-d3-tee
-            openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
+        :end-before: ---
 
     Debugger:
 
-        ::
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
-
+        :start-after: run-gdb-remotelog
-           xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
+        :end-before: ---
 
     Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
 
 
 4.  Attach both ``openocd_log.txt`` and ``gdb_log.txt`` files to your issue report.
+
+
+.. _OpenOCD Manual: http://openocd.org/doc/html/index.html