Browse Source
Add the ST-Link GDB server (part of the STM32CubeCLT) as west runner. The STM32CubeCLT is an all-in-one multi-OS command-line toolset, which is part of the STM32Cube ecosystem, and notably includes a GDB server for debugging using ST-Link probes. This runner supports the "attach", "debug" and "debugserver" commands. Documentation: https://www.st.com/en/development-tools/stm32cubeclt.html Signed-off-by: Mathieu Choplain <mathieu.choplain@st.com>pull/91613/merge
Mathieu Choplain
3 weeks ago
committed by
Fabio Baltieri
6 changed files with 265 additions and 26 deletions
@ -0,0 +1,4 @@
@@ -0,0 +1,4 @@
|
||||
# SPDX-License-Identifier: Apache-2.0 |
||||
|
||||
board_set_debugger_ifnset(stlink_gdbserver) |
||||
board_finalize_runner_args(stlink_gdbserver) |
||||
@ -0,0 +1,188 @@
@@ -0,0 +1,188 @@
|
||||
# Copyright (c) 2025 STMicroelectronics |
||||
# |
||||
# SPDX-License-Identifier: Apache-2.0 |
||||
|
||||
""" |
||||
Runner for debugging applications using the ST-LINK GDB server |
||||
from STMicroelectronics, provided as part of the STM32CubeCLT. |
||||
""" |
||||
|
||||
import argparse |
||||
import platform |
||||
import re |
||||
import shutil |
||||
from pathlib import Path |
||||
|
||||
from runners.core import MissingProgram, RunnerCaps, RunnerConfig, ZephyrBinaryRunner |
||||
|
||||
STLINK_GDB_SERVER_DEFAULT_PORT = 61234 |
||||
|
||||
|
||||
class STLinkGDBServerRunner(ZephyrBinaryRunner): |
||||
@classmethod |
||||
def _get_stm32cubeclt_paths(cls) -> tuple[Path, Path]: |
||||
""" |
||||
Returns a tuple of two elements of class pathlib.Path: |
||||
[0]: path to the ST-LINK_gdbserver executable |
||||
[1]: path to the "STM32CubeProgrammer/bin" folder |
||||
""" |
||||
|
||||
def find_highest_clt_version(tools_folder: Path) -> Path | None: |
||||
if not tools_folder.is_dir(): |
||||
return None |
||||
|
||||
# List all CubeCLT installations present in tools folder |
||||
CUBECLT_FLDR_RE = re.compile(r"stm32cubeclt_([1-9]).(\d+).(\d+)", re.IGNORECASE) |
||||
installations: list[tuple[int, Path]] = [] |
||||
for f in tools_folder.iterdir(): |
||||
m = CUBECLT_FLDR_RE.match(f.name) |
||||
if m is not None: |
||||
# Compute a number that can be easily compared |
||||
# from the STM32CubeCLT version number |
||||
major, minor, revis = int(m[1]), int(m[2]), int(m[3]) |
||||
ver_num = major * 1000000 + minor * 1000 + revis |
||||
installations.append((ver_num, f)) |
||||
|
||||
if len(installations) == 0: |
||||
return None |
||||
|
||||
# Sort candidates and return the path to the most recent version |
||||
most_recent_install = sorted(installations, key=lambda e: e[0], reverse=True)[0] |
||||
return most_recent_install[1] |
||||
|
||||
cur_platform = platform.system() |
||||
|
||||
# Attempt to find via shutil.which() |
||||
if cur_platform in ["Linux", "Windows"]: |
||||
gdbserv = shutil.which("ST-LINK_gdbserver") |
||||
cubeprg = shutil.which("STM32_Programmer_CLI") |
||||
if gdbserv and cubeprg: |
||||
# Return the parent of cubeprg as [1] should be the path |
||||
# to the folder containing STM32_Programmer_CLI, not the |
||||
# path to the executable itself |
||||
return (Path(gdbserv), Path(cubeprg).parent) |
||||
|
||||
# Search in OS-specific paths |
||||
search_path: str |
||||
tool_suffix = "" |
||||
if cur_platform == "Linux": |
||||
search_path = "/opt/st/" |
||||
elif cur_platform == "Windows": |
||||
search_path = "C:\\ST\\" |
||||
tool_suffix = ".exe" |
||||
elif cur_platform == "Darwin": |
||||
search_path = "/opt/ST/" |
||||
else: |
||||
raise RuntimeError("Unsupported OS") |
||||
|
||||
clt = find_highest_clt_version(Path(search_path)) |
||||
if clt is None: |
||||
raise MissingProgram("ST-LINK_gdbserver (from STM32CubeCLT)") |
||||
|
||||
gdbserver_path = clt / "STLink-gdb-server" / "bin" / f"ST-LINK_gdbserver{tool_suffix}" |
||||
cubeprg_bin_path = clt / "STM32CubeProgrammer" / "bin" |
||||
|
||||
return (gdbserver_path, cubeprg_bin_path) |
||||
|
||||
@classmethod |
||||
def name(cls) -> str: |
||||
return "stlink_gdbserver" |
||||
|
||||
@classmethod |
||||
def capabilities(cls) -> RunnerCaps: |
||||
return RunnerCaps(commands={"attach", "debug", "debugserver"}, dev_id=True, extload=True) |
||||
|
||||
@classmethod |
||||
def extload_help(cls) -> str: |
||||
return "External Loader for ST-Link GDB server" |
||||
|
||||
@classmethod |
||||
def do_add_parser(cls, parser: argparse.ArgumentParser): |
||||
# Expose a subset of the ST-LINK GDB server arguments |
||||
parser.add_argument( |
||||
"--swd", action='store_true', default=True, help="Enable SWD debug mode" |
||||
) |
||||
parser.add_argument("--apid", type=int, default=0, help="Target DAP ID") |
||||
parser.add_argument( |
||||
"--port-number", |
||||
type=int, |
||||
default=STLINK_GDB_SERVER_DEFAULT_PORT, |
||||
help="Port number for GDB client", |
||||
) |
||||
|
||||
@classmethod |
||||
def do_create(cls, cfg: RunnerConfig, args: argparse.Namespace) -> "STLinkGDBServerRunner": |
||||
return STLinkGDBServerRunner( |
||||
cfg, args.swd, args.apid, args.dev_id, args.port_number, args.extload |
||||
) |
||||
|
||||
def __init__( |
||||
self, |
||||
cfg: RunnerConfig, |
||||
swd: bool, |
||||
ap_id: int | None, |
||||
stlink_serial: str | None, |
||||
gdb_port: int, |
||||
external_loader: str | None, |
||||
): |
||||
super().__init__(cfg) |
||||
self.ensure_output('elf') |
||||
|
||||
self._swd = swd |
||||
self._gdb_port = gdb_port |
||||
self._stlink_serial = stlink_serial |
||||
self._ap_id = ap_id |
||||
self._external_loader = external_loader |
||||
|
||||
def do_run(self, command: str, **kwargs): |
||||
if command in ["attach", "debug", "debugserver"]: |
||||
self.do_attach_debug_debugserver(command) |
||||
else: |
||||
raise ValueError(f"{command} not supported") |
||||
|
||||
def do_attach_debug_debugserver(self, command: str): |
||||
# self.ensure_output('elf') is called in constructor |
||||
# and validated that self.cfg.elf_file is non-null. |
||||
# This assertion is required for the test framework, |
||||
# which doesn't have this insight - it should never |
||||
# trigger in real-world scenarios. |
||||
assert self.cfg.elf_file is not None |
||||
elf_path = Path(self.cfg.elf_file).as_posix() |
||||
|
||||
gdb_args = ["-ex", f"target remote :{self._gdb_port}", elf_path] |
||||
|
||||
(gdbserver_path, cubeprg_path) = STLinkGDBServerRunner._get_stm32cubeclt_paths() |
||||
gdbserver_cmd = [gdbserver_path.as_posix()] |
||||
gdbserver_cmd += ["--stm32cubeprogrammer-path", str(cubeprg_path.absolute())] |
||||
gdbserver_cmd += ["--port-number", str(self._gdb_port)] |
||||
gdbserver_cmd += ["--apid", str(self._ap_id)] |
||||
gdbserver_cmd += ["--halt"] |
||||
|
||||
if self._swd: |
||||
gdbserver_cmd.append("--swd") |
||||
|
||||
if command == "attach": |
||||
gdbserver_cmd += ["--attach"] |
||||
else: # debug/debugserver |
||||
gdbserver_cmd += ["--initialize-reset"] |
||||
gdb_args += ["-ex", f"load {elf_path}"] |
||||
|
||||
if self._stlink_serial: |
||||
gdbserver_cmd += ["--serial-number", self._stlink_serial] |
||||
|
||||
if self._external_loader: |
||||
extldr_path = cubeprg_path / "ExternalLoader" / self._external_loader |
||||
if not extldr_path.exists(): |
||||
raise RuntimeError(f"External loader {self._external_loader} does not exist") |
||||
gdbserver_cmd += ["--extload", str(extldr_path)] |
||||
|
||||
self.require(gdbserver_cmd[0]) |
||||
|
||||
if command == "debugserver": |
||||
self.check_call(gdbserver_cmd) |
||||
elif self.cfg.gdb is None: # attach/debug |
||||
raise RuntimeError("GDB is required for attach/debug") |
||||
else: # attach/debug |
||||
gdb_cmd = [self.cfg.gdb] + gdb_args |
||||
self.require(gdb_cmd[0]) |
||||
self.run_server_and_client(gdbserver_cmd, gdb_cmd) |
||||
Loading…
Reference in new issue