stack-layout

name	stack-layout
description	Diff stack-frame layouts between target and base for a function. Labels base-side slots with source variable names from a MSVC /Z7 CodeView recompile. Identifies SWAPPED pairs (decl-reorder candidates), SHIFTED slots, DIFFER (different variables in same slot), and TGT_ONLY / BASE_ONLY (extra/missing locals). Filters out callee-save slots.
argument-hint	<symbol_name> [-u <unit>]
allowed-tools	Bash(python3 scripts/analysis/stack_layout.py *), Bash(python3 scripts/analysis/codeview_locals.py *), Bash(python3 scripts/analysis/diff_inspect.py *), Read, Grep, Glob

Stack Layout Diff Skill (MSVC X360)

Compare stack-frame layouts between target and our build for a single function. Returns frame size and callee-save counts at the top, then a per-slot diff table with verdicts that point to specific source fixes.

Arguments

$ARGUMENTS — the symbol (MSVC mangled ?Name@Class@@QAEHXZ or demangled Class::Method(args)). Append -u <unit> if ambiguous (e.g. -u default/system/hamobj/HamCharacter).

Steps

1. Run the diff:

   python3 scripts/analysis/stack_layout.py --symbol "$ARGUMENTS" --project-dir .
   

2. Read the prologue summary at the top:

   • Frame Δ and Callee-saved GPR/FPR Δ
   • On MSVC X360, GPRs are 64-bit (std) — 8 bytes per saved GPR.
   • If frame Δ is fully explained by callee-save counts → AT_LIMIT (not source-fixable).
   • Otherwise the structural Δ remainder is the real lever.

3. Read the verdict table. Rows are sorted most-actionable first:

   Verdict	Meaning	Action
   SWAPPED	Two slots' fingerprints exchanged	Reorder the two declarations
   DIFFER	Same offset, different fingerprint	Different variable lives there — decl-reorder
   SHIFTED	Same fingerprint, offset differs by the dominant Δ	One side has an extra local pushing the rest
   TGT_ONLY	Slot exists only on target	Target spills a temp we keep in a register (or vice versa)
   BASE_ONLY	Slot exists only on our build	Extra spill; usually a register-pressure symptom
   MATCH	Hidden by default; pass --show-equal to see

4. Fingerprint columns (kind sz=N L=loads S=stores A=accesses [first..last]):

   • float sz=4 → float
   • float sz=8 → double / paired-single store
   • int sz=4 → int, pointer, bool, or 32-bit member
   • int sz=8 → 64-bit std/ld (frequent on Xenon)
   • addr sz=0 → an addi rN, r1, off taking address-of

5. "base var" column — the source variable name our build allocates at that offset, extracted from a MSVC /Z7 CodeView recompile. Use it to identify exactly which declaration to reorder.

When to Use

• run_objdiff output flagged **Stack:** frame Δ ... | N SWAPPED ...
• Function diff shows many [off:+N] annotations
• Frame sizes don't match between target and our build
• You suspect a declaration reorder is the fix

Output knobs

• --no-names — skip CodeView recompile + name extraction
• --show-equal — include MATCH rows
• --show-callee-save — include prologue/epilogue callee-save slots (hidden by default)
• --json-file <path> — skip objdiff invocation; load diff JSON from cached path

How name extraction works

The tool recompiles the function's source file with /Z7 to embed CodeView records in the .debug$S COFF section, parses S_REGREL32 records, and maps each register-relative variable to a frame-offset → name pair. Cached at /tmp/claude/stack_codeview/<base>.<hash>.cv.obj by source mtime + cflags hash; second runs are ~0.5s.

Frame-register handling: CodeView records reg=2 (= PPC r1) or reg=32 (= PPC r31). MSVC X360 commonly aliases r31 to new r1 via subi r31, r1, FRAMESIZE before stwu, so r31-relative offsets equal r1-relative offsets after frame allocation. The tool accepts both.

Limits:

• Base side only: there's no debug build oracle for the target. TGT_ONLY rows show no name.
• Compiler temps unnamed: /O1 strips many locals into registers — empty "base var" cell ≠ "unknown variable" — it's "no source declaration."
• Same name in nested scopes: deeper scope wins via min-depth merging.

Detection limits

• Callee-save detection handles:
  • bl __savegprlr_NN / bl __savefpr_NN helpers
  • Manual pre-stwu saves: stw r12, -8, r1, std rN, -off, r1, stfd fN, -off, r1
  • Post-stwu stmw rN, off, r1 (rare on X360)
• Unusual prologue shapes may under- or over-count; verify against the asm if the frame summary looks off.

MSVC X360 prologue cheat-sheet

mflr r12                              ; LR -> r12 (not r0 like Wii MWCC!)
bl __savegprlr_NN                     ; r12->-8(r1), r31..rNN std at -16, -24, ...
stfd f31, -0x?, r1                    ; manual FPR save (pre-stwu, NEGATIVE offset)
subi r31, r1, FRAMESIZE               ; optional: r31 = new r1 (frame-ptr alias)
stwu r1, -FRAMESIZE, r1               ; allocate frame
... body code (uses r1 or r31 base) ...
addi r1, r1, FRAMESIZE                ; deallocate
b __restgprlr_NN                      ; restore + return

After stwu, the saved-register slots end up at frame_size - 8 (LR) down to frame_size - 8 - 8*(saved_count-1).

Tips

• After a declaration reorder, re-run to confirm SWAPPED rows resolve.
• Dominant body-offset shift is reported separately from frame Δ — the dominant shift is what SHIFTED rows are normalized against.
• If verdicts are all DIFFER with no clean SHIFT/SWAP, the function is mid-reflow; try /compare-asm or run_diff_inspect mode=diagnose.