summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNick Brassel <nick@tzarc.org>2024-03-08 22:24:11 +1100
committerGitHub <noreply@github.com>2024-03-08 22:24:11 +1100
commit8946aace5bb3c5397b79b0e5999cc9547e0ade65 (patch)
treeba50078e796c67ac11bc142810c953e2cbf51951
parent0a03fc512c471d3836d071686afafda0f62be62f (diff)
Add instructions for debugging ARM with VSCode+BMP. (#11217)
-rw-r--r--docs/other_vscode.md74
1 files changed, 74 insertions, 0 deletions
diff --git a/docs/other_vscode.md b/docs/other_vscode.md
index 49d5035b08..4c71a0eb1c 100644
--- a/docs/other_vscode.md
+++ b/docs/other_vscode.md
@@ -117,3 +117,77 @@ Using the [standard `compile_commands.json` database](https://clang.llvm.org/doc
1. Start typing `clangd: Restart Language Server` and select it when it appears.
Now you're ready to code QMK Firmware in VS Code!
+
+# Debugging ARM MCUs with Visual Studio Code
+
+**...and a Black Magic Probe.**
+
+Visual Studio Code has the ability to debug applications, but requires some configuration in order to get it to be able to do so for ARM targets.
+
+This documentation describes a known-working configuration for setting up the use of a Black Magic Probe to debug using VS Code.
+
+It is assumed that you've correctly set up the electrical connectivity of the Black Magic Probe with your MCU. Wiring up `NRST`, `SWDIO`, `SWCLK`, and `GND` should be enough.
+
+Install the following plugin into VS Code:
+
+* [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) -
+ This adds debugger support for ARM Cortex targets to VS Code.
+
+A debugging target for the MCU for your board needs to be defined, and can be done so by adding the following to a `.vscode/launch.json` file:
+
+```json
+{
+ // Use IntelliSense to learn about possible attributes.
+ // Hover to view descriptions of existing attributes.
+ // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Black Magic Probe (OneKey Proton-C)",
+ "type": "cortex-debug",
+ "request": "launch",
+ "cwd": "${workspaceRoot}",
+ "executable": "${workspaceRoot}/.build/handwired_onekey_proton_c_default.elf",
+ "servertype": "bmp",
+ "BMPGDBSerialPort": "COM4",
+ "svdFile": "Q:\\svd\\STM32F303.svd",
+ "device": "STM32F303",
+ "v1": false,
+ "windows": {
+ "armToolchainPath": "C:\\QMK_MSYS\\mingw64\\bin"
+ }
+ }
+ ]
+}
+```
+
+You'll need to perform some modifications to the file above in order to target your specific device:
+
+* `"name"`: Can be anything, but if you're debugging multiple targets you'll want something descriptive here.
+* `"cwd"`: The path to the QMK Firmware repository root directory -- _if using the `.vscode` directory existing in the `qmk_firmware` git repository, the default above should be correct_
+* `"executable"`: The path to the `elf` file generated as part of the build for your keyboard -- _exists in `<qmk_firmware>/.build`_
+* `"BMPGDBSerialPort"`: The `COM` port under Windows, or the `/dev/...` path for Linux/macOS. Two serial port devices will be created -- the Black Magic Probe debug port is *usually* the first. If it doesn't work, try the second.
+* `"svdFile"`: _[Optional]_ The path to the SVD file that defines the register layout for the MCU -- the appropriate file can be downloaded from the [cmsis-svd repository](https://github.com/posborne/cmsis-svd/tree/master/data/STMicro)
+* `"device"`: The name of the MCU, which matches the `<name>` tag at the top of the downloaded `svd` file.
+* `"armToolchainPath"`: _[Optional]_ The path to the ARM toolchain installation location on Windows -- under normal circumstances Linux/macOS will auto-detect this correctly and will not need to be specified.
+
+!> Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings: ![VSCode Settings](https://i.imgur.com/EGrPM1L.png)
+
+Optionally, the following modifications should also be made to the keyboard's `rules.mk` file to disable optimisations -- not strictly required but will ensure breakpoints and variable viewing works correctly:
+```makefile
+# Disable optimisations for debugging purposes
+LTO_ENABLE = no
+OPT = g
+DEBUG = 3
+```
+
+At this point, you should build and flash your firmware through normal methods (`qmk compile ...` and `qmk flash ...`).
+
+Once completed, you can:
+* Switch to the debug view in VS Code (in the sidebar, the Play button with a bug next to it)
+* Select the newly-created debug target in the dropdown at the top of the sidebar
+* Click the green play button next to the dropdown
+
+VS Code's debugger will then start executing the compiled firmware on the MCU.
+
+At this stage, you should have full debugging set up, with breakpoints and variable listings working!