mjc · ixtli · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/.ace-aarch64-unwind-spec.md b/.ace-aarch64-unwind-spec.md
@@ -0,0 +1,84 @@
+# Spec: aarch64 DWARF user unwind support
+
+Priority directive from the user (2026-06-11): the dwarf call-graph path is the
+parity priority — fp call graphs require frame-pointer builds of the whole world.
+The local oracle (Docker on Apple Silicon) records arm64 perf.data, so aarch64
+support is the critical path for oracle-driven dwarf work. Validate against
+`target/oracle/dwarf.*` (re-record with `scripts/perf-oracle` after changes; the
+recorded inputs are stable otherwise).
+
+## Current state
+
+- `src/perfdata/unwind.rs`: `PerfX86_64Regs { ip, sp, bp, registers: [u64;16] }`,
+  `FramehopUnwinder { unwinder: UnwinderX86_64<ModuleBytes>, cache: CacheX86_64 }`,
+  `unwind_x86_64_frame_pointer_stack_like_elfutils` (x86 ebl fallback),
+  `PerfUserMemoryReader` (arch-neutral), module loading via
+  `ExplicitModuleSectionInfo` (arch-neutral).
+- `src/perfdata/fold.rs` threads `&PerfX86_64Regs` through ~21 sites; entry point is
+  `append_perf_user_unwind_frames` →
+  `PerfX86_64Regs::from_perf_masked_values(event.layout.sample_regs_user, &regs.values)`.
+  `perf_user_reg_value(mask, values, 8)` hardcodes PERF_REG_X86_IP=8 in
+  `parse_sample_for_summary` too.
+- x86-only logic to gate by arch: `is_syscall_return_state` (rcx==ip && r11!=0),
+  `libdw_arch_fallback_after_empty_object_unwind` guard `regs.bp >= regs.sp`.
+
+## Register numbering
+
+- x86_64 (PERF_REG_X86_*): BP=6, SP=7, IP=8 (already implemented).
+- aarch64 (PERF_REG_ARM64_*): x0..x28 = 0..28, X29/FP = 29, LR/x30 = 30, SP = 31,
+  PC = 32. perf records `--call-graph dwarf` on arm64 with mask covering x0-x30,
+  sp, pc (mask 0x1ffffffff).
+
+## Arch detection
+
+perf.data does not store arch per attr; perf uses the header HEADER_ARCH feature
+(string from uname, "aarch64" / "x86_64"). Header feature parsing machinery exists
+(see `header_build_ids_by_filename_from_file` / `src/perfdata/build_id.rs`,
+`header.rs`). Add `header_arch_from_file` reading HEADER_ARCH (feature bit 5;
+perf string format: u32 len + bytes, see perf util/header.c write_arch/read).
-`header.rs`). Add `header_arch_from_file` reading HEADER_ARCH (feature bit 5;
-perf string format: u32 len + bytes, see perf util/header.c write_arch/read).
+`header.rs`). Add `header_arch_from_file` reading HEADER_ARCH (feature bit 6;
+perf string format: u32 len + bytes, see perf util/header.c write_arch/read).
-`header.rs`). Add `header_arch_from_file` reading HEADER_ARCH (feature bit 5;
-perf string format: u32 len + bytes, see perf util/header.c write_arch/read).
+`header.rs`). Add `header_arch_from_file` reading HEADER_ARCH (feature bit 6;
+perf string format: u32 len + bytes, see perf util/header.c write_arch/read).
+Default to x86_64 when absent. Plumb into `FoldAccumulator`/sink construction so
+`append_perf_user_unwind_frames` can decode regs per arch.
+
+## Design (project is unreleased — rename freely)
+
+1. Replace `PerfX86_64Regs` with arch-neutral `PerfUserRegs { arch: PerfArch,
+   ip: u64, sp: u64, fp: u64, lr: Option<u64>, values: ... }` with
+   `from_perf_masked_values(arch, mask, values)`; keep per-arch accessors used by
+   the x86 syscall-return check (rcx = values[?]; preserve current behavior via
+   the existing masked-value lookup). Alternatively an enum — pick whichever keeps
+   the 21 fold.rs sites simplest; most only use ip/sp/bp.
+2. `FramehopUnwinder` becomes an enum or holds per-arch unwinder+cache
+   (`framehop::aarch64::{UnwinderAarch64, CacheAarch64, UnwindRegsAarch64}`).
+   Module registration (`framehop::Module::new` + ExplicitModuleSectionInfo) is
+   shared; instantiate by arch at accumulator/PidUnwindState creation (arch comes
+   from the file header, one arch per perf.data).
+   Note framehop aarch64 `UnwindRegsAarch64::new(lr, sp, fp)`; `iter_frames` seeds
+   with pc. framehop strips PAC bits itself.
+3. aarch64 ebl_unwind fallback, faithful to elfutils backends/aarch64_unwind.c
+   (fetched 2026-06-11, evverx/elfutils mirror):
+   - FP_REG=29 LR_REG=30 SP_REG=31; FP_OFFSET=0 LR_OFFSET=8 SP_OFFSET=16.
+   - prev pc = lr; fail only if lr unreadable or lr == 0.
+   - newLr = mem[fp+8] else 0; newFp = mem[fp+0] else 0; newSp = fp+16.
+   - success iff `fp == 0 || newSp > sp` (NO bp>=sp precondition like x86;
+     fp==0 still yields one lr-based caller).
+   - Iterate like the x86 `unwind_x86_64_frame_pointer_stack_like_elfutils` loop
+     (callback-per-frame semantics; subsequent pc gets the `!initial && !signal`
+     pc-1 adjustment in the consumer like the existing code).
+4. Gate x86-only logic by arch: syscall-return truncation (no arm64 analogue),
+   `regs.bp >= regs.sp` fallback precondition is x86-only (aarch64 fallback has
+   its own conditions above).
+5. Leaf-only / scenario-D predicate (see .ace-research-perf-unwind.md §3): on
+   aarch64 the no-CFI fallback succeeds whenever lr != 0, so "current-IP-only"
+   stacks are far rarer; the cheap skip-gate condition 6 becomes
+   `!has_unwind_info_for_ip(ip) && lr == 0` on aarch64.
+
+## Tests
+
+- Unit tests mirroring tests/perfdata_unwind.rs x86 cases for the aarch64
+  fallback (synthetic stacks: fp chain at fp+0/fp+8, the fp==0-with-lr case, the
+  newSp <= sp failure case).
+- Reg decoding tests for the arm64 mask layout (pc=32, sp=31, fp=29, lr=30).
+- End-to-end: `scripts/perf-oracle` → dwarf bench comparison should go from
+  pyroclast_folded_lines=2 vs inferno=16 to matching (after the script-parity
+  naming fixes are merged; residuals analyzed against
+  .ace-research-perf-unwind.md).