fibers B1.0a: plumb abi(.pure), emit bails (lock)
First implementation step of Stream B1 (fibers). Make the inert abi(.pure) ABI carry an is_pure flag through lowering, with LLVM emission deliberately bailing loudly until B1.0b — the lock half of the lock->green cadence. - IR Function.is_pure, set from fd.abi == .pure at both declareFunction decl sites. - funcWantsImplicitCtx skips .pure (no synthetic __sx_ctx, mirroring the .c skip): a pure fn reads args from ABI registers, an implicit ctx would occupy a register slot the asm doesn't expect. - both body-lowering paths bypass lowerValueBody for .pure: lower the asm body as statements + cap with unreachable. A pure body has no sx return (the asm rets itself), so the implicit-return diagnostic must not fire. - emit_llvm Pass 2 bails loudly when func.is_pure (build-gating nonzero exit) rather than emit a framed body, whose epilogue would corrupt a context switch's deliberate SP-in != SP-out. examples/1800-concurrency-pure-asm.sx: one host example (no .build pin -- the bail fires before instruction selection, so it is host-independent), locked to the bail snapshot. B1.0b flips emit to LLVM's naked attribute + asm-only body and pins the example per-arch. The sx-facing name is "pure" throughout (field, diagnostic); LLVM's naked attribute is only the B1.0b lowering mechanism. Suite green (722/0).
This commit is contained in:
agra
@@ -1,7 +1,8 @@
|
||||
# PLAN-FIBERS — Stream B1 (fibers + Io + M:1 scheduler)
|
||||
|
||||
> **STATUS: 🚧 carved, not started.** First implementation step = **B1.0a** (naked-ABI
|
||||
> lock commit). See the kickoff prompt at the bottom.
|
||||
> **STATUS: 🚧 in progress.** B1.0a (`abi(.pure)` lock commit) ✅ landed. Next step =
|
||||
> **B1.0b** (`abi(.pure)` real emission — LLVM `naked` attr). See the kickoff prompt at the
|
||||
> bottom.
|
||||
|
||||
Carved from [PLAN-POST-METATYPE.md](PLAN-POST-METATYPE.md) Stream B (§B1) + the
|
||||
design-of-record [../design/execution-evolution-roadmap.md](../design/execution-evolution-roadmap.md)
|
||||
@@ -29,54 +30,60 @@ authorization.
|
||||
|
||||
## Design (grounded against the tree)
|
||||
|
||||
### B1.0 — `abi(.pure)` ⇒ LLVM naked (the one genuinely net-new compiler piece in B1)
|
||||
### B1.0 — `abi(.pure)` codegen (the one genuinely net-new compiler piece in B1)
|
||||
|
||||
The design doc spells `callconv(.naked)`; the **real sx surface is `abi(.pure)`** — written
|
||||
in the postfix slot, `name :: (sig) -> Ret abi(.pure) { asm { … }; }` (cf.
|
||||
The design doc spells this `callconv(.naked)`; the **real sx surface is `abi(.pure)`** —
|
||||
written in the postfix slot, `name :: (sig) -> Ret abi(.pure) { asm { … }; }` (cf.
|
||||
`build_options :: () -> BuildOptions abi(.compiler);` in [build.sx:28](../library/modules/build.sx#L28)).
|
||||
The sx-facing name is **pure** throughout (field, flag, diagnostics); LLVM's `naked`
|
||||
function attribute is only the *lowering mechanism* (B1.0b), not what we call the function.
|
||||
|
||||
**Grounding (verified — do not re-derive):**
|
||||
- The `ABI` enum **already carries `.pure`** — `ABI = enum { default, c, compiler, pure }`
|
||||
([ast.zig:142](../src/ast.zig#L142)), documented "pure / naked function (inline asm
|
||||
body), no calling-convention prologue/epilogue." So B1.0 is **NOT** "extend the enum."
|
||||
- `.pure` is **inert today**: [type_resolver.zig:237](../src/ir/type_resolver.zig#L237)
|
||||
maps `.compiler, .pure → .default` CC, and `emit_llvm` emits **no naked attribute**. So
|
||||
the net-new work is exactly: **carry `abi == .pure` into the IR `Function`, emit the LLVM
|
||||
`naked` attr, and skip the implicit-`Context` / prologue lowering** so the body is just
|
||||
the asm block + its own `ret`.
|
||||
maps `.compiler, .pure → .default` CC, and `emit_llvm` emits **no LLVM `naked`
|
||||
attribute**. So the net-new work is exactly: **carry `abi == .pure` into the IR
|
||||
`Function`, emit LLVM's `naked` attr, and skip the implicit-`Context` / prologue
|
||||
lowering** so the body is just the asm block + its own `ret`.
|
||||
- The IR `Function` struct ([inst.zig:605](../src/ir/inst.zig#L605)) carries `call_conv`
|
||||
(default/c) + `is_compiler_domain`, but **no naked flag** — add one (`is_naked: bool`).
|
||||
(default/c) + `is_compiler_domain`, but **no pure flag** — add one (`is_pure: bool`).
|
||||
- Attribute API is in-tree: `nounwind` is set at
|
||||
[emit_llvm.zig:1339](../src/ir/emit_llvm.zig#L1339) via
|
||||
`LLVMGetEnumAttributeKindForName("nounwind", 8)` → `LLVMCreateEnumAttribute(ctx, id, 0)`
|
||||
→ `LLVMAddAttributeAtIndex(func, func_idx_attr /* -1 */, attr)`. The `naked` attr is the
|
||||
same shape: `LLVMGetEnumAttributeKindForName("naked", 5)`.
|
||||
→ `LLVMAddAttributeAtIndex(func, func_idx_attr /* -1 */, attr)`. The LLVM `naked` attr
|
||||
is the same shape: `LLVMGetEnumAttributeKindForName("naked", 5)`.
|
||||
- The `.c` ABI **already skips the implicit ctx** at lowering — `lam.abi == .c` /
|
||||
`fd.abi == .c` gates (closure.zig:171, [decl.zig:515](../src/ir/lower/decl.zig#L515)).
|
||||
`.pure` must skip it **too** (a naked fn gets no synthetic `__sx_ctx`, no stack frame,
|
||||
no prologue — args arrive in ABI registers and are read directly from asm).
|
||||
`.pure` must skip it **too** (a `.pure` fn gets no synthetic `__sx_ctx`, no stack frame,
|
||||
no prologue — args arrive in ABI registers and are read directly from asm). The
|
||||
implicit-return machinery (`lowerValueBody`) must also be bypassed: a `.pure` body has no
|
||||
sx return (the asm rets itself), so lower its statements and cap the block with
|
||||
`unreachable`.
|
||||
- **Inline asm already works end-to-end** (lower→emit→JIT): aarch64
|
||||
([examples/1645](../examples/1645-platform-asm-aarch64-add.sx)), x86_64
|
||||
([examples/1651](../examples/1651-platform-asm-x86-syscall-write.sx)), global asm, JIT
|
||||
([1653](../examples/1653-platform-asm-global-jit.sx)). `emitInlineAsm` /
|
||||
`LLVMGetInlineAsm` at [ops.zig:915](../src/backend/llvm/ops.zig#L915). The naked body is
|
||||
a single asm block reusing this path.
|
||||
`LLVMGetInlineAsm` at [ops.zig:915](../src/backend/llvm/ops.zig#L915). The `.pure` body
|
||||
is a single asm block reusing this path.
|
||||
|
||||
**`.pure` ≠ `.c` (design §4.6 context-switch note):** a `.c` epilogue restores SP from the
|
||||
frame; a context switch deliberately makes SP-in ≠ SP-out, so the `.c` epilogue would
|
||||
restore from the *wrong* stack. `naked` = no prologue/epilogue/frame — the asm emits its
|
||||
own `ret`. This is *why* the switch must be naked, not `.c`.
|
||||
restore from the *wrong* stack. `.pure` = no prologue/epilogue/frame — the asm emits its
|
||||
own `ret`. This is *why* the switch must be `.pure`, not `.c`.
|
||||
|
||||
**Snapshot story (per the atomics precedent, corrected):** the LLVM `naked` attribute text
|
||||
is **arch-invariant**, but a naked fn's *body is raw per-arch asm* (it can't be portable —
|
||||
that's the point). So unlike atomics (where one host `.ir` sufficed), B1.0 needs **two
|
||||
arch-gated examples** — an aarch64 one and an x86_64 one — exactly like the existing asm
|
||||
corpus split (1645 aarch64 / 1651 x86). Each carries a `.build {"target": "<triple>"}`
|
||||
sidecar: it runs end-to-end on a matching host and falls to **ir-only** on a mismatch
|
||||
(asserting the `.ir` shows `define … #N` with the `naked` attribute + the asm body). State
|
||||
loudly: **the `.ir` proves the `naked` keyword + asm emitted, NOT that the hand-written
|
||||
register save/restore is correct** — that is the B1.3 switch-stress harness's job, never
|
||||
the corpus's.
|
||||
**Snapshot story (per the atomics precedent):** a `.pure` fn's *body is raw per-arch asm*
|
||||
(it can't be portable — that's the point), while LLVM's `naked` attribute text is
|
||||
arch-invariant. **B1.0a** (lock) needs only **one host example** locked to the emit bail —
|
||||
the bail fires at the function level *before* any asm/instruction selection, so it is
|
||||
host-independent (no `.build` target pin). **B1.0b** (green) adds emission, pins that
|
||||
example aarch64 (`.build {"target": "aarch64-macos"}`, end-to-end on a matching host,
|
||||
ir-only on a mismatch), and adds an x86_64 cross sibling — mirroring the existing asm
|
||||
corpus split (1645 aarch64 / 1651 x86). The ir-only `.ir` (only producible once emission
|
||||
lands in B1.0b) asserts the `naked` attribute + the asm body. State loudly: **the `.ir`
|
||||
proves the `naked` keyword + asm emitted, NOT that any hand-written register save/restore
|
||||
is correct** — that is the B1.3 switch-stress harness's job, never the corpus's.
|
||||
|
||||
### B1.1 — per-fiber `context` root (grounding says this is SMALL, likely library-only)
|
||||
|
||||
@@ -126,39 +133,42 @@ compiler work.** Prerequisite of B1.3 (a fiber needs a valid root before it swit
|
||||
don't churn every snapshot.
|
||||
|
||||
### Files the compiler floor touches (B1.0 only; B1.1–B1.5 are library + tests)
|
||||
B1.0 (naked) forces the exhaustive-switch / plumbing sites:
|
||||
B1.0 (`.pure`) forces these plumbing sites:
|
||||
- [ast.zig:142](../src/ast.zig#L142) — `ABI.pure` (exists; reference only).
|
||||
- [inst.zig:605](../src/ir/inst.zig#L605) — add `is_naked: bool = false` to `Function`.
|
||||
- [decl.zig](../src/ir/lower/decl.zig) — set `is_naked` from `fd.abi == .pure`; gate the
|
||||
implicit-ctx / param-stack / prologue lowering off for `.pure` (mirror the `.c` skips at
|
||||
decl.zig:515 + the entry-ctx bind at :2667/:2815 — a naked fn binds no ctx).
|
||||
- [type_resolver.zig:237](../src/ir/type_resolver.zig#L237) — leave CC `.default` (a naked
|
||||
fn-pointer type has no CC of its own; the nakedness is a decl-level emit attribute).
|
||||
- [emit_llvm.zig:1339](../src/ir/emit_llvm.zig#L1339)-adjacent — emit the `naked` enum attr
|
||||
on the LLVM function when `is_naked`; ensure no body-prologue is generated (naked body =
|
||||
the asm block only).
|
||||
- [inst.zig:605](../src/ir/inst.zig#L605) — add `is_pure: bool = false` to `Function`.
|
||||
- [decl.zig](../src/ir/lower/decl.zig) — set `is_pure` from `fd.abi == .pure`; gate the
|
||||
implicit-ctx off for `.pure` in `funcWantsImplicitCtx` (mirror the `.c` skip at
|
||||
decl.zig:515) and bypass `lowerValueBody` for `.pure` bodies (lower statements + cap with
|
||||
`unreachable`, in both body-lowering paths) — a `.pure` fn binds no ctx and has no sx
|
||||
return.
|
||||
- [type_resolver.zig:237](../src/ir/type_resolver.zig#L237) — leave CC `.default` (a `.pure`
|
||||
fn-pointer type has no CC of its own; pureness is a decl-level emit attribute).
|
||||
- [emit_llvm.zig:402](../src/ir/emit_llvm.zig#L402) Pass 2 — **B1.0a:** bail loudly when
|
||||
`func.is_pure` (build-gating). **B1.0b:** instead emit LLVM's `naked` attr (shape per
|
||||
`nounwind` at emit_llvm.zig:1339) + the asm-only body (no prologue).
|
||||
- Any `.op`/`Function`-field switch the Zig build flags — let the build tell you.
|
||||
|
||||
---
|
||||
|
||||
## Phases (xfail→green steps)
|
||||
|
||||
### B1.0 — `abi(.pure)` ⇒ LLVM naked ← START HERE
|
||||
- **B1.0a (lock)** — carry `abi == .pure` into IR `Function.is_naked`; thread through
|
||||
`decl.zig` (skip implicit-ctx for `.pure`, like `.c`); in `emit_llvm` **BAIL loudly** when
|
||||
a naked fn is emitted ("naked (`abi(.pure)`) emission not yet implemented"). Add
|
||||
`examples/1800-concurrency-naked-aarch64.sx` (a tiny naked fn with an aarch64 asm body that
|
||||
reads its arg from `x0`/returns via `ret`, `.build {"target":"aarch64-macos"}`) **and**
|
||||
`examples/1801-concurrency-naked-x86_64.sx` (x86_64 sibling, `.build
|
||||
{"target":"x86_64-linux"}`). Seed markers; capture the **bail diagnostic** as the locked
|
||||
snapshot (these are ir-only on the non-matching host, so the bail must surface at emit/IR
|
||||
time, not run). `zig build && zig build test` green against the bail. Commit.
|
||||
- **B1.0b (green)** — emit the LLVM `naked` attr (`LLVMGetEnumAttributeKindForName("naked",
|
||||
5)` + add at func index −1); ensure the naked body lowers to *only* the asm block (no
|
||||
prologue/epilogue, no ctx). On a matching host the example runs (asserts the computed
|
||||
value); on a mismatch it's ir-only (assert `.ir` shows `naked` + the asm). Capture both
|
||||
arch `.ir` snapshots; add a unit test in `emit_llvm.test.zig` asserting the `naked`
|
||||
attribute is present on a `.pure` function. Review the diff (no stray error text). Commit.
|
||||
### B1.0 — `abi(.pure)` codegen
|
||||
- **B1.0a (lock) — ✅ DONE** (commit pending). Carried `abi == .pure` into IR
|
||||
`Function.is_pure`; threaded through `decl.zig` (`funcWantsImplicitCtx` skips `.pure` like
|
||||
`.c`; both body-lowering paths bypass `lowerValueBody` for `.pure`, lowering the asm body +
|
||||
capping with `unreachable`); `emit_llvm` Pass 2 **bails loudly** on `func.is_pure`
|
||||
("`abi(.pure)` function '…' LLVM emission not yet implemented", build-gating nonzero exit).
|
||||
`examples/1800-concurrency-pure-asm.sx` (one host example, no `.build` pin — the bail is
|
||||
host-independent) locked to the bail snapshot. Suite green (722/0).
|
||||
- **B1.0b (green) ← NEXT** — emit LLVM's `naked` attr
|
||||
(`LLVMGetEnumAttributeKindForName("naked", 5)` + `LLVMCreateEnumAttribute` +
|
||||
`LLVMAddAttributeAtIndex` at func index −1; shape per `nounwind` at emit_llvm.zig:1339);
|
||||
emit the `.pure` body as the asm block only (no prologue/epilogue/ctx). Pin `1800`
|
||||
aarch64 (`.build {"target":"aarch64-macos"}`) → runs end-to-end (exit 42) on this host,
|
||||
ir-only on a mismatch; capture its `.ir` (asserts `naked` + the asm). Add an x86_64 cross
|
||||
sibling `examples/1801-concurrency-pure-asm-x86.sx` (`.build {"target":"x86_64-linux"}`,
|
||||
ir-only here). Add a unit test in `emit_llvm.test.zig` asserting the `naked` attribute is
|
||||
present on a `.pure` function. Review the diff (no stray error text). Commit.
|
||||
|
||||
### B1.1 — per-fiber `context` root (probe-first; likely zero compiler change)
|
||||
- **B1.1a (probe + lock)** — write a probe (`.sx-tmp/`) + an `18xx` example that snapshots a
|
||||
@@ -207,20 +217,25 @@ asserting program-emitted ordering contracts.
|
||||
it; `18xx` under the deterministic `Io`.
|
||||
- **B1.5:** `18xx` ordering-contract snapshots under the deterministic `Io`.
|
||||
|
||||
## Kickoff prompt (B1.0a — paste into a fresh session)
|
||||
> Implement Stream B1 step **B1.0a** (naked-ABI lock commit) per
|
||||
> `current/PLAN-FIBERS.md`. Verify `zig build && zig build test` is green first. Then: (1)
|
||||
> add `is_naked: bool = false` to the IR `Function` struct (`src/ir/inst.zig:605`); (2) in
|
||||
> `src/ir/lower/decl.zig`, set `is_naked` from `fd.abi == .pure` and gate the implicit-`Context`
|
||||
> / param-stack / entry-ctx lowering OFF for `.pure` (mirror the existing `fd.abi == .c`
|
||||
> skips at decl.zig:515 + the `__sx_default_context` binds at :2667/:2815 — a naked fn binds
|
||||
> no ctx); (3) in `src/ir/emit_llvm.zig`, **BAIL loudly** when emitting a naked function
|
||||
> ("naked (`abi(.pure)`) emission not yet implemented") — do NOT emit the attr yet; (4) add
|
||||
> `examples/1800-concurrency-naked-aarch64.sx` (tiny naked fn, aarch64 asm body, `.build
|
||||
> {"target":"aarch64-macos"}`) and `examples/1801-concurrency-naked-x86_64.sx` (x86_64
|
||||
> sibling, `.build {"target":"x86_64-linux"}`); seed the `.exit` markers, capture the
|
||||
> emit/IR-time bail diagnostic as the locked snapshot, confirm `zig build test` green, review
|
||||
> the diff, commit. STOP — B1.0b (real `naked` emission) is the next step; do NOT implement
|
||||
> emission in the same commit that adds the examples. Handle any exhaustive-switch site the
|
||||
> Zig build flags from the new `Function` field. If you hit an UNRELATED compiler bug, file
|
||||
> `issues/NNNN`, mark `CHECKPOINT-FIBERS.md` BLOCKED, and STOP.
|
||||
## Kickoff prompt (B1.0b — paste into a fresh session)
|
||||
> Implement Stream B1 step **B1.0b** (`abi(.pure)` real emission) per
|
||||
> `current/PLAN-FIBERS.md`. Verify `zig build && zig build test` is green first (B1.0a is
|
||||
> already landed: `Function.is_pure` plumbed, `decl.zig` skips ctx + bypasses implicit-return
|
||||
> for `.pure`, `emit_llvm` Pass 2 bails loudly, `examples/1800-concurrency-pure-asm.sx`
|
||||
> locked to the bail). Then: (1) in `src/ir/emit_llvm.zig` Pass 2 (~line 402), REPLACE the
|
||||
> `func.is_pure` bail with real emission — set LLVM's `naked` attribute on the function
|
||||
> (`LLVMGetEnumAttributeKindForName("naked", 5)` → `LLVMCreateEnumAttribute(ctx, id, 0)` →
|
||||
> `LLVMAddAttributeAtIndex(llvm_func, -1, attr)`; shape per the `nounwind` set at
|
||||
> emit_llvm.zig:1339) and emit the `.pure` body as its asm block only, no prologue/epilogue
|
||||
> (the body already lowers to the inline-asm op + an `unreachable` terminator). (2) Pin
|
||||
> `examples/1800-concurrency-pure-asm.sx` aarch64 with a `.build` sidecar
|
||||
> `{"target":"aarch64-macos"}`; on this aarch64 host it runs end-to-end (exit 42), capture
|
||||
> `.ir` + regen (`-Dname=examples/1800-concurrency-pure-asm.sx -Dupdate-goldens`), review the
|
||||
> diff (assert the `.ir` shows the `naked` attr + `mov x0, #42` / `ret`, NO stray error
|
||||
> text). (3) Add `examples/1801-concurrency-pure-asm-x86.sx` (x86_64 body, `.build
|
||||
> {"target":"x86_64-linux"}`, ir-only on this host — requires its `.ir`, now producible).
|
||||
> (4) Add a unit test in `src/ir/emit_llvm.test.zig` asserting the `naked` attribute is
|
||||
> present on an `abi(.pure)` function. Confirm `zig build test` green, commit. NOTE: the
|
||||
> `.ir` proves the keyword + asm emitted, NOT register-save correctness (that's the B1.3
|
||||
> switch-stress harness). If you hit an UNRELATED compiler bug, file `issues/NNNN`, mark
|
||||
> `CHECKPOINT-FIBERS.md` BLOCKED, and STOP.
|
||||
|
||||
Reference in New Issue
Block a user