docs: repurpose WROVER-KIT debugging guide for Kaluga-1

docs/conf_common.py

@@ -152,7 +152,6 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst',
                'get-started-legacy/**']
 
 ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
-              'api-guides/jtag-debugging/configure-wrover.rst',
               'api-reference/system/himem.rst',
               'api-guides/RF_calibration.rst',
               'api-reference/system/ipc.rst',

docs/en/api-guides/jtag-debugging/configure-wrover.rst → docs/en/api-guides/jtag-debugging/configure-ft2232h-jtag.rst

@@ -1,52 +1,47 @@
-Configure WROVER JTAG Interface
-===============================
-:link_to_translation:`zh_CN:[中文]`
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: devkit-defs
+   :end-before: ---
+
 
-All versions of ESP-WROVER-KIT boards have built-in JTAG functionality. Putting it to work requires setting jumpers to enable JTAG functionality, setting SPI flash voltage and configuring USB drivers. Please refer to step by step instructions below.
+Configure |devkit-name| JTAG Interface
+======================================
+:link_to_translation:`zh_CN:[中文]`
 
+All versions of |devkit-name| boards have built-in JTAG functionality. Putting it to work requires setting jumpers or DIP switches to enable JTAG functionality, and configuring USB drivers. Please refer to step by step instructions below.
 
 Configure Hardware
 ^^^^^^^^^^^^^^^^^^
 
-1.  Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
-
-2.  Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+    :start-after: devkit-hw-config
+    :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         |
-    +---+---------------+-------------+
+* Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
 
+    .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+        :start-after: jtag-pins
+        :end-before: ---
 
 Configure USB Drivers
 ^^^^^^^^^^^^^^^^^^^^^
 
-Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP-WROVER-KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
+Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on |devkit-name| board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
 
-.. note:: ESP-WROVER-KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
+.. note:: |devkit-name| uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
 
 
 Windows
 """""""
 
-1.  Using standard USB A / micro USB B cable connect ESP-WROVER-KIT to the computer. Switch the WROVER KIT on.
+1.  Using standard USB A / micro USB B cable connect |devkit-name| to the computer. Switch the |devkit-name| on.
 
-2.  Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then download them from https://www.ftdichip.com/Drivers/D2XX.htm and install manually.
+2.  Wait until USB ports of |devkit-name| are recognized by Windows and drives are installed. If they do not install automatically, then download them from https://www.ftdichip.com/Drivers/D2XX.htm and install manually.
 
 3.  Download Zadig tool (Zadig_X.X.exe) from https://zadig.akeo.ie/ and run it.
 
 4.  In Zadig tool go to "Options" and check "List All Devices".
 
-5.  Check the list of devices that should contain two WROVER specific USB entries: "Dual RS232-HS (Interface 0)" and "Dual RS232-HS (Interface 1)". The driver name would be "FTDIBUS (vxxxx)" and USB ID: 0403 6010.
+5.  Check the list of devices that should contain two |devkit-name| specific USB entries: "Dual RS232-HS (Interface 0)" and "Dual RS232-HS (Interface 1)". The driver name would be "FTDIBUS (vxxxx)" and USB ID: 0403 6010.
 
     .. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg
         :align: center
@@ -55,19 +50,19 @@ Windows
 
         Configuration of JTAG USB driver in Zadig tool
 
-6.  The first device (Dual RS232-HS (Interface 0)) is connected to the JTAG port of the ESP32. Original "FTDIBUS (vxxxx)" driver of this device should be replaced with "WinUSB (v6xxxxx)". To do so, select "Dual RS232-HS (Interface 0) and reinstall attached driver to the "WinUSB (v6xxxxx)", see picture above.
+6.  The first device (Dual RS232-HS (Interface 0)) is connected to the JTAG port of the {IDF_TARGET_NAME}. Original "FTDIBUS (vxxxx)" driver of this device should be replaced with "WinUSB (v6xxxxx)". To do so, select "Dual RS232-HS (Interface 0) and reinstall attached driver to the "WinUSB (v6xxxxx)", see picture above.
 
 .. note::
 
-    Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
+    Do not change the second device "Dual RS232-HS (Interface 1)". It is routed to {IDF_TARGET_NAME}'s serial port (UART) used for upload of application to {IDF_TARGET_NAME}'s flash.
 
-Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
+Now |devkit-name|'s JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
 
 
 Linux
 """""
 
-1.  Using standard USB A / micro USB B cable connect ESP-WROVER-KIT board to the computer. Power on the board.
+1.  Using standard USB A / micro USB B cable connect |devkit-name| board to the computer. Power on the board.
 
 .. highlight:: none
 
@@ -92,9 +87,9 @@ Linux
 
     If you see similar result and you are a member of ``plugdev`` group, then the set up is complete.
 
-    The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to ESP32's serial port (UART) used for upload of application to ESP32's flash.
+    The ``/dev/ttyUSBn`` interface with lower number is used for JTAG communication. The other interface is routed to {IDF_TARGET_NAME}'s serial port (UART) used for upload of application to {IDF_TARGET_NAME}'s flash.
 
-Now ESP-WROVER-KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
+Now |devkit-name|'s JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
 
 
 MacOS
@@ -104,14 +99,14 @@ On macOS, using FT2232 for JTAG and serial port at the same time needs some addi
 
 1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.
 
-2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on WROVER KIT.
+2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on |devkit-name|.
 
 Manually unloading the driver
 .............................
 
 1. Install FTDI driver from https://www.ftdichip.com/Drivers/VCP.htm
 
-2. Connect USB cable to the WROVER KIT.
+2. Connect USB cable to the |devkit-name|.
 
 3. Unload the serial port driver::
 
@@ -121,9 +116,11 @@ Manually unloading the driver
 
     sudo kextunload -b com.apple.driver.AppleUSBFTDI
 
-4. Run OpenOCD::
+4. Run OpenOCD:
 
-    bin/openocd -f board/esp32-wrover-kit-3.3v.cfg
+   .. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+       :start-after: run-openocd
+       :end-before: ---
 
 5. In another terminal window, load FTDI serial port driver again::
 
@@ -131,7 +128,7 @@ Manually unloading the driver
 
 .. note::
 
-   If you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if WROVER KIT was reconnected or power was toggled.
+   If you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if |devkit-name| was reconnected or power was toggled.
 
 This procedure can be wrapped into a shell script, if desired.
 

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

@@ -161,3 +161,16 @@
     xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
 
 ---
+
+.. devkit-defs
+
+.. |devkit-name| replace:: ESP-WROVER-KIT
+.. |devkit-name-with-link| replace:: :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`
+
+---
+
+.. devkit-hw-config
+
+* Enable on-board JTAG functionality by setting JP8 according to :doc:`../../hw-reference/esp32/get-started-wrover-kit`, Section :ref:`get-started-esp-wrover-kit-v4.1-setup-options`.
+
+---

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

@@ -145,3 +145,16 @@
     xtensa-esp32s2-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
 
 ---
+
+.. devkit-defs
+
+.. |devkit-name| replace:: ESP-S2-Kaluga-1
+.. |devkit-name-with-link| replace:: :doc:`ESP-S2-Kaluga-1 <../../hw-reference/modules-and-boards>`
+
+---
+
+.. devkit-hw-config
+
+* Out of the box, ESP32-S2-Kaluga-1 doesn't need any additional hardware configuration for JTAG debugging. However if you are experiencing issues, check that switches 2-5 of the "JTAG" DIP switch block are in "ON" position.
+
+---

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

@@ -25,6 +25,11 @@ GDB. The document is structured as follows:
     This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
 
 
+.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
+   :start-after: devkit-defs
+   :end-before: ---
+
+
 .. _jtag-debugging-introduction:
 
 Introduction
@@ -62,9 +67,7 @@ Under "Application Loading and Monitoring" there is another software and hardwar
 
 Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse <https://www.eclipse.org/>`_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms.
 
-.. only:: esp32
-
-    If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection.
+If the |devkit-name-with-link| is used, then connection from PC to {IDF_TARGET_NAME} is done effectively with a single USB cable. This is made possible by the FT2232H chip, which provides two USB channels, one for JTAG and the one for UART connection.
 
 Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse.
 
@@ -74,7 +77,7 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate
 Selecting JTAG Adapter
 ----------------------
 
-The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
+The quickest and most convenient way to start with JTAG debugging is by using |devkit-name-with-link|. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. |devkit-name| is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter.
 
 If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range.
 
@@ -131,7 +134,7 @@ This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the tw
 .. toctree::
     :maxdepth: 1
 
-    :esp32: configure-wrover
+    configure-ft2232h-jtag
     configure-other-jtag
 
 

docs/page_redirects.txt

@@ -47,9 +47,9 @@ get-started-cmake/get-started-wrover-kit-v3    hw-reference/esp32/get-started-wr
 get-started-cmake/get-started-pico-kit         hw-reference/esp32/get-started-pico-kit
 get-started-cmake/get-started-pico-kit-v3      hw-reference/esp32/get-started-pico-kit-v3
 
-api-guide/build-system-cmake                   api-guide/build-system
-api-guide/ulp-cmake                            api-guide/ulp
-api-guide/unit-tests-cmake                     api-guide/unit-tests
+api-guides/build-system-cmake                   api-guides/build-system
+api-guides/ulp-cmake                            api-guides/ulp
+api-guides/unit-tests-cmake                     api-guides/unit-tests
 
 api-reference/network/tcpip_adapter            api-reference/network/esp_netif
 
@@ -67,3 +67,5 @@ hw-reference/get-started-pico-kit-v3       hw-reference/esp32/get-started-pico-k
 hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0
 hw-reference/get-started-ethernet-kit      hw-reference/esp32/get-started-ethernet-kit
 hw-reference/esp32s2/user-guide-kaluga-1-v1.2  hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit
+
+api-guides/jtag-debugging/configure-wrover  api-guides/jtag-debugging/configure-ft2232h-jtag

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

@@ -127,7 +127,7 @@ JTAG 正常工作至少需要连接的信号线有：TDI，TDO，TCK，TMS 和 G
 .. toctree::
     :maxdepth: 1
 
-    :esp32: configure-wrover
+    configure-ft2232h-jtag
     configure-other-jtag