Document debugging with VSCode + STM32CubeCLT + cortex-debug extension

Author: bryceschober

_dev/How-to-debug.md

@@ -232,6 +232,83 @@ This [tutorial](https://visualgdb.com/tutorials/arduino/stm32/) shows how to dev
 
 See the Visual Studio Code extension for Arduino [README.md](https://github.com/microsoft/vscode-arduino/blob/main/README.md).
 
+# Visual Studio Code + STM32CubeCLT + `cortex-debug` extension
+
+These settings were extracted by using the [new STM32 VS Code extension](https://marketplace.visualstudio.com/items?itemName=stmicroelectronics.stm32-vscode-extension)'s generated launch configuration. That extension currently only supports `CMake` projects, so using it for development isn't yet appropriate for all use cases (i.e. [STM32duino](https://github.com/stm32duino/Arduino_Core_STM32)).
+
+## Prerequisites
+
+1. Download and install the latest STM32CubeCLT installer from <https://www.st.com/en/development-tools/stm32cubeclt.html>
+2. Restart Windows in order to reload your system environment variables.
+
+   On Linux, you might need to manually define the appropriate environment variable yourself, something like this, but making sure you have the correct installation path:
+
+   ```shell
+   echo "export STM32CLT_PATH=/opt/st/stm32cubeclt_1.16.0" >> ~/.bashrc
+   ```
+
+## Debug Launch settings
+
+See the embedded comments below for pointers to places you might need or want to modify for your
+application.
+
+```jsonc
+"launch": {
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug w/ ST-Link",
+      "cwd": "${workspaceFolder}",
+      "type": "cortex-debug",
+      "executable": "myproject.elf", // Change to your .elf executable
+      "request": "launch",
+      "servertype": "stlink",
+      "device": "STM32H563ZITx", // Change to your MCU used
+      "interface": "swd",
+      "serialNumber": "", // Set ST-Link ID if you use multiple at the same time
+      "runToEntryPoint": "main",
+      "svdFile": "${env:STM32CLT_PATH}/STMicroelectronics_CMSIS_SVD/STM32H563.svd", // Change based your MCU used
+      "v1": false, // Change it depending on ST Link version
+      "serverpath": "${env:STM32CLT_PATH}/STLink-gdb-server/bin/ST-LINK_gdbserver",
+      "stm32cubeprogrammer": "${env:STM32CLT_PATH}/STM32CubeProgrammer/bin",
+      "stlinkPath": "${env:STM32CLT_PATH}/STLink-gdb-server/bin/ST-LINK_gdbserver",
+      "armToolchainPath": "${env:STM32CLT_PATH}/GNU-tools-for-STM32/bin",
+      "gdbPath": "${env:STM32CLT_PATH}/GNU-tools-for-STM32/bin/arm-none-eabi-gdb",
+      "serverArgs": [
+        "-m",
+        "1",
+      ],
+      //"preLaunchTask": "Build + Flash"
+    },
+    {
+      "name": "Attach w/ ST-Link",
+      "cwd": "${workspaceFolder}",
+      "type": "cortex-debug",
+      "executable": "myproject.elf", // Change to your .elf executable
+      // Let CMake extension decide executable: "${command:cmake.launchTargetPath}"
+      // Or fixed file path: "${workspaceFolder}/path/to/filename.elf"
+      "request": "attach",
+      "servertype": "stlink",
+      "device": "STM32H563ZITx", // Change to your MCU used
+      "interface": "swd",
+      "serialNumber": "", // Set ST-Link ID if you use multiple at the same time
+      "runToEntryPoint": "main",
+      "svdFile": "${env:STM32CLT_PATH}/STMicroelectronics_CMSIS_SVD/STM32H563.svd", // Change based your MCU used
+      "v1": false, // Change it depending on ST Link version
+      "serverpath": "${env:STM32CLT_PATH}/STLink-gdb-server/bin/ST-LINK_gdbserver",
+      "stm32cubeprogrammer": "${env:STM32CLT_PATH}/STM32CubeProgrammer/bin",
+      "stlinkPath": "${env:STM32CLT_PATH}/STLink-gdb-server/bin/ST-LINK_gdbserver",
+      "armToolchainPath": "${env:STM32CLT_PATH}/GNU-tools-for-STM32/bin",
+      "gdbPath": "${env:STM32CLT_PATH}/GNU-tools-for-STM32/bin/arm-none-eabi-gdb",
+      "serverArgs": [
+        "-m",
+        "1",
+      ],
+    }
+  ]
+}
+```
+
 # Command Line GDB
 
 ## 1. Command Line GDB