dist/tools/PyCortexMDebug: Integrate GDB extension into RIOT by maribu · Pull Request #21863 · RIOT-OS/RIOT

maribu · 2025-11-09T20:40:24Z

Contribution description

When running

 make USE_PYCORTEXMDEBUG=1 debug

RIOT will now fetch PyCortexMDebug and instruct GDB to load that extension on start. If additionally RIOT provides SVD_VENDOR and SVD_MODEL to identify the SVD file to load, an svd_load $(SVD_VENDOR) $(SVD_CLIENT) is also passed to GDB.

For nRF52 and STM32F7 based boards, SVD_VENDOR and SVD_CLIENT are already provided.

Testing procedure

Prepare the SVD database with wget -O ~/.cache/cmdebug/cmsis-svd-data.zip https://github.com/cmsis-svd/cmsis-svd-data/archive/refs/heads/main.zip. (This is documented in the README.md in dist/tools/PyCortexMDebug and can be automated in a follow up.)
Flash a valid image on an STM32F7 board using OpenOCD, e.g. a NUCLEO-F767ZI, using make BOARD=nucleo-f767zi -C examples/basic/default flash
Run the debugger using make RIOT_USE_PYCORTEXMDEBUG=1 BOARD=nucleo-f767zi -C examples/basic/default debug
Confirm that you get something like Loading SVD file STMicro/STM32F7x7...
Confirm that the svd command works, e.g. try svd SYSCFG EXTICR1
Do the same with an nRF52 board using JLink, e.g. the nrf52840dk defaults to using J-Link when installed

Expected results:

The svd_load command is provided in GDB and works out of the box for both J-Link and OpenOCD
The SVD vendor and model are provided for STM32F7 and nRF52 based boards, so that one can skip the svd_load <SVD_VENDOR> <SVD_MODEL> command and directly inspect memory with svd

Issues/PRs references

None

riot-ci · 2025-11-09T20:52:39Z

Murdock results

✔️ PASSED

dde6e6e cpu/stm32f7: Provide SVD_VENDOR and SVD_MODEL

Success	Failures	Total	Runtime
10931	0	10931	11m:51s

Artifacts

Documentation preview

AnnsAnns

Neat stuff 😄

makefiles/tools/dbg_common.inc.mk

dist/tools/PyCortexMDebug/README.md

AnnsAnns · 2025-11-10T16:18:57Z

It's still failing a static test, I'll test it in the meantime though :)

AnnsAnns · 2025-11-10T16:30:29Z

Normal building/flashing/debugging works fine. When I use USE_PYCORTEXMDEBUG based on the instructions it fails with:

/home/ann/projects/riot/base/dist/tools/jlink/jlink.sh flash /home/ann/projects/riot/base/examples/basic/default/bin/nrf52840dk/default.elf
### Flashing Target ###
### Flashing elf file ###
SEGGER J-Link Commander V8.84 (Compiled Nov  5 2025 18:42:50)
DLL version V8.84, compiled Nov  5 2025 18:41:46

J-Link Commander will now exit on Error

J-Link Command File read successfully.
Processing script file...
J-Link>loadfile /home/ann/projects/riot/base/examples/basic/default/bin/nrf52840dk/default.elf
J-Link connection not established yet but required for command.
Connecting to J-Link via USB...O.K.
Firmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Jul  8 2025 10:14:41
Hardware version: V1.00
J-Link uptime (since boot): 0d 00h 01m 30s
S/N: 683141474
License(s): RDI, FlashBP, FlashDL, JFlash, GDB
USB speed mode: High speed (480 MBit/s)
VTref=3.300V
Target connection not established yet but required for command.
Device "NRF52840_XXAA" selected.


Connecting to target via SWD
InitTarget() start
InitTarget() end - Took 2.18ms
Found SW-DP with ID 0x2BA01477
DPIDR: 0x2BA01477
CoreSight SoC-400 or earlier
Scanning AP map to find all available APs
AP[2]: Stopped AP scan as end of AP map has been reached
AP[0]: AHB-AP (IDR: 0x24770011, ADDR: 0x00000000)
AP[1]: JTAG-AP (IDR: 0x02880000, ADDR: 0x01000000)
Iterating through AP map to find AHB-AP to use
AP[0]: Core found
AP[0]: AHB-AP ROM base: 0xE00FF000
CPUID register: 0x410FC241. Implementer code: 0x41 (ARM)
Found Cortex-M4 r0p1, Little endian.
FPUnit: 6 code (BP) slots and 2 literal slots
CoreSight components:
ROMTbl[0] @ E00FF000
[0][0]: E000E000 CID B105E00D PID 000BB00C SCS-M7
[0][1]: E0001000 CID B105E00D PID 003BB002 DWT
[0][2]: E0002000 CID B105E00D PID 002BB003 FPB
[0][3]: E0000000 CID B105E00D PID 003BB001 ITM
[0][4]: E0040000 CID B105900D PID 000BB9A1 TPIU
[0][5]: E0041000 CID B105900D PID 000BB925 ETM
Memory zones:
  Zone: "Default" Description: Default access mode
Cortex-M4 identified.
'loadfile': Performing implicit reset & halt of MCU.
Reset type: NORMAL (https://kb.segger.com/J-Link_Reset_Strategies)
Reset: Halt core after reset via DEMCR.VC_CORERESET.
Reset: Reset device via AIRCR.SYSRESETREQ.
Downloading file [/home/ann/projects/riot/base/examples/basic/default/bin/nrf52840dk/default.elf]...
Comparing flash   [100%] Done.
J-Link: Flash download: Bank 0 @ 0x00000000: Skipped. Contents already match
O.K.
J-Link>Write4 0x10001200 00000012 00000012
Writing 00000012 -> 10001200
Writing 00000012 -> 10001204
J-Link>r
Reset delay: 0 ms
J-Link: Flash download: Bank 0 @ 0x00000000: Skipped. Contents already match
Reset type: NORMAL (https://kb.segger.com/J-Link_Reset_Strategies)
Reset: Halt core after reset via DEMCR.VC_CORERESET.
Reset: Reset device via AIRCR.SYSRESETREQ.
J-Link>g
Memory map 'after startup completion point' is active
J-Link>exit

Script processing completed.

make: *** No rule to make target '/home/ann/projects/riot/base/dist/tools/PyCortexMDebug/checkout', needed by 'debug'.  Stop.

maribu · 2025-11-10T16:38:09Z

Indeed, should be fixed now

AnnsAnns · 2025-11-10T16:43:31Z

Squash 👍

AnnsAnns · 2025-11-10T16:44:43Z

(Also wow that is such a neat feature)

dist/tools/PyCortexMDebug/README.md

makefiles/tools/jlink.inc.mk

makefiles/tools/openocd.inc.mk

cpu/stm32/stm32_info.mk

- Do not provide defaults for `${DBG}`, `${TUI}`, `${GDB_PORT}`, `${TELNET_PORT}` with special shell functions, but use canonical syntax for that - Add `${DBG_EXTRA_FLAGS}` and pass them to GDB, as we do in OpenOCD - Run `${DBG}` with `sh -c "..."` just like done in `openocd.sh` to allow passing flags to GDB in the same way independent of whether JLink or OpenOCD is used.

When running make RIOT_USE_PYCORTEXMDEBUG=1 debug RIOT will now fetch PyCortexMDebug and instruct GDB to load that extension on start. If additionally RIOT provides `SVD_VENDOR` and `SVD_MODEL` to identify the SVD file to load, an `svd_load $(SVD_VENDOR) $(SVD_CLIENT)` is also passed to GDB. Co-authored-by: crasbe <[email protected]> Co-authored-by: Ann🐸 <[email protected]>

With this, running `make RIOT_USE_PYCORTEXMDEBUG=1 debug` for any nRF52 based boards will directly load the correct SVD file.

With this, running `make RIOT_USE_PYCORTEXMDEBUG=1 debug` for any STM32F7 based boards will directly load the correct SVD file. Co-authored-by: crasbe <[email protected]>

AnnsAnns

Thank you for the continued review over the night 😄

Here is my approval, though crasbe should probably also approve

crasbe · 2025-11-11T10:26:23Z

Here is my approval, though crasbe should probably also approve

Oh, you actually tested this, your approval is enough :)

AnnsAnns · 2025-11-11T10:45:30Z

Here is my approval, though crasbe should probably also approve

Oh, you actually tested this, your approval is enough :)

Yeah but you also reviewed it, didn't want to overrule your review ;P

maribu · 2025-11-11T14:09:19Z

Thx ❤️

maribu requested review from aabadie and vincent-d as code owners November 9, 2025 20:40

maribu added the Type: enhancement The issue suggests enhanceable parts / The PR enhances parts of the codebase / documentation label Nov 9, 2025

maribu requested a review from jia200x as a code owner November 9, 2025 20:40

maribu added CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR Area: tools Area: Supplementary tools labels Nov 9, 2025

github-actions bot added Platform: ARM Platform: This PR/issue effects ARM-based platforms Area: doc Area: Documentation Area: build system Area: Build system Area: cpu Area: CPU/MCU ports labels Nov 9, 2025

maribu changed the title ~~dist/tools/jlink: refactor script~~ dist/tools/PyCortexMDebug: Integrate GDB extension into RIOT Nov 10, 2025

AnnsAnns requested changes Nov 10, 2025

View reviewed changes

makefiles/tools/dbg_common.inc.mk Outdated Show resolved Hide resolved

makefiles/tools/dbg_common.inc.mk Outdated Show resolved Hide resolved

dist/tools/PyCortexMDebug/README.md Show resolved Hide resolved

crasbe reviewed Nov 10, 2025

View reviewed changes

maribu and others added 4 commits November 10, 2025 19:56

cpu/nrf52: Provide SVD_VENDOR and SVD_MODEL

1756601

With this, running `make RIOT_USE_PYCORTEXMDEBUG=1 debug` for any nRF52 based boards will directly load the correct SVD file.

cpu/stm32f7: Provide SVD_VENDOR and SVD_MODEL

dde6e6e

With this, running `make RIOT_USE_PYCORTEXMDEBUG=1 debug` for any STM32F7 based boards will directly load the correct SVD file. Co-authored-by: crasbe <[email protected]>

maribu force-pushed the dist/tools/PyCortexMDebug branch from 811c09e to dde6e6e Compare November 10, 2025 18:58

maribu enabled auto-merge November 10, 2025 21:28

AnnsAnns approved these changes Nov 11, 2025

View reviewed changes

maribu added this pull request to the merge queue Nov 11, 2025

AnnsAnns removed this pull request from the merge queue due to a manual request Nov 11, 2025

crasbe added this pull request to the merge queue Nov 11, 2025

Merged via the queue into RIOT-OS:master with commit cb427b0 Nov 11, 2025
26 checks passed

maribu deleted the dist/tools/PyCortexMDebug branch November 11, 2025 14:09

maribu mentioned this pull request Nov 11, 2025

cpu/{sam0_common,stm32}: Provide SVD_VENDOR and SVD_MODEL #21872

Merged

13 tasks

leandrolanzieri added this to the Release 2026.01 milestone Jan 13, 2026

Conversation

maribu commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contribution description

Testing procedure

Issues/PRs references

Uh oh!

riot-ci commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

AnnsAnns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AnnsAnns commented Nov 10, 2025

Uh oh!

AnnsAnns commented Nov 10, 2025

Uh oh!

maribu commented Nov 10, 2025

Uh oh!

AnnsAnns commented Nov 10, 2025

Uh oh!

AnnsAnns commented Nov 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AnnsAnns left a comment

Choose a reason for hiding this comment

Uh oh!

crasbe commented Nov 11, 2025

Uh oh!

AnnsAnns commented Nov 11, 2025

Uh oh!

Uh oh!

maribu commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

maribu commented Nov 9, 2025 •

edited

Loading

riot-ci commented Nov 9, 2025 •

edited

Loading