Dm00613038 Stm32cubeide ST Link GDB Server Stmicroelectronics
Dm00613038 Stm32cubeide ST Link GDB Server Stmicroelectronics
User manual
Introduction
The STM32CubeIDE ST-LINK GDB server, also referred to as the GDB server, is a command-line application that runs on a PC
connected to the Arm® Cortex®-M target via the ST-LINK JTAG probe.
At start-up, the ST-LINK GDB server connects to the STM32 Arm® Cortex®-M target using the ST-LINK JTAG. After establishing
the target-side communication, it waits for the client to connect to its TCP-listen socket. Once the client is connected to the
TCP-listen socket, the ST-LINK GDB server processes the Remote Serial Protocol (RSP) messages sent by the client, performs
the appropriate target-side actions, and sends RSP replies back to the client.
Figure 1 shows a typical debug session using the ST-LINK GDB server to debug an Arm® Cortex®-M target using
STMicroelectronic ST-LINK probe.
TCP socket
JTAG cable
interface
GDB client
STM32
Running on device
local or remote PC
The figure shows how the GDB client connects to the ST-LINK GDB server via a TCP-socket interface in order to debug the
Arm® Cortex®-M target connected via the ST-LINK JTAG.
• --ext-memory-loaders
Provides the list of the available external memory loaders.
• -el <file_path>, --extload <file_path>
Selects a custom external memory-loader.
• --external-init
Runs Init() from external memory loader after reset to make external memory accessible without need for
application software to set up the access to memory-mapped external memory.
[This option requires that option -el <file_path>, --extload <file_path> is used also.]
• -cp <path>, --stm32cubeprogrammer-path <path>
Path to the STM32CubeProgrammer (STM32CubeProg) installation.
• --pend-halt-timeout <Pending halt timeout>
Specifies the maximum time for ST-LINK GDB server to wait for the core to halt (default time is 2 seconds).
When using this option, the GDB client must also be started to use longer timeout values. For instance, use
a .gdbinit file containing the following two lines to get a 50-second timeout:
– set remotetimeout 50
– set tcp connect-timeout 50
• --temp-path <path>
Temporary files for starting a debug session are stored at the path provided.
• --preserve-temps
Temporary files are not removed.
• --licenses
Provides the list of the tools and licenses used.
• --, --ignore-rest
Ignores the rest of the labeled arguments following this flag.
• --version
Displays version information and exits.
3 Troubleshooting
In case the server hangs or fails to start up, follow these steps:
1. Shutdown the GDB server and any client attached to the server.
2. Power off the target board.
3. Disconnect the ST-LINK JTAG USB cable.
4. Re-connect the ST-LINK JTAG USB cable.
5. Power on the target board.
6. Check the debug configuration settings, such as the SWD/JTAG interface
7. Start the GDB server, preferably using a different port number.
A good practice is to try the debug of another project to eliminate the possibility of a project-specific problem with
the project configuration or start-up code.
We also recommend to try and debug with another USB cable, ST-LINK or STM32 hardware to exclude hardware
failures as the reason for the debug problems.
It is also advised to try and connect to the target using some other tool from STMicroelectronics, such as the
STM32CubeProgrammer (STM32CubeProg). If STM32CubeProgrammer can connect to the target, try to:
1. Erase the Flash with STM32CubeProgrammer.
2. Program a new program with STM32CubeProgrammer.
3. If the programming is successful, erase the Flash again with STM32CubeProgrammer.
4. Disconnect STM32CubeProgrammer from the target.
5. Try and debug the program using ST-LINK_gdbserver.
0 TARGET_SUCCESS OK.
Port is in use, something is already connected to the
1 TARGET_CONNECT_ERR
board, such as STM32CubeProgrammer.
2 TARGET_DLL_ERR No ST-LINK connected.
3 TARGET_USB_COMM_ERR USB communication error.
4 TARGET_NO_DEVICE ST-LINK is connected but no board is connected
For instance, not using option –d when only SWD pins
5 TARGET_UNKNOWN_MCU_TARGET
are connected to the HW.
6 TARGET_FIRMWARE_OLD Old ST-LINK_firmware.
7 TARGET_RESET_ERR Reset error.
8 TARGET_HELD_UNDER_RESET Reset button on board pressed.
9 TARGET_NOT_HALTED Target could not be halted.
10 TARGET_CMD_ERR Command error.
11 TARGET_APP_RESET_ERR Application reset error.
12 TARGET_VERSION_ERR Version error.
13 TARGET_GET_STATUS_ERR Get status error.
14 TARGET_FORCE_HALT_ERR Force halt error.
Several boards are connected. Need to specify –
16 TARGET_STLINK_SELECT_REQ
i <ST-LINK S/N>.
The ST-LINK serial number cannot be found when using
17 TARGET_STLINK_SERIAL_NOT_FOUND
the –i option.
###############################################################
#### Sample Configuration File
###############################################################
###############################################################
# -e : Enables persistent mode
###############################################################
-e
###############################################################
# -f <Log-File> : Name of log file.
###############################################################
-f debug_log_v0.txt
###############################################################
# -l <Log-Level> : Logging level between 0 & 31
###############################################################
-l 31
###############################################################
# -p <Port-Number> : TCP-Listen Port-Number.
###############################################################
-p 61234
###############################################################
# -v : Enables verbose mode
###############################################################
-v
###############################################################
# -r <refresh-delay-sec> : Maximum Delay in status refresh
###############################################################
-r 1
###############################################################
# -cp <path> : Path to STM32CubeProgrammer
###############################################################
-cp C:\ST\STM32CubeIDE_1.7.0.21w21\STM32CubeIDE\plugins\
com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.0.0.202105061353\
tools\bin
Revision history
Contents
1 GDB server usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 GDB server start-up options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 GDB server modes of operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Starting the GDB server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Debugging with GDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Launching GDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Connecting to the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Loading the program on the target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.1 Loading program to external memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.2 Memory read/write to external memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Setting watch-points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Running the program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.7 Exiting a debug session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.8 Debugging on the target STM32 board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.9 Monitor commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Appendix A Return/error code information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Appendix B Configuration file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
List of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
List of figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
List of tables
Table 1. ST-LINK GDB server return/error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Table 2. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
List of figures
Figure 1. Overview of a debug setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1