Skip to content

[debugger] Add physical memory breakpoint types#123

Merged
drhelius merged 20 commits into
drhelius:mainfrom
gagnonpl:breakpoints-improvements
May 18, 2026
Merged

[debugger] Add physical memory breakpoint types#123
drhelius merged 20 commits into
drhelius:mainfrom
gagnonpl:breakpoints-improvements

Conversation

@gagnonpl

Copy link
Copy Markdown
Contributor

Hi again. This one is a tad bigger than the other two. I've been working on some improvements to the breakpoints system to help my rom hacking endeavors. Hope you like it.

Motivation

The way read/write RAM breakpoints works atm is that you can set a breakpoint for these:

  • ROM/RAM
  • VRAM
  • Palette RAM
  • HuC6270 Reg
  • HuC6260 Reg

In theory you can make a read/write breakpoint for any of WRAM/ROM/CD RAM/Card RAM already, by using the ROM/RAM type and setting a BP at the cpu address pointing at the correct location in the MPR window with the right mapped bank. But there are a couple limitations:

  1. When inspecting memory in the memory editor, the physical WRAM/ROM/CD/Card RAM offsets are listed. If one wants to set a breakpoint, they need to first convert the offset to a CPU visible address using the MPR that has the bank (hopefully) mapped where the byte of interest is located.
  2. If a BP is set to a ROM/RAM address, but the game maps a different bank than the bank of interest to the MPR corresponding to that address, it will create false positives.
  3. If one is interested in a specific physical RAM byte, but isn't sure to which MPR the game will map the bank where the byte is located, one has to set breakpoints to all possible MPRs the game may use. That also gives rise to false positives.
    Physical ROM/RAM BPs solve these.

New features

  • Added physical breakpoint types:

    • read/write: WRAM, Zero Page, BRAM
    • read/write/execute: Card RAM, CD RAM
    • read/execute: ROM
  • Physical breakpoints resolve CPU address + MPR bank to backing ROM/RAM offsets, so they follow the actual ROM/RAM location regardless of which MPR maps it.

  • Widened breakpoint addresses from u16 to u32, for Card RAM and ROM offsets.

  • Support 384KB/512KB/768KB ROMs and SF2 with special mappers

  • Added variable-width hex parser for addresses/ranges, e.g. 50, 1000, 50-1FFFF.

  • Added per-breakpoint-type address validation.

  • Added cached read/write breakpoint flags to avoid physical RAM breakpoint overhead when none are active.

  • Adding an existing breakpoint now merges R/W/X flags instead of silently doing nothing.

  • Breakpoint list now has clickable R/W/X toggles.

  • Add/Toggle breakpoint on address or range from memory editor by clicking "Toggle Breakpoint" in context menu after selecting byte or range of bytes.

  • GUI labels and address display updated for new breakpoint types and longer Card RAM addresses.

  • Added up/down arrows to re-order the breakpoints in the list.

  • Renamed ROM/RAM breakpoint type to CPU_ADDRESS. This is to avoid confusion with other ROM or RAM breakpoint types. Existing CPU-visible address behavior is preserved.

  • Changed Save/Load Debug Settings to handle the larger addresses. Bumped magic number to maintain compatibility with old .ggdebug files.

  • Changed media load/reset behavior to preserve the breakpoints list.

  • MCP/debug adapter breakpoint type names updated for new memory areas.

Possible future improvements

  • Conditional breakpoints
  • Add BIOS ROM breakpoints for CD-ROM games? -> would require exposing system card in ROM tab of memory editor
  • Error popup with reason why BP couldn't be added if address validation fails?
breakpoints-pr

@drhelius

Copy link
Copy Markdown
Owner

Woah! It looks nice but it's too much to digest.

I see things that I'd like to correct and you are also tapping into the hot path so I'll need to review it carefully

@gagnonpl

Copy link
Copy Markdown
Contributor Author

Yeah sorry about the size. Features kept creeping up on me but I think they all fit together nicely.

About the hot path, yes I tried to be very careful about making sure everything is minimal and INLINE. I check some flags to short-circuit address conversion etc. when there are no breakpoints of a specific type.

@gagnonpl gagnonpl force-pushed the breakpoints-improvements branch from c7a14eb to 9e118ab Compare May 16, 2026 14:16
@drhelius

Copy link
Copy Markdown
Owner

Please don't force push, I can't identify your changes this way.

If you need to add modifications I rather prefer more commits and squash them once I have reviewed all the code.

Thanks!

@drhelius drhelius merged commit 7c9a5a7 into drhelius:main May 18, 2026
19 checks passed
@drhelius

Copy link
Copy Markdown
Owner

Reworked some parts to keep with style and make sure performance impact is minimal.
Thanks for contributing.

gagnonpl added a commit to gagnonpl/Geargrafx that referenced this pull request May 18, 2026
gagnonpl added a commit to gagnonpl/Geargrafx that referenced this pull request May 18, 2026
gagnonpl added a commit to gagnonpl/Geargrafx that referenced this pull request May 18, 2026
gagnonpl added a commit to gagnonpl/Geargrafx that referenced this pull request May 18, 2026
don't clear breakpoints list on rom load/reload
support GGDEBUG2 debug settings files
add up/down buttons to re-order breakpoints list
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants