sx/current/CHECKPOINT-ASM.md

sx Inline Assembly — Checkpoint (ASM stream)

Companion to current/PLAN-ASM.md; design in docs/inline-asm-design.md. Update after every commit, one step at a time per the cadence rule (no commit may both add a test and make it pass).

Last completed step

C.0 — IR op inline_asm (lock; no behavior change). Added inline_asm: InlineAsm to the IR Op union + the InlineAsm struct (template: StringId, operands: []const AsmOperand {role/name/constraint/operand}, clobbers: []const StringId, has_side_effects) in src/ir/inst.zig — all strings interned, operands in source order, result on Inst.ty. The new variant forced (and got) arms in two exhaustive Op switches: src/ir/interp.zig (loud bailDetail — inline asm is never comptime-evaluable) and src/ir/print.zig (IR dump). src/ir/emit_llvm.zig gets a @panic tripwire — emit lands in Phase D, and until then lowerAsmExpr still bails so no inline_asm op is ever created (reaching emit would be a lowering-switched-over-too-early bug). Unit test inline_asm op shape in src/ir/inst.test.zig. zig build test green (652 corpus, 446 unit). Files: src/ir/inst.zig, src/ir/interp.zig, src/ir/print.zig, src/ir/emit_llvm.zig, src/ir/inst.test.zig.

Prior: B.1 — operand-name validation (design §II.5 auto-naming rule). Extended lowerAsmExpr with a pinnedRegister(constraint) helper ("={eax}"→eax, "+{rax}"→rax, "=r"→null) and two checks: (1) reject the echo form [eax] "={eax}" — a label identical to its own pinned register is redundant (the operand is already auto-named after the register); (2) reject duplicate operand names (ambiguous %[name] / result field). Locked with examples/1643-platform-asm-echo-name.sx + 1644-platform-asm-duplicate-name.sx. zig build test green (652 corpus, 0 failed; 445 unit). Files: src/ir/lower/expr.zig.

Prior: B.0 — asm shape validation (compile-path diagnostics). Restructured the .asm_expr lowering arm into lowerAsmExpr (src/ir/lower/expr.zig, mixed into Lowering in src/ir/lower.zig): it validates BEFORE the not-yet-implemented codegen bail, so the user sees the real problem first. Two checklist items now enforced with named diagnostics: (1) template must be a compile-time-known string ("..." / #string); (2) no value outputs ⇒ must be volatile (mirrors Zig — a result-less asm could be deleted). Valid shapes still bail with the "codegen not yet implemented" message. Result-type derivation + auto-naming stay deferred to a later step (observable only once Phase C produces a real IR op). Locked with examples/1641-platform-asm-missing-volatile.sx (volatile error) + 1642-platform-asm-nop-volatile.sx (volatile no-output accepted → codegen bail). zig build test green (650 corpus, 0 failed; 445 unit). Files: src/ir/lower/expr.zig, src/ir/lower.zig, examples/164{1,2}-*.

Prior: A.1 — parse asm { … } + loud lowering bail (folded A.1+A.2 into one honest lock commit, since the loud bail IS current correct behavior — cadence option (a)). Added AsmExpr/AsmOperand to src/ast.zig + the asm_expr Node.Data arm; parseAsmExpr in src/parser.zig (parsePrimary .kw_asm dispatch) — parses the template, flat operand list ([name]? "constraint" -> Type value output / = expr input), and clobbers(.…); volatile/clobbers recognized contextually via isContextualWord. The new asm_expr tag forced (and got) arms in three exhaustive Node.Data switches: src/sema.zig analyzeNode + findNodeAtOffset, src/ir/semantic_diagnostics.zig checkBindingNames (all recurse into template + operand payloads). Lowering bails LOUD + named in src/ir/lower/expr.zig ("inline assembly codegen is not yet implemented…") via an explicit .asm_expr arm (not the generic unknown_expr else) returning emitPlaceholder. -> @place write-through is rejected with a clear "Phase 2" parse error. Locked with examples/1640-platform-asm-parse.sx (multi-output divmod, named operands, register pins, clobbers — parses then bails; called from main). zig build test green (648 corpus, 0 failed; 445 unit). Files: src/ast.zig, src/parser.zig, src/sema.zig, src/ir/semantic_diagnostics.zig, src/ir/lower/expr.zig, examples/1640-*.

Prior: A.0 — kw_asm keyword (first compiler code). Added the kw_asm Token.Tag variant + .{ "asm", .kw_asm } keyword-map entry in src/token.zig; volatile / clobbers deliberately stay OUT of the global table (contextual). New exhaustive Tag switch in src/lsp/server.zig classifyToken flagged the missing arm (the intended coverage tripwire) — added .kw_asm to the keyword group. Lock test in new src/lexer.test.zig (asm→kw_asm, volatile/clobbers→identifier), wired into the src/root.zig barrel as lexer_tests. zig build test green (648 corpus, 0 failed; 445 unit, 0 failed — +1). Files: src/token.zig, src/lexer.test.zig, src/root.zig, src/lsp/server.zig.

Prior: 0.2 — CLAUDE.md docs for <name>.build; Phase 0 COMPLETE. 0.1 — corpus runner ir-only branch for cross-target examples. Replaced 0.0's loud placeholder bail: when cfg.target doesn't match the host (ir_only), sweepRoot skips run/build/exec and verifies via sx ir --target only — asserting .exit (ir cmd) + .ir (normalized stdout) + .stderr, never .stdout (write skipped in update mode, assertion skipped in verify mode). An .ir snapshot is required in ir-only mode — its absence is a loud failure ("needs an .ir snapshot for ir-only mode"). Locked with examples/1639-platform-target-cross.sx (asm-free main :: () -> i64 { return 0; }), .build { "target": "x86_64-linux" }, + checked-in .ir. Verified both guards fire: corrupting the .ir → IR mismatch; deleting it → the require-failure. zig build test green (647 corpus, 0 failed; 444 unit). Files: src/corpus_run.test.zig, examples/1639-*.

Current state

Phase A underway: asm { … } lexes (A.0) and parses into AsmExpr (A.1); lowering bails LOUD + named (no IR op / emit yet). Result-type derivation, the operand auto-naming rule, and the validation checklist are Phase B (not yet implemented — any asm reaching lowering errors out). The adopted operand auto-naming rule (design §II.5, decided this session): name auto-derived from a {reg} pin; explicit [name] only when it differs or for register-class (=r) operands; echo form [eax] "={eax}" rejected. Parser stores name: ?[]const u8; the rule is a Phase-B (typing) concern, so the parser needs no change for it.

Known orthogonal bug: issue 0137 — sx run on a program with no main segfaults (src/target.zig:256-273, unguarded JIT entry lookup). Pre-existing, asm-independent; does NOT block the ASM stream (every example has a main).

Phase B–E feasibility already confirmed against the live tree (LLVMGetInlineAsm / LLVMBuildCall2 / LLVMAppendModuleInlineAsm in LLVM@19 Core.h; ERR-stream extractvalue→tuple in emit_llvm.zig:726-927; lib-less extern, 60 sites; --target a global CLI flag).

Next step

C.1 + D together (must land as one green step) — wire lowerAsmExpr to BUILD the inline_asm op (intern template + constraints + clobber names; resolve each operand's effective name via the §II.5 auto-naming rule; lower input Refs; compute the result TypeId from the out_value operands — 0→void, 1→T, N→tuple, named) AND implement emitInlineAsm in src/ir/emit_llvm.zig (replacing the @panic tripwire) — the port of Zig's airAssembly: assemble the LLVM constraint string (outputs =/+, inputs, clobbers→~{name}), rewrite %[name]→${N} / %% / %=, LLVMGetInlineAsm + LLVMBuildCall2, AT&T dialect. They land together because the moment lowering stops bailing, emit is reached — a half-step would hit the tripwire. First target: the single-value-output syscall on x86_64-linux (ir-only via a .build { "target": "x86_64-linux" } + .ir snapshot, since the host is aarch64). Result-type derivation for expr_typer.zig (inferType .asm_expr arm) also lands here — now observable. Then E (multi- return tuples) + remaining validation (%[name] references a real operand). See PLAN-ASM.md Phases C–E + design §II.6.

Log

• (init) Plan + design doc written; ASM stream opened.
• (0.0) Corpus runner target-gating: <name>.build JSON config (replaces .aot marker), --target threading, hostMatchesTarget execute-gate, loud cross-target placeholder bail. Migrated 1226/1227 .aot→.build; locked with 1638 fixture + unit tests. zig build test green.
• (0.1) ir-only branch: cross-target examples verify via sx ir --target only (exit+ir+stderr, no stdout; .ir required). Locked with 1639 fixture; verified corrupt-.ir → mismatch and missing-.ir → loud failure. zig build test green.
• (0.2) docs: CLAUDE.md documents <name>.build JSON sidecar (aot + target + ir-only gating), replacing stale .aot marker prose. Phase 0 COMPLETE.
• (A.0) kw_asm keyword in token.zig (+ map entry); LSP classifyToken switch coverage; lock test in new lexer.test.zig (wired via root.zig). volatile / clobbers stay contextual identifiers. zig build test green (445 unit, +1).
• (A.1) parse asm { … } → AsmExpr + loud lowering bail; asm_expr arms in 3 exhaustive Node.Data switches; -> @place rejected (Phase 2). Adopted operand auto-naming rule (design §II.5). Locked with 1640 fixture. Filed orthogonal issue 0137 (no-main JIT segfault). zig build test green (648 corpus, 445 unit).
• (B.0) asm shape validation in lowerAsmExpr: comptime-string template + no-output⇒volatile, with named diagnostics before the codegen bail. Locked with 1641 (volatile error) + 1642 (volatile accepted). zig build test green (650 corpus, 445 unit).
• (B.1) operand-name validation: pinnedRegister helper + reject echo form ([eax] "={eax}") and duplicate names. Locked with 1643 + 1644. zig build test green (652 corpus, 445 unit).
• (C.0) IR op inline_asm: InlineAsm + interp bailDetail + print arm + emit @panic tripwire (Phase D). No behavior change (lowering still bails). Unit test inline_asm op shape. zig build test green (652 corpus, 446 unit).

Known issues

• 0137 — sx run on a program with no main segfaults (unguarded JIT entry lookup, src/target.zig:256-273). Pre-existing, asm-independent. Filed issues/0137-jit-run-no-main-segfault.md. Does not block A.1.