diff --git a/docs/docs/tutorials/hw-debug.md b/docs/docs/tutorials/hw-debug.md new file mode 100644 index 000000000..c82453979 --- /dev/null +++ b/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/). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e2e98363c..5494a0d69 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/firmware/Makefile b/firmware/Makefile index 7d9ef7ecd..d597d01fb 100644 --- a/firmware/Makefile +++ b/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"