Debugging with GDB / SWD (#265)

* Create documentation page for debugging

* Add make commands and update documentation

* Add dynamic platform cfg and build dir

* Update documentation

* Update documentation

* Update makefile, hardcode board, debug commands

* Update documentation

* Rename docs page and merge conflicts

* Rebase

* Update documentation

* Remove extra line from makefile

* Update documentation

docs/docs/tutorials/hw-debug.md

@@ -0,0 +1,113 @@
+# :material-bug: Hardware Debugging
+
+## Background
+
+For debugging our boards, we use OpenOCD and GDB.
+
+[OpenOCD (Open On-Chip Debugger)](https://openocd.org/) is a tool that enables on-chip debugging, flash programming, and testing for microcontrollers. It will start a server that listens for commands from various sources such as GDB.
+
+[GDB (GNU Debugger)](https://www.sourceware.org/gdb/) is a debugging tool that enables inspection, modification, and control of program execution on microcontrollers.
+
+## Installation
+
+=== "Windows"
+    ```text
+    choco install openocd
+    ```
+
+=== "Linux"
+    ```text
+    sudo apt-get install openocd
+    ```
+
+=== "Mac"
+    ```text
+    brew install openocd
+    ```
+
+The ARM GNU Toolchain containing GDB is already installed if you followed the [Firmware Development Setup](../firmware/dev-setup.md) guide. Refer to that if it is not installed.
+
+### Verify Installation
+
+Check that both programs are installed and have an acceptable version.
+
+Do not copy the `# version comments`.
+
+```text
+openocd --version               # >= 0.12.0
+arm-none-eabi-gdb --version     # >= 13.0
+```
+
+## Usage
+
+To debug a program, the OpenOCD server must be started and GDB connected to it.
+
+1. Build your project for the `stm32f767` platform. See [Compiling a Project](../firmware/compile-project.md) for more details:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 build
+    ```
+
+2. Plug your board into your computer and ensure it is powered on.
+
+3. Start the OpenOCD server:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-openocd
+    ```
+
+4. In a separate terminal, start GDB:
+
+    ```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-gdb
+    ```
+
+5. Start debugging in the GDB terminal. See the list of common commands and an example below.
+
+### GDB Commands
+
+These commands are executed directly in the GDB terminal.
+
+`help`: Displays a list of available commands and their syntax/descriptions.
+
+`load`: Loads the program into the target device's memory. The `debug-gdb` command has been configured to do this automatically on startup.
+
+`continue`: Resumes program execution until the next breakpoint or end.
+
+`finish`: Continues execution until the current function finishes, then stops.
+
+`next`: Executes the next line of code, stepping over any function calls.
+
+`step`: Executes the next line of code, stepping into any function calls.
+
+`break`: Sets a breakpoint at a specified line or function to pause execution.
+
+`info breakpoints`: Lists all active breakpoints and their details.
+
+`where`: Displays the current call stack, showing the active function and its caller hierarchy.
+
+Refer to [VisualGDB](https://visualgdb.com/gdbreference/commands/) and [GDB Cheat Sheet](https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf) for more commands and details.
+
+### Example
+
+The following commands show an example debugging session with the Blink project.
+
+```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-openocd
+```
+
+```bash
+    make PROJECT=Demo/Blink PLATFORM=stm32f767 debug-gdb
+```
+
+```text
+    (gdb) break main        # Set a breakpoint at the main function
+    (gdb) continue          # Continue the execution of the program
+    (gdb) where             # Display the current call stack
+    (gdb) next              # Execute the next line of code
+    (gdb) quit              # Exit GDB
+```
+
+## Resources
+
+Refer to additional documentation for more information on debugging with [OpenOCD](https://openocd.org/doc/html/index.html) and [GDB](https://sourceware.org/gdb/current/onlinedocs/gdb/).

docs/mkdocs.yml

@@ -118,6 +118,7 @@ nav:
     - tutorials/git.md
     - tutorials/site-dev.md
     - tutorials/wsl-can/index.md
+    - tutorials/hw-debug.md
     - tutorials/ssh-signing.md
   - Firmware:
     - firmware/index.md

firmware/Makefile

@@ -17,7 +17,7 @@ PROJECT_NAME := $(notdir $(patsubst %/,%,$(PROJECT)))
 
 COMPILE_COMMANDS_DEST := $(BUILD)/compile_commands.json
 
-.PHONY: build config clean deepclean st-flash
+.PHONY: build config clean deepclean st-flash debug-openocd debug-gdb
 
 build: config
 	cmake --build $(BUILD_DIR)
@@ -44,3 +44,9 @@ endif
 
 st-flash: build
 	st-flash --reset write $(BUILD_DIR)/$(PROJECT_NAME).bin 0x08000000
+
+debug-openocd:
+	openocd -f interface/stlink.cfg -f target/stm32f7x.cfg -c "gdb_port 3333"
+
+debug-gdb:
+	arm-none-eabi-gdb "$(BUILD_DIR)/main.elf" -ex "target extended-remote localhost:3333" -ex "load"