This page provides a brief summary of the most commonly used GDB commands with the Black Magic Probe. It is provided just as an introduction, the GDB Manual should be consulted for more complete information.
GDB’s online help system is also a good source of information. Use the command
help <command> for more information about any GDB command.
Connecting to the Black Magic Probe and target¶
Connecting GDB to the Black Magic Probe¶
target extended-remote <port>
This command connects GDB to the Black Magic Probe for remote target debugging. It does not perform any JTAG or SWD actions and does not attach GDB to the target processor.
The port parameter should be the name of the serial interface of the GDB server provided by the Black Magic Probe. On Linux:
target extended-remote /dev/ttyACM0 target extended-remote /dev/serial/by-id/usb-Black_Sphere_Technologies_Black_Magic_Probe_E2C0C4C6-if00 target extended-remote /dev/ttyBmpGdb
On OS X:
target extended-remote /dev/cu.usbmodemE2C0C4C6
target extended-remote COM3 target extended-remote \\.\COM10
List available Black Magic Probe commands¶
(gdb) monitor help General commands: version -- Display firmware version info help -- Display help for monitor commands jtag_scan -- Scan JTAG chain for devices swdp_scan -- Scan SW-DP for devices targets -- Display list of available targets morse -- Display morse error message connect_srst -- Configure connect under SRST: (enable|disable) hard_srst -- Force a pulse on the hard SRST line - disconnects target debug_bmp -- Output BMP "debug" strings to the second vcom: (enable|disable)
The list of available commands is context sensitive. After connecting to certain targets the list of available commands changes. For example STM32 targets provide
monitor erase_mass that is not available until you scan for available targets and find the STM32 target.
Finding connected targets¶
monitor jtag_scan monitor swdp_scan
These commands instruct the Black Magic Probe to scan for connected target devices using the JTAG or SWD interfaces. Any currently connected target will be detached by this command.
monitor tpwr enable
Using black magic probe v2, there is a voltage translator present. By default, the voltage translator is off, and expects a Vtarget voltage present. If Vtarget is not connected to the target board, use the tpwr enable command to power translator with the onboard 3.3V regulator.
Attaching to a target¶
Attach GDB to a target device connected to the Black Magic Probe. The argument must be a target id displayed in the output of one of the monitor commands above. Attaching will not reset the target, for that use the
Enabling access to memory mapped IO from GDB¶
set mem inaccessible-by-default off
This command instructs GDB to allow access to memory outside of the devices known memory map. This is useful to allow access to memory mapped IO from GDB.
Because the above are all common commands that you are likely to run every time you start GDB, you may want to include them in your
.gdbinit file. Create a text file named
.gdbinit in your home directory or project directory from which you run GDB and it will execute these commands on startup.
Loading your program onto the target¶
This command will transfer your program binary to the target device. If the program is linked at Flash memory addresses, the Flash will be erased and programmed accordingly.
This command will compare a CRC32 of the target memory to the sections of your binary file and report if an inconsistency is found. It is useful to verify the flash programming.
Debugging with GDB¶
Starting your program¶
These command reset and begin execution on the target.
run allows the target to run normally until interrupted or other event occurs, while
start runs through the start-up code will halt on entry to the
While the target is running, it may be interrupted by typing Ctrl-C in the GDB console or sending GDB a SIGINT.
Setting stop conditions¶
break <function> break <file>:<line> watch <var>
These commands set breakpoints and watchpoints. Breakpoints will interrupt the target when a particular location in the program is reached, and watchpoints will interrupt the program when a particular variable is changed.
Examining the target state¶
print <expr> x <address> info registers
These commands may be used to inspect target variables, memory or core registers.
dump ihex memory <file> <start> <stop>
This command can be used to dump the target memory contents to an Intel hex file. There are other variants for alternative formats, use the command
help dump for more information.
Detaching from the target device¶
These commands can be used to disconnect the Black Magic Probe from the target device.
kill will also reset the target on detach.