Skip to content

Commit d65a995

Browse files
brianignacio5brianignacio5
authored
Bugfix/debugging docs (#1131)
* update verify app * update debug docs example configs * fix lint * adding cdt gdb adapter as dependency * rm py debug adapter from setup update template * update docs with cdt gdb adapter * add peripheral view support * moving to cdt gdb adapter fix doctor cmd test test node 16 try node 18 remove out delete try rm set output modify github output another try at test result test again rm comment code * rm commented code * update peripheral values on stopped event * rm console log line * add support for gdbstub * add core dump * update lockfile * update docs * fix test * add IDF_TARGET_CPU_WATCHPOINT_NUM simplify default launch json * fix esp32h2 hw breakpoint number * listen to disconnect with restart event keep openocd running * update default target connect cmds
1 parent a3291c6 commit d65a995

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+6748
-321
lines changed

‎.github/actions/idf/entrypoint.sh

+4-1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ export PY_PKGS=$(python -m pip list --format json)
1919
yarn
2020
yarn lint
2121
Xvfb -ac :99 -screen 0 1920x1080x16 & sleep 2 & yarn test
22-
echo ::set-output name=result::$(cat ./out/results/test-results.xml)
22+
EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
23+
echo "result<<$EOF" >> $GITHUB_OUTPUT
24+
echo "$(cat ./out/results/test-results.xml)" >> $GITHUB_OUTPUT
25+
echo "$EOF" >> $GITHUB_OUTPUT
2326

2427
rm -r .vscode-test

‎.github/workflows/ci.yml

+3-6
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,12 @@ jobs:
1313
runs-on: ubuntu-latest
1414

1515
steps:
16-
- name: Clone Repository
17-
uses: actions/checkout@v2
16+
- uses: actions/checkout@v4
1817
with:
1918
submodules: "recursive"
20-
21-
- name: Setup Node.js 14
22-
uses: actions/setup-node@v2
19+
- uses: actions/setup-node@v4
2320
with:
24-
node-version: "14"
21+
node-version: 18
2522

2623
- name: Install Node Dependencies
2724
run: yarn

‎.github/workflows/ui-test.yml

+1-2
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,7 @@ jobs:
1313
runs-on: ubuntu-latest
1414

1515
steps:
16-
- name: Clone Repository
17-
uses: actions/checkout@v2
16+
- uses: actions/checkout@v4
1817
with:
1918
submodules: "recursive"
2019

‎README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -185,15 +185,15 @@ Click <kbd>F1</kbd> to show Visual studio code actions, then type **ESP-IDF** to
185185
We have implemented some utilities commands that can be used in tasks.json and launch.json that can be used like:
186186

187187
```json
188-
"miDebuggerPath": "${command:espIdf.getXtensaGdb}"
188+
"miDebuggerPath": "${command:espIdf.getToolchainGdb}"
189189
```
190190

191191
- `espIdf.getExtensionPath`: Get the installed location absolute path.
192192
- `espIdf.getOpenOcdScriptValue`: Return the value of OPENOCD_SCRIPTS from `idf.customExtraVars` or from system OPENOCD_SCRIPTS environment variable.
193193
- `espIdf.getOpenOcdConfig`: Return the openOCD configuration files as string. Example `-f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp32-wrover.cfg`.
194194
- `espIdf.getProjectName`: Return the project name from current workspace folder `build/project_description.json`.
195-
- `espIdf.getXtensaGcc`: Return the absolute path of the toolchain gcc for the ESP-IDF target given by `idf.adapterTargetName` configuration setting and `idf.customExtraPaths`.
196-
- `espIdf.getXtensaGdb`: Return the absolute path of the toolchain gdb for the ESP-IDF target given by `idf.adapterTargetName` configuration setting and `idf.customExtraPaths`.
195+
- `espIdf.getToolchainGcc`: Return the absolute path of the toolchain gcc for the ESP-IDF target given by `idf.adapterTargetName` configuration setting and `idf.customExtraPaths`.
196+
- `espIdf.getToolchainGdb`: Return the absolute path of the toolchain gdb for the ESP-IDF target given by `idf.adapterTargetName` configuration setting and `idf.customExtraPaths`.
197197

198198
See an example in the [debugging](./docs/DEBUGGING.md) documentation.
199199

‎docs/DEBUGGING.md

+161-42
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,168 @@
77
88
The Visual Studio Code uses `.vscode/launch.json` to configure debug as specified in [Visual Studio Code Debugging](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).
99

10-
We recommend using our ESP-IDF Debug Adapter to debug your ESP-IDF projects, but you can also just configure launch.json for the [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools).
10+
We recommend using our `Eclipse CDT GDB Adapter` configuration to debug your ESP-IDF projects, but you can configure launch.json for any GDB debugger extension like [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) and [Native Debug](https://marketplace.visualstudio.com/items?itemName=webfreak.debug). The ESP-IDF Debug adapter will be deprecated and removed in the next major release.
1111

1212
Our extension implements a `ESP-IDF: Peripheral View` tree view in the `Run and Debug` view which will use the SVD file defined in the `IDF SVD File Path (idf.svdFilePath)` configuration setting to be defined in the [settings.json](../SETTINGS.md) to populate a set of peripherals registers values for the active debug session target. You could find Espressif SVD files from [Espressif SVD](https://github.com/espressif/svd).
1313

14+
If `initCommands`, `gdbinitFile` or `initGdbCommands` are defined in launch.json, make sure to include the following commands for debug session to properly work as shown in [JTAG Debugging with command line](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/using-debugger.html#command-line).
15+
16+
## Using the Eclipse CDT GDB Debug Adapter
17+
18+
The Eclipse CDT team have published a GDB debug adapter as NPM package which we include in our extension dependencies. For more information about the debug adapter please review [CDT-GDB-Adapter Github Repository](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter).
19+
20+
The default configuration is:
21+
22+
```JSON
23+
{
24+
"configurations": [
25+
{
26+
"type": "gdbtarget",
27+
"request": "attach",
28+
"name": "Eclipse CDT GDB Adapter"
29+
}
30+
]
31+
}
32+
```
33+
34+
where required of the arguments are automatically defined and resolved by the extension itself.
35+
36+
In case the user wants more customized control, the basic arguments in launch.json are:
37+
38+
```JSON
39+
{
40+
"configurations": [
41+
{
42+
"type": "gdbtarget",
43+
"request": "attach",
44+
"name": "Eclipse CDT Remote",
45+
"program": "${workspaceFolder}/build/${command:espIdf.getProjectName}.elf",
46+
"initCommands": [
47+
"set remote hardware-watchpoint-limit {IDF_TARGET_CPU_WATCHPOINT_NUM}",
48+
"mon reset halt",
49+
"maintenance flush register-cache",
50+
"thb app_main"
51+
],
52+
"gdb": "${command:espIdf.getToolchainGdb}",
53+
"target": {
54+
"connectCommands": [
55+
"set remotetimeout 20",
56+
"-target-select extended-remote localhost:3333"
57+
]
58+
}
59+
}
60+
]
61+
}
62+
```
63+
64+
- `program`: ELF file of your project build directory to execute the debug session. The command `${command:espIdf.getProjectName}` will query the extension to find the current build directory project name.
65+
- `initCommands`: GDB Commands to initialize GDB and target.
66+
- `gdb`: GDB executable to be used. By default `"${command:espIdf.getToolchainGdb}"` will query the extension to find the ESP-IDF toolchain GDB for the current `IDF_TARGET` of your esp-idf project (esp32, esp32c6, etc.).
67+
68+
> **NOTE** `{IDF_TARGET_CPU_WATCHPOINT_NUM}` is resolved by the extension according to the current `IDF_TARGET` of your esp-idf project (esp32, esp32c6, etc.).
69+
70+
Some additional arguments you might use are:
71+
72+
- `runOpenOCD`: (Default: true). Run extension openOCD Server.
73+
- `verifyAppBinBeforeDebug`: (Default: false) Verify that current ESP-IDF project binary is the same as binary in chip.
74+
- `logFile`: Absolute path to the file to log interaction with gdb. Example: `${workspaceFolder}/gdb.log`.
75+
- `verbose`: Produce verbose log output.
76+
- `environment`: Environment variables to apply to the ESP-IDF Debug Adapter. It will replace global environment variables and environment variables used by the extension.
77+
78+
```json
79+
"environment": {
80+
"VAR": "Value"
81+
}
82+
```
83+
84+
- `imageAndSymbols`:
85+
86+
```json
87+
"imageAndSymbols": {
88+
"symbolFileName": "If specified, a symbol file to load at the given (optional) offset",
89+
"symbolOffset": "If symbolFileName is specified, the offset used to load",
90+
"imageFileName": "If specified, an image file to load at the given (optional) offset",
91+
"imageOffset": "If imageFileName is specified, the offset used to load"
92+
}
93+
```
94+
95+
- `target`: Configuration for target to be attached. Specifies how to connect to the device to debug. Usually OpenOCD exposes the chip as a remote target on port `3333`.
96+
97+
```json
98+
"target": {
99+
"type": "The kind of target debugging to do. This is passed to -target-select (defaults to remote)",
100+
"host": "Target host to connect to (defaults to 'localhost', ignored if parameters is set)",
101+
"port": "Target port to connect to (defaults to value captured by serverPortRegExp, ignored if parameters is set)",
102+
"parameters": "Target parameters for the type of target. Normally something like localhost:12345. (defaults to `${host}:${port}`)",
103+
"connectCommands": "Replace all previous parameters to specify an array of commands to establish connection"
104+
}
105+
```
106+
107+
Other arguments please review this extension's package.json `gdbtarget` debugger contribution.
108+
109+
## Use Microsoft C/C++ Extension to Debug
110+
111+
The user can also use [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) to debug, the community recommend this launch.json configuration:
112+
113+
```JSON
114+
{
115+
"configurations": [
116+
{
117+
"name": "GDB",
118+
"type": "cppdbg",
119+
"request": "launch",
120+
"MIMode": "gdb",
121+
"miDebuggerPath": "${command:espIdf.getToolchainGdb}",
122+
"program": "${workspaceFolder}/build/${command:espIdf.getProjectName}.elf",
123+
"windows": {
124+
"program": "${workspaceFolder}\\build\\${command:espIdf.getProjectName}.elf"
125+
},
126+
"cwd": "${workspaceFolder}",
127+
"environment": [{ "name": "PATH", "value": "${config:idf.customExtraPaths}" }],
128+
"setupCommands": [
129+
{ "text": "set remotetimeout 20" },
130+
],
131+
"postRemoteConnectCommands": [
132+
{ "text": "mon reset halt" },
133+
{ "text": "maintenance flush register-cache"},
134+
],
135+
"externalConsole": false,
136+
"logging": {
137+
"engineLogging": true
138+
}
139+
}
140+
]
141+
}
142+
```
143+
144+
# Using NativeDebug
145+
146+
The user can also try using the [Native Debug](https://marketplace.visualstudio.com/items?itemName=webfreak.debug) extension with this example launch.json configuration:
147+
148+
```JSON
149+
{
150+
"configurations": [
151+
{
152+
"type": "gdb",
153+
"request": "attach",
154+
"name": "NativeDebug",
155+
"target": "extended-remote :3333",
156+
"executable": "${workspaceFolder}/build/${command:espIdf.getProjectName}.elf",
157+
"gdbpath": "${command:espIdf.getToolchainGdb}",
158+
"cwd": "${workspaceRoot}",
159+
"autorun": [
160+
"mon reset halt",
161+
"maintenance flush register-cache",
162+
"thb app_main"
163+
]
164+
}
165+
]
166+
}
167+
```
168+
14169
## Use the ESP-IDF Debug Adapter
15170

16-
> **NOTE:** Currently the python package `pygdbmi` used by the debug adapter still depends on some Python 2.7 libraries (libpython2.7.so.1.0) so make sure that the Python executable you use in `idf.pythonBinPath` contains these libraries. This will be dropped in later versions of ESP-IDF.
171+
**DEPRECATED NOTICE**: We are deprecating the use of our ESP-IDF Debug Adapter in favor of using the Eclipse CDT GDB Adapter. It will removed from extension in the future major release.
17172

18173
This extension includes the [ESP-IDF Debug Adapter](https://github.com/espressif/esp-debug-adapter) which implement the debug adapter protocol (DAP) to communicate Xtensa's Toolchain and OpenOCD with Visual Studio Code allowing the user to easily debug ESP-IDF applications. Visual Studio Code will:
19174

@@ -45,7 +200,7 @@ The ESP-IDF Debug Adapter settings for launch.json are:
45200
- `initGdbCommands`: One or more xtensa-esp32-elf-gdb commands to execute in order to setup the underlying debugger.
46201
> **NOTE**: If `gdbinitFile` is defined, these commands will be ignored.
47202
- `logLevel`: Debug Adapter logging level (0-4), 5 - for a full OOCD log. Default: 2.
48-
- `mode`: Can be either `auto`, to start the Debug Adapter and OpenOCD server within the extension or `manual`, to connect to existing Debug Adapter and OpenOCD session. Default: auto.
203+
- `mode`: Can be either `auto`, to start the Debug Adapter and OpenOCD server within the extension or `manual`, to connect to an already running Debug Adapter and OpenOCD session. Default: auto.
49204
> **NOTE:** If set to `manual`, OpenOCD and ESP-IDF Debug Adapter have to be manually executed by the user and the extension will just try to connect to existing servers at configured ports.
50205
- `name`: The name of the debug launch configuration. This will be shown in the Run view (Menu View -> Run).
51206
- `type`: Type of debug configuration. It **must** be `espidf`.
@@ -67,7 +222,6 @@ Example launch.json for ESP-IDF Debug Adapter:
67222

68223
```JSON
69224
{
70-
"version": "0.2.0",
71225
"configurations": [
72226
{
73227
"type": "espidf",
@@ -80,9 +234,10 @@ Example launch.json for ESP-IDF Debug Adapter:
80234
"tmoScaleFactor": 1,
81235
"initGdbCommands": [
82236
"target remote :3333",
237+
"set remotetimeout 20",
83238
"symbol-file /path/to/program.elf",
84239
"mon reset halt",
85-
"flushregs",
240+
"maintenance flush register-cache",
86241
"thb app_main"
87242
],
88243
"env": {
@@ -95,40 +250,4 @@ Example launch.json for ESP-IDF Debug Adapter:
95250

96251
### Output and Logs from ESP-IDF Debug Adapter and OpenOCD
97252

98-
Beside the Visual Studio Code Debug console output. You can find the debug adapter output in `<project_dir>/debug.log` and Menu View -> Output -> `ESP-IDF Debug Adapter` as well as OpenOCD output in Menu View -> Output -> `OpenOCD`.
99-
100-
## Use Microsoft C/C++ Extension to Debug
101-
102-
The user can also use [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) to debug, the community recommend this launch.json configuration:
103-
104-
```JSON
105-
{
106-
"version": "0.2.0",
107-
"configurations": [
108-
{
109-
"name": "GDB",
110-
"type": "cppdbg",
111-
"request": "launch",
112-
"MIMode": "gdb",
113-
"miDebuggerPath": "${command:espIdf.getXtensaGdb}",
114-
"program": "${workspaceFolder}/build/${command:espIdf.getProjectName}.elf",
115-
"windows": {
116-
"program": "${workspaceFolder}\\build\\${command:espIdf.getProjectName}.elf"
117-
},
118-
"cwd": "${workspaceFolder}",
119-
"environment": [{ "name": "PATH", "value": "${config:idf.customExtraPaths}" }],
120-
"setupCommands": [
121-
{ "text": "target remote :3333" },
122-
{ "text": "set remote hardware-watchpoint-limit 2"},
123-
{ "text": "mon reset halt" },
124-
{ "text": "thb app_main" },
125-
{ "text": "flushregs" }
126-
],
127-
"externalConsole": false,
128-
"logging": {
129-
"engineLogging": true
130-
}
131-
}
132-
]
133-
}
134-
```
253+
Beside the Visual Studio Code Debug console output. You can find OpenOCD and the ESP-IDF debug adapter output in `<project_dir>/debug.log` and Menu View -> Output -> `ESP-IDF`.

0 commit comments

Comments
 (0)