update pico-examples/ide/vscode (#313)

Co-authored-by: martin <[email protected]>

Author: mjcross

ide/vscode/README.md

@@ -0,0 +1,49 @@
+# Sample configuration files for developing with VSCode and the SWD port
+
+This example provides files that illustrate how to use Microsoft(R) Visual Studio Code (*VSCode*) with a target connected via its Serial Wire Debug (*SWD*) port.
+
+Many configurations are possible. VSCode might be running on:
+
+* a Raspberry Pi wired directly to a target's SWD pins
+* a PC or Mac connected to a target via a Pico running [picoprobe](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#debugging-using-another-raspberry-pi-pico)
+* a machine with an already running instance of `OpenOCD`
+
+[Getting Started with the Raspberry Pi Pico](https://rptl.io/pico-get-started) describes a basic setup for VSCode and how to build picoprobe and `OpenOCD`, a tool that connects to the GNU Debugger [GDB](https://www.sourceware.org/gdb/).
+
+**Configuring VSCode to use the SWD port lets it upload code transparently and gives you step-through debugging from within the IDE.**
+
+---
+
+## Assumptions
+
+The example assumes:
+
+1. A functioning development environment with [pico-sdk](https://github.com/raspberrypi/pico-sdk), ARM Toolchain, VSCode and `OpenOCD` all built and installed according to the instructions in the [Getting Started Guide](https://rptl.io/pico-get-started).
+2. A target connected via the SWD port (see above).
+3. Reasonable familiarity with [pico-sdk](https://github.com/raspberrypi/pico-sdk), [CMake](https://cmake.org/cmake/help/latest/guide/tutorial/index.html) and [VSCode workspaces](https://code.visualstudio.com/docs/editor/workspaces).
+
+> Note: The provided files illustrate working configurations but you will almost certainly want to customise them further to meet your needs.
+
+
+---
+
+## Using the Example
+
+1. Open a fresh VScode workspace, add a simple standalone SDK project (removing any existing `build` directory) and create a `.vscode` folder at its top level.
+
+2. Choose the `launch-*-swd.json` file closest to your setup (see below), rename it to `launch.json` and copy it to the `.vscode` folder you created.
+
+    Start with:
+    * `launch-probe-swd.json` if the target is connected via an SWD probe (e.g. picoprobe)
+    * `launch-raspberrypi-swd.json` if the target is directly connected to a Raspberry Pi GPIO 
+    * `launch-remote-openocd.json` if VSCode should connect to an already running instance of `OpenOCD`.
+
+> Be sure to review the selected file and make any changes needed for your environment.
+
+3. Copy the `settings.json` file into the `.vscode` folder. This illustrates how to configure the *CMake* plugin so that you debug using *cortex-debug* instead of trying to launch the executable on the host.
+
+Lauching a debug session in the workspace (e.g. with *f5*) should now build the project and if successful upload it to the target, open a debug session and pause at the start of `main()`.
+
+> VSCode has some background work to do the first time through. If appears to have stalled then leave it alone for at least a minute.
+
+> If `OpenOCD` reports that GDB won't launch or quits unexpectedly, you may need to adjust the *gdbPath* and/or *configFiles* settings in `launch.json`. See the comments in the example files and check the latest [Getting Started](https://rptl.io/pico-get-started).

ide/vscode/launch-probe-swd.json

@@ -0,0 +1,28 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Pico Debug",
+            "cwd": "${workspaceRoot}",
+            "executable": "${command:cmake.launchTargetPath}",
+            "request": "launch",
+            "type": "cortex-debug",
+            "servertype": "openocd",
+            // This may need to be "arm-none-eabi-gdb" for some previous builds
+            "gdbPath" : "gdb-multiarch",
+            "device": "RP2040",
+            "configFiles": [
+                // This may need to be "interface/picoprobe.cfg" for some previous builds
+                "interface/cmsis-dap.cfg",
+                "target/rp2040.cfg"
+            ],
+            "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
+            "runToEntryPoint": "main",
+            // Work around for stopping at main on restart
+            "postRestartCommands": [
+                "break main",
+                "continue"
+            ]
+        }
+    ]
+}

ide/vscode/launch-raspberrypi-swd.json

@@ -8,15 +8,15 @@
             "request": "launch",
             "type": "cortex-debug",
             "servertype": "openocd",
-            // This may need to be arm-none-eabi-gdb depending on your system
+            // This may need to be "arm-none-eabi-gdb" for some previous builds
             "gdbPath" : "gdb-multiarch",
             "device": "RP2040",
             "configFiles": [
                 "interface/raspberrypi-swd.cfg",
                 "target/rp2040.cfg"
             ],
             "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
-            "runToMain": true,
+            "runToEntryPoint": "main",
             // Work around for stopping at main on restart
             "postRestartCommands": [
                 "break main",

ide/vscode/launch-remote-openocd.json

@@ -8,12 +8,12 @@
             "executable": "${command:cmake.launchTargetPath}",
             "request": "launch",
             "servertype": "external",
-            // This may need to be arm-none-eabi-gdb depending on your system
+            // This may need to be "arm-none-eabi-gdb" for older builds
             "gdbPath" : "gdb-multiarch",
             // Connect to an already running OpenOCD instance
             "gdbTarget": "your-openocd:3333",
             "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
-            "runToMain": true,
+            "runToEntryPoint": "main",
             // Work around for stopping at main on restart
             "postRestartCommands": [
                 "break main",