Extend @gba-kit/debug-info for address→symbol maps

[macabeus]

Fourteen self-contained commits taking @gba-kit/debug-info from a GBA-shaped reader to a general ELF32/DWARF one: declaration facts alongside layout, function signatures, the preprocessor macro table, both byte orders, relocatable objects, a .debug_line walk that survives real producer output — and four producer-dialect bug fixes found by adversarial review, TDD-pinned on committed toolchain artifacts. (The motivating consumer is asmlift, which builds an address→symbol map out of an ELF; nothing here is specific to it.) Each commit stands alone, and @gba-kit/debug-info goes 87 → 214 tests.

variableShape — classify a global's declaration shape

Walks a variable DIE's type through typedefs and cv-qualifiers to scalar | pointer | array | struct, with element size/signedness for arrays and tag name/byte size for structs. null doubles as the "is this name declared in the headers?" probe. Layout was already exposed; this answers what kind of thing a name is — a small closed set, where a full DIE→C-type renderer is neither needed nor cheap.

Big-endian ELF/DWARF + RELA-relocated debug sections

Byte order is read from e_ident and threaded through every multi-byte read (Cursor gains a littleEndian flag), so the MSB-first ELF32 images MIPS and PowerPC toolchains emit parse. Separately, PowerPC relocatable objects are RELA-style: string/section offsets in raw .debug_* bytes are zeros with the real values in .rela.<sec> addends (ARM/MIPS REL keeps them in the field), so sectionData applies those addends to a cached copy and DWARF in a raw .o parses identically across both conventions.

Verified against real artifacts: a big-endian MIPS sidecar object (283 variables + 209 structs), a big-endian PPC32 sidecar including struct layouts, and a GameCube main.elf (36,588 symbols).

Declaration facts for members and variables

Layout does not describe a declaration on its own: several declarations produce the same bytes at the same offset, and what separates them lives in the type chain rather than in the offsets. struct() members now carry signed (the member's base-type DW_AT_encoding — offset and size alone do not say whether a byte reads as -1 or as 255), pointer (which separates the 4-byte cases sharing signed: null — pointer vs enum vs nested struct, indistinguishable by offset and size, and not interchangeable since pointers compare as unsigned), and volatile (the vu16 field; MMIO idiom — accesses to the field are observable rather than foldable). variableShape carries volatile / const, collected while resolving the typedef and cv-qualifier chain; for an array DWARF puts the qualifier on the element type, so the element chain feeds the same accumulator. Both ARM test projects declare a volatile struct with a signed char member, a member-level volatile, a pointer member, a volatile scalar and a const table, so every fact is covered in both DWARF dialects; their ELFs and binutils oracles are rebuilt from that source.

Walk .debug_line by its own terminators

unit_length is not a dependable end marker. agbcc (GCC 2.95) sizes a line unit by predicting the encoded length of the statements it is about to emit, and mispredicts: in pokeemerald 28 of 303 units under-count — 18 by one byte, 6 by two, 2 by three, one by four, and event_object_movement.o by 51. A walk that seeks to the declared end therefore resumes mid-statement and reads the next unit's header as line-program bytes. The line program is self-delimiting, so DW_LNE_end_sequence is the authority on where a unit ends; around that, one unreadable unit does not cost the section (unsupported versions and 64-bit DWARF are skipped by their own length, zero-word padding is stepped over, every read in the program loop is bounded), and a sequence that never closes discards its own rows, so recovery cannot invent data.

pokeemerald yields 193,233 rows across all 303 units, consuming the section to its last byte, and agrees with readelf --debug-dump=decodedline on every row readelf decodes. The regression tests build on the committed agbcc DWARF-2 bytes, shortening a unit's unit_length by 1–7 and asserting the decoded rows are unchanged.

Big-endian MIPS + PowerPC test projects, proving cross-endian equivalence

mips-min (mips-linux-gnu-gcc, MIPS o32) and ppc-min (powerpc-linux-gnu-gcc, PowerPC 32) join the two ARM projects, compiling one byte-identical source with -g -O2 -fno-eliminate-unused-debug-types, linked freestanding and never executed. They cover what no little-endian ELF can: DWARF read MSB-first end to end, and bitfields allocated from the most significant end of the storage unit — which the parser normalized as if the low end were universal, reporting every big-endian bitfield at its little-endian position. Ground truth for the fixed numbers is each compiler's own read-modify-write of g_bits.cross. ppc-min also vendors build/main.o — the only artifact shape that exercises the RELA path — whose .debug_info has 59 relocations, every raw field zero.

The same commit adds a cross-endian equivalence block comparing all four projects: the shared declaration set is pinned (anything absent from a project is listed by name, so a shape that quietly stops parsing fails there rather than shrinking the comparison), every project must report the same byte layout and the same declaration facts, and the bitfield shifts must be mirrors — leShift + beShift + bitWidth === size * 8 — not merely different. Checked against deliberately broken parsers one mutation at a time. CI installs the stock Ubuntu cross packages (native, no Docker or qemu) and rebuilds all four projects from scratch, so the committed artifacts stay honest.

What a pointer points AT, an array member's elements, and alias naming

variableShape's pointer arm gains pointee — { structName, size, volatile, const } when the target resolves to a struct or union, null for every other target. structName is deliberately not "the struct tag": it is the name struct() looks a layout up by, and for the typedef struct {…} T; idiom that is T, so struct(shape.pointee.structName) is always a round trip. The struct arm is named by exactly the same rule. The pointee's qualifiers are the ones left of the * and provably cannot leak into the pointer variable's own, right of it — the test projects declare both spellings and assert the volatile lands on a different object in each. struct() members of array type additionally carry elemSize / elemSigned / length, so an indexed read into char name[6] is expressible; each key is omitted when the DWARF does not determine it.

A member's const, and what a pointer member points at

Completing StructMember's declaration set: const?: true alongside volatile?: true (a cv-qualifier moves no field, so nothing about offset or size carries it), and pointeeSize / pointeeSigned on pointer members whose target is a base type (pointer arithmetic scales by the pointee width, so p - 4 through a u16 * and through a void * reach different memory). MemberLocation still omits all of these: a location is where to read, not what may be done there.

Read a compiled function's declared signature

functionSignature(name) returns what a function returns and the type of each parameter, from subprogram DIEs — the same width/signedness/pointer vocabulary a struct member uses. Only DEFINITIONS are indexed, with low_pc as the witness: a function that is still hand-written assembly, or merely declared in a header, has no subprogram DIE at all, so null means "this ELF did not compile it", never "it takes no arguments". Verified against pokeemerald's agbcc-emitted DWARF-2: 15,678 of 15,858 functions, signatures matching the sources exactly.

Read the preprocessor macro table (.debug_macinfo)

A compiler invoked with -g3 records every #define it saw — the only place some facts survive at all: a macro leaves no symbol, no type and no DIE, so a consumer reading an ELF has no other way to learn that a project spells a fixed address gCounter rather than (*(u16 *)0x03001234). Parses the DWARF 2/3 form, whose opcode stream carries its strings inline and is self-contained by construction — the form a macro sidecar graft produces. Verified on two real sidecars: 1,380 definitions (41 address casts) and 1,941 (1 address cast).

Tested on a committed artifact: devkitarm-min vendors build/macinfo.o (its main.c compiled with -gdwarf-2 -g3 -gstrict-dwarf, the exact sidecar recipe), with fixture #defines pinned by name/body/line and readelf agreeing on all 417 defines. Writing the truncation test caught a real bug on the spot: a stream cut mid-string surfaced a corrupted define as a real entry (Cursor.cstr returns partial text when the NUL never arrives). Both string sites now stop at an unterminated string, and the spec pins the prefix property — every returned entry equals the full parse's entry, at any cut.

agbcc-min rebuilt with the fixed agbcc

The agbcc submodule moves to a commit fixing two bugs in agbcc's own DWARF output — the relevant one being the missing .debug_abbrev table terminator, which made every standard tool refuse the section outright. The parser needed no change; the committed artifact is rebuilt 4 bytes larger, with build/oracle.json byte-identical — the evidence that the compiler fix moves no code.

Four producer-dialect fixes, TDD-pinned (producer-quirks.spec.ts)

An adversarial review reproduced four wrong readings of real compiler output; the test projects grew the trigger shapes first (the spec failed 8/11 against them, its 3 passes being negative controls), then the fixes turned it green:

1. DW_FORM_flag decodes as a boolean. DWARF 2/3's flag form is a byte; returning the raw number satisfied no === true test, so every declaration check was inert on those dialects — a forward-declared struct shadowed its own definition link-order-dependently (agbcc-min pins the scenario: FwdPay declared in the first CU, defined in the second), and prototyped was always false on modern-gcc -gdwarf-2 output.
2. functionSignature resolves gcc's abstract/concrete split. At -O1+ a function that is both inlined and emitted becomes an abstract DIE (name, params) plus a concrete DIE (low_pc, abstract_origin); indexing only same-DIE name+low_pc returned null for exactly the small helpers a consumer wants callee signatures for (add/square in mips-min and ppc-min are the committed proof). Each fact is now read from the DIE that carries it, per-parameter origins included.
3. 0xffffffff upper bound = zero-length, not 2³² elements. GCC 2.95 stores the -1 bound in unsigned data4; upper+1 on the raw u32 claimed 4-GiB shapes. This was live in shipped data — two pokeemerald tables claimed 4 and 16 GiB — and both now read length: null against the real ELF, while initializer-sized arrays keep their true bounds (pinned).
4. A declaration's [1] array reports length: null. agbcc emits upper_bound 0 for an unsized extern array, byte-identical to a real [1]; the variable's own DW_AT_declaration disambiguates (agbcc-min's g_ext_table is defined only in crt0.s — the ldscript/asm-placed-table idiom). A defined [1] keeps its length.

Real-world validation of the four: klonoa's gSineTable drops its confident wrong length: 1 with all 222 signatures intact, and re-vendoring asmlift's benchmark maps changed exactly the predicted entries (kleod −26 phantom sizes; pokeemerald +6,701 real sizes, since prefer-definition finally works on DWARF-2) with zero rows moving across the 675-row benchmark.

---

No API is removed or changed in shape — every addition is a new field or a new method, so existing consumers are unaffected. The changeset records it all as one minor bump; this is the 0.4.0 that unblocks asmlift's vendored symbol maps.