st-util

Run GDB server on port 4500

$ st-util [[-p|--listen_port]] [4500]

$ target extended-remote [localhost]:[4500]

$ load [firmware.elf]

st-util [options]

-v, --version
    Prints the st-util version information and exits.

-h, --help
    Displays a help message with available options and exits.

-p, --port
    Specifies the TCP port for the GDB server to listen on. The default port is 4242.

-s, --serial
    Selects a specific ST-Link device by its unique serial number. Useful when multiple ST-Link probes are connected.

-n, --no-reset
    Prevents the target microcontroller from being reset before connecting to it.

-1, --freq
    Sets the ST-Link clock frequency in kilohertz for communication with the target.

-m, --multi
    Enables support for multiple GDB clients to connect simultaneously to the st-util server.

-a, --allow-probe
    Allows GDB clients to specify a probe ID. (Typically for advanced or specific ST-Link firmware features).

-r, --reset
    Resets the target microcontroller after establishing the connection. This is often the default behavior.

-d, --debug
    Sets the debug verbosity level of st-util. Levels range from 0 (none) to 5 (error), with 3 (info) being the default.

-N, --no-stlink-reset
    Prevents the ST-Link device itself from being reset at startup.

-P, --persistent
    Keeps the st-util GDB server running even after the GDB client disconnects.

-e, --exit-on-disconnect
    Causes st-util to exit automatically when the connected GDB client disconnects.

-f, --flash-size
    Manually specifies the flash memory size of the target microcontroller in KBytes. Useful for unrecognized chips.

-b, --sram-size
    Manually specifies the SRAM (RAM) size of the target microcontroller in KBytes. Useful for unrecognized chips.

-R, --ram-offset
    Manually specifies the starting memory address (offset) of the SRAM on the target.

st-util is a crucial command-line utility from the stlink open-source project, designed to facilitate debugging and programming of STMicroelectronics STM32 microcontrollers using ST-Link compatible debug probes. It primarily functions as a GDB server, creating a bridge between the GNU Debugger (GDB) and the target embedded device. When launched, st-util typically listens on a specified TCP port (defaulting to 4242) for incoming GDB connections. Developers can then connect their GDB client to this port, enabling a comprehensive range of debugging operations such as setting breakpoints, stepping through code execution, examining memory contents, and programming (flashing) firmware onto the microcontroller's flash memory. This utility significantly streamlines the embedded development workflow by offering a robust and efficient debugging interface, making it an indispensable tool for anyone working with the popular STM32 family of microcontrollers in a Linux environment.

Requires libusb for communication with the ST-Link device.
Users may need to configure udev rules to grant appropriate permissions for accessing the ST-Link without root privileges.
Compatibility can vary across different ST-Link firmware versions and specific STM32 microcontroller series.
The default GDB server port 4242 might conflict with other services on the host system.

Once st-util is running, establish a debugging session from GDB using the command:
target extended-remote localhost:<port_number> (replacing <port_number> with the actual port, e.g., 4242).

To allow non-root users to access the ST-Link USB device, it's often necessary to set up udev rules. Consult your distribution's documentation or the stlink project's GitHub page for specific instructions.

If multiple ST-Link debug probes are connected to your system, use the --serial <serial_number> option to specify which particular device st-util should connect to for the debugging session.

st-util emerged as a core component of the stlink open-source project. This initiative was born out of the need for Linux-compatible tools to interact with ST-Link debug probes, providing an essential alternative to the proprietary, often Windows-exclusive, software provided by STMicroelectronics. Driven by the collaborative efforts of the embedded systems community, the stlink project, and consequently st-util, aimed to democratize access to STM32 development on open-source operating systems. Over time, st-util has matured into a widely adopted and stable tool, becoming a standard fixture in many Linux-based embedded development environments, underpinning the debug and programming workflows for countless STM32 projects worldwide.

arm-none-eabi-gdb(1), st-flash(1), st-info(1), openocd(1)