diff options
Diffstat (limited to 'docs/other_vscode.md')
| -rw-r--r-- | docs/other_vscode.md | 74 |
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:  + +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! |