52 update gdb docs (#53)

* feat: moved the debugging guide to the docs folder * fix: typo in readme * Reorder new docs file * Update docs/development/how_to__gdb_debugging.md contents --------- Co-authored-by: JatoMixo <[email protected]>
aindustriosa · Jul 31, 2024 · db730e9 · db730e9
1 parent 9d9436a
commit db730e9
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -52,19 +52,8 @@ export UPLOAD_TOOL=blackmagic
 cargo xtask run app hello_world
 ```
 
-### Use GDB debug
-
-You need `runner = "gdb-multiarch -q -x openocd_debug.gdb"` in mightybuga_bsc/.cargo/config , then start a openocd instance:
-
-```commandline
-sudo openocd -f openocd.cfg
-```
-
-and:
-
-```commandline
-cargo run
-```
+## Debugging
+Go to the [documentation for debugging](./docs/GDB-Debugging/gdb-debugging.md).
 
 ## References
 Forked from https://cgit.pinealservo.com/BluePill_Rust/blue_pill_base

diff --git a/docs/development/how_to__gdb_debugging.md b/docs/development/how_to__gdb_debugging.md
@@ -0,0 +1,50 @@
+# GDB debugging
+Note that, currently, the debug commands are done inside each binary folder. This is because xtask only has rules for release (not debug) binaries and because each application folder has its own `.cargo` folder with the how to run aliases. 
+
+## Step 1: Config cargo to use GDB with the correct OpenOCD config file for debugging:
+In `mightybuga_bsc/.cargo/config` or `apps/{APP_NAME}/.cargo/config`, depending on what you want to debug, you need to uncomment this line:
+```
+runner = "gdb-multiarch -q -x openocd_debug.gdb"
+```
+
+## Step 2: Start a OpenOCD instance
+Then start a openocd instance (from the directory of an app or `mightybuga_bsc`), for example:
+
+```bash
+cd mightybuga_bsc # or apps/{APP_NAME}
+sudo openocd -f openocd.cfg
+```
+
+## Step 3: Compile and run GDB
+In the app's directory:
+
+```bash
+cd mightybuga_bsc # or apps/{APP_NAME}
+cargo run # you can also debug an example with `--example {EXAMPLE_NAME}`
+```
+
+
+# GDB debugging with VSCode
+We have had success debugging in VSCode using the [Cortex-Debug plugin](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) and [the Device Support Pack - STM32F1](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug-dp-stm32f1) that launches OpenOCD and GDB from the IDE using a `launch.json` like this for the "hello_world" app:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Cortex Debug",
+            "cwd": "${workspaceFolder}",
+            "executable": "./target/thumbv7m-none-eabi/debug/hello_world",
+            "request": "launch",
+            "type": "cortex-debug",
+            "runToEntryPoint": "main",
+            "servertype": "openocd",
+            "configFiles": [
+                "./apps/hello_world/openocd.cfg"
+            ],
+            "showDevDebugOutput": "raw",
+            "deviceName": "STM32F103C8"
+        }
+    ]
+}
+```
diff --git a/mightybuga_bsc/README.md b/mightybuga_bsc/README.md
@@ -18,14 +18,6 @@ cargo xtask mightybuga_bsc example blink # use 'cargo xtask help' for a complete
 ```
 or from the BSC folder:
 
+## Debugging
+Go to the [documentation for debugging](../docs/GDB-Debugging/gdb-debugging.md).
 
-### Debugging
-Check what runner you have uncommented in .cargo/config:
-
-You need `runner = "gdb-multiarch -q -x openocd.gdb", start a openocd instance:
-
-sudo openocd -f openocd.cfg
-
-and:
-
-cargo xtask mightybuga_bsc example blink