Skip to content

@gba-kit/debug-info: add support for DWARF .debug_info#4

Merged
macabeus merged 7 commits into
mainfrom
get-dwarf
Jun 29, 2026
Merged

@gba-kit/debug-info: add support for DWARF .debug_info#4
macabeus merged 7 commits into
mainfrom
get-dwarf

Conversation

@macabeus

@macabeus macabeus commented Jun 28, 2026

Copy link
Copy Markdown
Owner

What

Adds DWARF type information to @gba-kit/debug-info and surfaces it in the scripting engine, so scripts and tests can read struct fields by name instead of hand-maintained addresses, offsets, and masks.

@gba-kit/debug-info

  • struct(name) — struct/union layout: members with byte offsets and sizes (descends anonymous unions/structs).
  • structMember(name, path) / variableMember(symbol, path) — resolve a dotted/array field path to its { offset, size, bitOffset?, bitWidth? }, rooted at a type name or at a global (whose type is read from its own DWARF DIE).
  • resolveVariable("symbol.field") — one call to a ResolvedLocation (address from .symtab, layout from DWARF).
  • enumValues(name), hasTypeInfo; exports TypeIndex, ResolvedLocation, MemberLocation.
  • Bitfields report bitOffset/bitWidth; members whose size can't be determined (incomplete type, flexible array) report size: null.
  • symbolToAddress now also resolves absolute (SHN_ABS) STT_NOTYPE ldscript globals (gFoo = 0x...;), while excluding section-relative markers (_end, __bss_start).
  • Parses DWARF 2–5 (agbcc and modern GCC), including multi-CU abbrev tables; malformed input degrades gracefully rather than crashing the load.

Scripting (@gba-kit/gba-emulator, @gba-kit/gba-node)

  • readVariable(path) — read a global or symbol.field by name, sized and bitfield-decoded from the DWARF (the read counterpart to watchSymbol).
  • wait({ memory }) and assert({ memory })address now also accepts a symbol/symbol.field path (read at the field's full width), in addition to a raw numeric address.
await wait({ memory: { address: 'game_sm.state', equals: 5 } });
const score = readVariable('g_game_vars.score');

Tests

Real ELF fixtures from both toolchains (agbcc DWARF-2, devkitARM DWARF-5) assert struct/enum/bitfield layouts, nested + anonymous-union member paths, multi-CU resolution, flexible arrays, and ldscript-symbol in/exclusion.

@macabeus macabeus self-assigned this Jun 28, 2026
@macabeus macabeus changed the title debug-info: add support for struct debug-info: add support for struct and global variables Jun 28, 2026
@macabeus macabeus changed the title debug-info: add support for struct and global variables @gba-kit/debug-info: add support for DWARF .debug_info Jun 28, 2026
@macabeus macabeus changed the title @gba-kit/debug-info: add support for DWARF .debug_info @gba-kit/debug-info: add support for DWARF .debug_info Jun 28, 2026
@macabeus
macabeus marked this pull request as ready for review June 29, 2026 00:01
@macabeus
macabeus merged commit bf00bbd into main Jun 29, 2026
2 checks passed
@macabeus
macabeus deleted the get-dwarf branch June 29, 2026 00:01
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.

1 participant