commit 1b9c9e4a655a8f6ae719cea49851d3c5b8a61783
parent 0f52c64c72c5244f3d33abc9ff3edfb5998d3f89
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Thu, 21 May 2026 07:02:32 -0700
docs: add x64 parity checklist
Diffstat:
1 file changed, 92 insertions(+), 0 deletions(-)
diff --git a/doc/X64_PARITY_CHECKLIST.md b/doc/X64_PARITY_CHECKLIST.md
@@ -0,0 +1,92 @@
+# x64 parity checklist
+
+Goal: bring `x86_64` to the same practical coverage as `aarch64` across
+standalone asm, disasm, C/toy compilation, object/link output, runtime, and
+debug tooling.
+
+## Asm / disasm
+
+- [ ] Expand `src/arch/x64/asm.c` beyond the current small AT&T subset:
+ branches, calls, arithmetic, shifts, compares, loads/stores, LEA, atomics,
+ SSE scalar FP, and backend-emitted forms.
+- [ ] Build an x64 ISA descriptor layer equivalent in role to
+ `src/arch/aa64/isa.{h,c}` so encoder, decoder, printer, and tests share
+ one instruction description.
+- [ ] Expand `src/arch/x64/disasm.c` to decode every instruction emitted by
+ x64 codegen and every standalone-asm form accepted by the assembler.
+- [ ] Add x64 listing tests under `test/asm/listing/`.
+- [ ] Make asm round-trip (`S`) meaningful for x64 codegen output and gate the
+ x64-emitted corpus on it.
+- [ ] Update `test/asm/regen.sh` or add an x64 variant for clang/objdump golden
+ regeneration.
+
+## Inline asm
+
+- [ ] Broaden x64 inline-asm template rendering to cover operand modifiers and
+ memory forms expected by GNU-style x86_64 asm.
+- [ ] Add an x64 inline-asm unit test parallel to `test/arch/aa64_inline_test.c`.
+- [ ] Verify register clobbers, `"cc"`, `"memory"`, callee-saved preservation,
+ early-clobber, matching constraints, and named operands on x64.
+- [ ] Add C and toy inline-asm execution cases that run on an x64 host/runner.
+
+## C / toy codegen
+
+- [ ] Close remaining explicit x64 backend panics in `src/arch/x64/ops.c`
+ (`u64`/FP conversions, unsupported bitcasts, non-constant memset byte
+ paths, indirect aggregate arg shapes, tail-call/sret gaps, and other
+ `unsupported`/`unimpl` paths).
+- [ ] Match aa64 coverage for scalar integer, FP, pointer, aggregate, varargs,
+ atomics, intrinsics, labels, computed goto, switch lowering, and alloca.
+- [ ] Prove x64 optimized and unoptimized C parse corpus paths with targeted
+ `CFREE_TEST_ARCH=x64` runs.
+- [ ] Prove toy cross-arch path `X` for x64 alongside aa64 cases.
+
+## ABI / platform
+
+- [ ] Finish SysV x86_64 ABI edge cases: aggregate classification, register save
+ area, variadic call metadata (`AL`), sret, byval, and mixed int/FP returns.
+- [ ] Decide and implement x86_64 Darwin ABI differences where they diverge from
+ Linux/SysV behavior.
+- [ ] Implement x86_64 `long double` semantics (`x87` 80-bit in 16-byte
+ storage) or document a staged compatibility mode.
+- [ ] Audit predefined macros, target triples, and driver target selection for
+ Linux and Darwin x86_64 parity.
+
+## Object / link / driver
+
+- [ ] Ensure ELF x86_64 relocations cover all codegen, asm, TLS, PLT/GOT, ifunc,
+ and linker-script cases currently passing for aa64.
+- [ ] Bring Mach-O x86_64 object/link coverage up to the aa64 Mach-O subset.
+- [ ] Exercise `cfree as`, `cc`, `ld`, `objdump`, `run`, and `emu` paths with
+ x64-specific tests where the command is intended to support x64.
+- [ ] Add x64 object disassembly annotation coverage for symbols and relocs.
+
+## Runtime / libc
+
+- [ ] Build `libcfree_rt.a` for x86_64 Linux and Darwin through cfree, not just
+ host clang probes.
+- [ ] Bring x86_64 coroutine/runtime assembly and C sources through the cfree
+ assembler/compiler path.
+- [ ] Retarget musl/glibc libc harnesses to x64 sysroots and run the same cases
+ currently exercised for aa64.
+- [ ] Add x64 smoke cases that use cfree-emitted bytes, not only clang-produced
+ harness binaries.
+
+## Debug / JIT / tooling
+
+- [ ] Add x64 displaced-step/debugger support: `INT3`, RIP-relative fixups,
+ ucontext register marshalling, and frame walking.
+- [ ] Emit and validate x64 DWARF CFI/line-info details, including frame-pointer
+ conventions and call-frame rows.
+- [ ] Fill x64 JIT support gaps: executable memory, relocations, symbol calls,
+ TLV/TLS behavior, and native-host execution tests.
+- [ ] Decide emulator scope for x86_64; either implement it or mark `emu` as
+ non-parity for x64.
+
+## Test policy
+
+- [ ] Add x64-targeted filters/goldens for each new feature as it lands.
+- [ ] Keep skips explicit and arch-scoped; do not let x64 cases silently ride
+ aa64 defaults.
+- [ ] Promote targeted x64 runs into default or CI-equivalent coverage once they
+ are stable on available runners.
