alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-07 20:00:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'doc/esp32s2_jtag_guide' into 'master'

Browse Source 
docs: update JTAG debugging guide for ESP32-S2

Closes FCS-469

See merge request espressif/esp-idf!9473
This commit is contained in:
Ivan Grokhotkov
2020-07-27 19:17:46 +08:00
parent cef10fdfef e6a94e982c
commit 580fe804a8
17 changed files with 1040 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,52 +1,47 @@
Configure WROVER JTAG Interface
===============================
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-defs
:end-before: ---
Configure |devkit-name| JTAG Interface
======================================
:link_to_translation:`zh_CN:[中文]`
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.
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`.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: devkit-hw-config
:end-before: ---
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
+---+---------------+-------------+
| | 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.

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

@@ -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
+---+-----------------------+-------------+
| | 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 |
+---+-----------------------+-------------+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation.

176
docs/en/api-guides/jtag-debugging/esp32.inc Normal file
View File

@@ -0,0 +1,176 @@
.. 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; esp 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``
- Board configuration file for 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``
- Board configuration file for ESP-WROVER-KIT with an 1.8 V ESP32-WROVER module.
* - ``board/esp32-ethernet-kit-3.3v.cfg``
- Board configuration file for 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>
---
.. 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`.
---

160
docs/en/api-guides/jtag-debugging/esp32s2.inc Normal file
View File

@@ -0,0 +1,160 @@
.. 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; esp appimage_offset 0x210000"
---
.. openocd-cfg-files
.. list-table:: OpenOCD configuration files for ESP32-S2
: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:: ESP32-S2 pins and JTAG signals
: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>
---
.. 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.
---

73
docs/en/api-guides/jtag-debugging/index.rst
View File

@@ -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
@@ -42,7 +47,7 @@ This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and d
.. note::
Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTE. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, MacOS or Linux and / or a different release of Eclipse.
Screenshots presented in this document have been made for Eclipse Neon 3 running on Ubuntu 16.04 LTS. There may be some small differences in what a particular user interface looks like, depending on whether you are using Windows, MacOS or Linux and / or a different release of Eclipse.
.. _jtag-debugging-how-it-works:
@@ -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.
@@ -98,7 +101,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc
The output should be as follows (although the version may be more recent than listed here)::
Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04)
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
@@ -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
@@ -144,35 +147,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 |run-openocd-device-name|):
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).
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-output
:end-before: ---
* 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 +177,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 +247,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::
src\openocd -f board\esp32-wrover-kit-3.3v.cfg
and Windows:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-src-win
:end-before: ---
.. _jtag-debugging-tips-and-quirks:

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

@@ -28,7 +28,7 @@ Flash Mappings vs SW Flash Breakpoints
In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format:
``esp32 appimage_offset <offset>``
``esp appimage_offset <offset>``
Offset should be in hex format. To reset to the default behaviour you can specify ``-1`` as offset.
@@ -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
Power supply voltage of ESP32's SPI flash chip
""""""""""""""""""""""""""""""""""""""""""""""
::
set ESP32_FLASH_VOLTAGE 1.8
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.
* - Variable
- Description
* - ``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 to the path (on the host) which will be the default directory for semihosting functions.
.. 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
+---+-----------------------+-------------+
| | 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 |
+---+-----------------------+-------------+
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: jtag-pins
:end-before: ---
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::
openocd -c 'set ESP_FLASH_SIZE 0' -f board/esp32-wrover-kit-3.3v.cfg
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`.
.. note::
@@ -299,7 +254,7 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
1. In issue report provide details of your configuration:
a. JTAG adapter type.
a. JTAG adapter type, and the chip/module being debugged.
b. Release of ESP-IDF used to compile and load application that is being debugged.
c. Details of OS used for debugging.
d. Is OS running natively on a PC or on a virtual machine?
@@ -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
:end-before: ---
openocd -l openocd_log.txt -d3 -f board/esp32-wrover-kit-3.3v.cfg
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:
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:
::
openocd -d3 -f board/esp32-wrover-kit-3.3v.cfg 2>&1 | tee openocd.log
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-openocd-d3-tee
:end-before: ---
Debugger:
::
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: run-gdb-remotelog
:end-before: ---
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
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

65
docs/en/api-guides/jtag-debugging/using-debugger.rst
View File

@@ -2,9 +2,11 @@ Using Debugger
--------------
:link_to_translation:`zh_CN:[中文]`
This section covers configuration and running debugger from :ref:`jtag-debugging-using-debugger-eclipse`
or from :ref:`jtag-debugging-using-debugger-command-line` or using :ref:`jtag-debugging-with-idf-py`.
It is recommended to first check if debugger works from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
This section covers configuration and running debugger using several methods:
* from :ref:`jtag-debugging-using-debugger-eclipse`
* from :ref:`jtag-debugging-using-debugger-command-line`
* using :ref:`jtag-debugging-with-idf-py`.
.. _jtag-debugging-using-debugger-eclipse:
@@ -12,6 +14,10 @@ It is recommended to first check if debugger works from :ref:`jtag-debugging-usi
Eclipse
^^^^^^^
.. note::
It is recommended to first check if debugger works using :ref:`jtag-debugging-with-idf-py` or from :ref:`jtag-debugging-using-debugger-command-line` and then move to using Eclipse.
Debugging functionality is provided out of box in standard Eclipse installation. Another option is to use pluggins like "GDB Hardware Debugging" plugin. We have found this plugin quite convenient and decided to use throughout this guide.
To begin with, install "GDB Hardware Debugging" plugin by opening Eclipse and going to `Help` > `Install` New Software.
@@ -193,50 +199,51 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-co
.. _jtag-debugging-with-idf-py:
Using idf.py debug targets
^^^^^^^^^^^^^^^^^^^^^^^^^^
idf.py debug targets
^^^^^^^^^^^^^^^^^^^^
It is also possible to execute the described debugging tools conveniently from ``idf.py``. These commands are supported:
1. ``idf.py openocd``
1. ``idf.py openocd``
Runs OpenOCD in a console with configuration defined in the environment or via command line.
It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added
from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location
using command line argument ``--openocd-scripts``.
Runs OpenOCD in a console with configuration defined in the environment or via command line.
It uses default script directory defined as ``OPENOCD_SCRIPTS`` environmental variable, which is automatically added
from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location
using command line argument ``--openocd-scripts``.
As for the JTAG configuration of the current board, please use the environmental variable ``OPENOCD_COMMANDS``
or ``--openocd-commands`` command line argument. If none of the above is defined,
OpenOCD is started with ``-f board/esp32-wrover-kit-3.3v.cfg`` board definition.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
:start-after: idf-py-openocd-default-cfg
:end-before: ---
As for the JTAG configuration of the current board, please use the environmental variable ``OPENOCD_COMMANDS``
or ``--openocd-commands`` command line argument. If none of the above is defined,
OpenOCD is started with |idf-py-def-cfg| board definition.
2. ``idf.py gdb``
2. ``idf.py gdb``
Starts the gdb the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial gdb scripts
referring to the current project elf file.
Starts the gdb the same way as the :ref:`jtag-debugging-using-debugger-command-line`, but generates the initial gdb scripts
referring to the current project elf file.
3. ``idf.py gdbtui``
3. ``idf.py gdbtui``
The same as `2`, but starts the gdb with ``tui`` argument allowing very simple source code view.
The same as `2`, but starts the gdb with ``tui`` argument allowing very simple source code view.
4. ``idf.py gdbgui``
4. ``idf.py gdbgui``
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window.
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window.
It is possible to combine these debugging actions on a single command line allowing convenient
setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background
actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
It is possible to combine these debugging actions on a single command line allowing convenient
setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background
actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.
An example of a very useful combination is
::
An example of a very useful combination is::
idf.py openocd gdbgui monitor
.. highlight:: none
The above command runs OpenOCD in the background, starts `gdbgui <https://www.gdbgui.com>`_ to open a browser window
with active debugger frontend and opens a serial monitor in the active console.
The above command runs OpenOCD in the background, starts `gdbgui <https://www.gdbgui.com>`_ to open a browser window
with active debugger frontend and opens a serial monitor in the active console.