Skip to content

Commit 33f0805

Browse files
kolipakakondalkolipakakondal
committed
Add debug docs
1 parent d4ec1e6 commit 33f0805

File tree

2 files changed

+141
-0
lines changed

2 files changed

+141
-0
lines changed

‎docs/en/debugproject.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,18 @@
11
Debug Your Project
22
===============================
3+
In most cases, only two things are required to start debugging an ESP-IDF project:
4+
5+
1. Create a debug configuration
6+
2. Check whether the board in the created configuration corresponds to the board in use.
7+
8+
.. note::
9+
If you're using Windows, you may need to install drivers using Zadig to run a debug session successfully. For detailed instructions, please refer to this `guide <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html#configure-usb-drivers>`_.
10+
11+
The fastest way to create a debug configuration is to expand the configuration list in the launch bar and click `New Launch Configuration...`. Then select `ESP-IDF GDB OpenOCD Debugging` -> Double Click or `Next`. After that, the preview for the new debug configuration will open where it's necessary to check the board.
12+
13+
After creating the debug configuration, you can go ahead and debug the project. Select the configuration you just created, select debug mode, and click on the "Debug" icon ![](docs_readme/images/icons/debug.png) to start debugging:
14+
15+
.. image:: https://github.com/espressif/idf-eclipse-plugin/assets/24419842/1fb0fb9b-a02a-4ed1-bdba-b4b4d36d100f
16+
:alt: Debugging process
17+
18+
To learn more about the debug configuration, please refer to :ref:`ESP-IDF OpenOCD Debugging <OpenOCDDebugging>`.

‎docs/en/openocddebugging.rst‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
.. _OpenOCDDebugging:
2+
3+
ESP-IDF GDB OpenOCD Debugging
4+
=============================
5+
6+
7+
Create a new debug configuration
8+
---------------------------------
9+
Please follow the below steps to create a new debug configuration:
10+
11+
* Right-click on the project
12+
* `Debug As > Debug Configurations...` This will launch a debug configuration window
13+
* On the left Panel, choose `ESP-IDF GDB OpenOCD Debugging`
14+
* Right Click and create `New Configuration` This will create a new debug configuration for your project
15+
16+
Please navigate through each tab and configure project specific settings.
17+
18+
.. note::
19+
Most of the settings are auto-configured by the plugin.
20+
21+
.. image:: ../../media/OpenOCDDebug_4.png
22+
23+
The other way to create a debug configuration is from the launch configuration bar:
24+
25+
* Expand list with launch/debug configurations
26+
* Click on `New Launch Configuration...`
27+
* Select `ESP-IDF GDB OpenOCD Debugging` and double click on it or on `Next >` button
28+
* In the `Debugger` tab, check if the `Config options` is right for your board.
29+
* Click on `Finish`
30+
31+
.. image:: ../../media/OpenOCDDebug_9.png
32+
33+
Main Tab
34+
--------
35+
1. Enter the “Name:” of this configuration, the default name is "{project_name} Configuration".
36+
2. On the “Main” tab below, under “Project:”, press “Browse” button and select the project if it's not selected or you want to change it.
37+
3. In the next line “C/C++ Application:” should be a relative path to the elf file, for example, "build\hello_world.elf" for `hello_world` project. If the elf file is not there, then likely this project has not been build yet. After building the project, the elf file will appear there, however, you can change it by pressing "Browse" button.
38+
39+
The last section on the "Main" tab is "Build (if required) before launching". If you don't want to build the project each time you are pressing the "Debug" button, click “Disable auto build”.
40+
41+
Points 1 - 3 are shown below.
42+
43+
.. image:: ../../media/OpenOCDDebug_5.png
44+
45+
Debugger Tab
46+
------------
47+
In the `Debugger` tab, all parameters are automatically configured to start debugging, you just need to check if the `Config options` line is appropriate for your board. It automatically adjusts based on `Flash voltage` and `Board` options. If you expand the list of boards, only those that match the selected `Target` will appear. So, for example, if the selected target is `esp32`, you will not see `ESP32-S2-KALUGA-1` in the list, to see it there, you need to change the target to `esp32s2` first. The second option in the debugger tab, which depends on the target, is the `gdb executable`, which is also automatically and dynamically configured based on the target you choose.
48+
49+
Let's take a look at some other options, that you need to check if they auto configured correctly for you:
50+
51+
4. The "Executable path" for OpenOCD is based on eclipse preferences, which are configured after tools installation. Check if the "Actual executable" is correct and if it's not, then likely the tools installation went wrong, so you need to check if tools installed correctly to avoid possible problems. If it's still not correct after tools installation, click on "Browse" and select the path to `openocd.exe` manually.
52+
5. In the next step, please make sure that the GDB port is 3333 if you want to use an internal gdb client and the Tcl port is 6666 if you want to use [Application Level Tracing](https://github.com/espressif/idf-eclipse-plugin#application-level-tracing). Also, check `Config options` as described above.
53+
6. In the `GDB Client Setup` section as described above, the gdb executable should be automatically and dynamically configured based on the target you choose. You can change it, by clicking "Browse" button and selecting the path to the gdb executable. By default, the "Commands" line should be `set mem inaccessible-by-default off`.
54+
55+
Points 4 - 6 are shown below.
56+
57+
.. image:: ../../media/OpenOCDDebug_6.png
58+
59+
.. note::
60+
Update the OpenOCD Config options based on the esp board you've choosen. Please check this `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#id1>`_.
61+
62+
Startup Tab
63+
-----------
64+
7. By default, the binaries will be uploaded to your board before joining a debug session, so there is no need to flash them to the target separately. If for some reason you don't want to do that, you can uncheck the `Flash every time with application binaries` option. Also, you can check `Enable verbose output` option, this will enable debug level 3 - '-d3'.
65+
8. Under “Initialization Commands”, “Initial Reset.” and “Enable ARM semihosting” are enabled by default. Then, in entry field below, must be the following lines:
66+
67+
mon reset halt
68+
flushregs
69+
set remote hardware-watchpoint-limit 2
70+
71+
Points 7 - 8 are shown below.
72+
73+
.. image:: ../../media/OpenOCDDebug_7.png
74+
75+
9. Options `Load Symbols` and `Use project binary` are selected.
76+
10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under “Set break point at:”. Checkout this option and enter the name of the main function e.g. app_main in provided field.
77+
11. Checkout “Continue” option. This will make the program to resume after `mon reset halt` is invoked per point 8. The program will then stop at breakpoint inserted at app_main.
78+
79+
Points 9 - 11 are shown below.
80+
81+
.. image:: ../../media/OpenOCDDebug_8.png
82+
83+
Common Tab
84+
----------
85+
You can save your debug logs to an external file. To do this:
86+
87+
* Go-to Common tab.
88+
* Under `Standard Input and Output` section: Select Output file checkbox, enter log file name and path where you want logs to be redirected.
89+
* Apply changes and run your application.
90+
91+
.. note::
92+
Path to the file can be relative if it's located in the workspace (see screenshot below)
93+
94+
.. image:: ../../media/OpenOCDDebug_13.png
95+
96+
## Preferences for OpenOCD Configuration
97+
OpenOCD path is auto-configured based on the `OPENOCD_SCRIPTS` path defined in the CDT Build environment variables.
98+
99+
.. image:: ../../media/OpenOCDDebug_2.png
100+
101+
Start Debugging
102+
---------------
103+
To start debugging, you need to select your debug configuration, change mode from `Run` to `Debug` and click on launch icon (bug icon).
104+
105+
.. image:: ../../media/OpenOCDDebug_10.png
106+
107+
After stopping the target at the default breakpoint, you will be suggested to switch to the `Debug perspective`.
108+
109+
.. image:: ../../media/OpenOCDDebug_11.png
110+
111+
You can customize the `Debug perspective` in your own way, for example, move some tabs, add additional views that you might find useful, or remove them. To add a view, follow these steps:
112+
113+
* On the top panel of the Eclipse click on `Window`
114+
* `Short View`
115+
* Select the view you want to add
116+
117+
.. image:: ../../media/OpenOCDDebug_12.png
118+
119+
Troubleshooting
120+
---------------
121+
* Please make sure you always have the latest `<https://github.com/espressif/idf-eclipse-plugin/releases/>`_ ESP-IDF Eclipse Plugin/Espressif-IDE.
122+
* Please check `<https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#selecting-jtag-adapter>`_ if the board has JTAG enabled.
123+
* If there is any OpenOCD timeout issue, please increase the GDB server timeout value `<https://www.esp32.com/viewtopic.php?f=40&t=36164#p122701>`_ from the preferences. Usually, this happens while working with large-size applications.
124+
* If you see any error while debugging, please check this OpenOCD troubleshooting FAQ guide `<https://github.com/espressif/openocd-esp32/wiki/Troubleshooting-FAQ>`_ and see if that helps to resolve the issue.
125+
* If you have any issue and want to enable OpenOCD debugging verbose, please check Enable verbose output `<https://github.com/espressif/idf-eclipse-plugin/blob/master/docs_readme/OpenOCD%20Debugging.md#startup-tab>`_ option from the startup tab.

0 commit comments

Comments
 (0)