fibers: rename ABI variant .pure -> .naked
"pure" universally means side-effect-free (GCC __attribute__((pure)), FP purity, D's pure) — the opposite of a register-clobbering context switch. The concept is "naked": no compiler-generated prologue/epilogue, body is raw asm that emits its own ret. That is the established term everywhere (LLVM's naked function attribute — which we literally emit — plus Zig callconv(.naked), Rust #[naked], GCC/Clang __attribute__ ((naked))). Rename the keyword + everything keyed off it so concept, surface, field, and the emitted LLVM attribute all agree. - ast.zig: ABI enum variant pure -> naked (+ doc). - parser: accept abi(.naked); error text updated. - IR Function.is_pure -> is_naked; type_resolver/decl/generic/pack/ emit_llvm references updated; diagnostics say abi(.naked). - examples 1800-1803 renamed *-pure-* -> *-naked-* (source + expected/ snapshots; .ir/.exit/.stdout/.stderr are byte-identical — the emitted IR is unchanged, only the keyword spelling differs). - docs (PLAN-FIBERS, CHECKPOINT-FIBERS, PLAN-POST-METATYPE, the design roadmap, the compiler-API checkpoint/design) updated; the naming rationale now records why .naked over .pure. No semantic change — pure cosmetics. Suite green (725/0).
This commit is contained in:
agra
@@ -1,6 +1,6 @@
|
||||
# PLAN-FIBERS — Stream B1 (fibers + Io + M:1 scheduler)
|
||||
|
||||
> **STATUS: 🚧 in progress.** B1.0 (`abi(.pure)` codegen) ✅ complete — emits a real LLVM
|
||||
> **STATUS: 🚧 in progress.** B1.0 (`abi(.naked)` codegen) ✅ complete — emits a real LLVM
|
||||
> `naked` function end-to-end (decl / generic / pack paths; examples 1800/1801/1802 + unit
|
||||
> test). Next step = **B1.1** (per-fiber `context` root — probe-first, likely library-only).
|
||||
|
||||
@@ -12,7 +12,7 @@ separate carve ([PLAN-CHANNELS.md], when reached) and depends on this + atomics
|
||||
|
||||
**Goal:** the colorblind, stackful, **pure-sx** async runtime — fibers behind an `Io`
|
||||
interface, an M:1 scheduler, blocking + deterministic-sim + event-loop `Io` impls. The
|
||||
**compiler floor is small and net-new**: make `abi(.pure)` actually emit an LLVM `naked`
|
||||
**compiler floor is small and net-new**: make `abi(.naked)` actually emit an LLVM `naked`
|
||||
function (B1.0), and confirm/close the per-fiber `context` root (B1.1). **Everything
|
||||
else — the context-switch asm, fiber bootstrap, `mmap` stacks, the scheduler, futures,
|
||||
the `Io` vtables — is ordinary sx library code** (design §4, §4.4). The irreducible FFI
|
||||
@@ -30,25 +30,27 @@ authorization.
|
||||
|
||||
## Design (grounded against the tree)
|
||||
|
||||
### B1.0 — `abi(.pure)` codegen (the one genuinely net-new compiler piece in B1)
|
||||
### B1.0 — `abi(.naked)` codegen (the one genuinely net-new compiler piece in B1)
|
||||
|
||||
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.
|
||||
The design doc spells this `callconv(.naked)`; the **real sx surface is `abi(.naked)`** —
|
||||
written in the postfix slot, `name :: (sig) -> Ret abi(.naked) { 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.
|
||||
The sx-facing name is **`naked`** throughout (keyword, field `is_naked`, diagnostics) —
|
||||
matching LLVM's `naked` attribute (the lowering mechanism) and the industry term
|
||||
(Zig/Rust/GCC/Clang). The ABI variant was renamed `.pure → .naked`: "pure" universally
|
||||
means *side-effect-free*, the opposite of a register-clobbering context switch.
|
||||
|
||||
**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
|
||||
- The `ABI` enum **already carries `.naked`** — `ABI = enum { default, c, compiler, naked }`
|
||||
([ast.zig:142](../src/ast.zig#L142)), documented "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 LLVM `naked`
|
||||
attribute**. So the net-new work is exactly: **carry `abi == .pure` into the IR
|
||||
- `.naked` is **inert today**: [type_resolver.zig:237](../src/ir/type_resolver.zig#L237)
|
||||
maps `.compiler, .naked → .default` CC, and `emit_llvm` emits **no LLVM `naked`
|
||||
attribute**. So the net-new work is exactly: **carry `abi == .naked` 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 pure flag** — add one (`is_pure: bool`).
|
||||
(default/c) + `is_compiler_domain`, but **no naked flag** — add one (`is_naked: 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)`
|
||||
@@ -56,24 +58,24 @@ function attribute is only the *lowering mechanism* (B1.0b), not what we call th
|
||||
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 `.pure` fn gets no synthetic `__sx_ctx`, no stack frame,
|
||||
`.naked` 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). The
|
||||
implicit-return machinery (`lowerValueBody`) must also be bypassed: a `.pure` body has no
|
||||
implicit-return machinery (`lowerValueBody`) must also be bypassed: a `.naked` 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 `.pure` body
|
||||
`LLVMGetInlineAsm` at [ops.zig:915](../src/backend/llvm/ops.zig#L915). The `.naked` body
|
||||
is a single asm block reusing this path.
|
||||
|
||||
**`.pure` ≠ `.c` (design §4.6 context-switch note):** a `.c` epilogue restores SP from the
|
||||
**`.naked` ≠ `.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. `.pure` = no prologue/epilogue/frame — the asm emits its
|
||||
own `ret`. This is *why* the switch must be `.pure`, not `.c`.
|
||||
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`.
|
||||
|
||||
**Snapshot story (per the atomics precedent):** a `.pure` fn's *body is raw per-arch asm*
|
||||
**Snapshot story (per the atomics precedent):** a `.naked` 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
|
||||
@@ -133,18 +135,18 @@ 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 (`.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_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
|
||||
B1.0 (`.naked`) forces these plumbing sites:
|
||||
- [ast.zig:142](../src/ast.zig#L142) — `ABI.naked` (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 == .naked`; gate the
|
||||
implicit-ctx off for `.naked` in `funcWantsImplicitCtx` (mirror the `.c` skip at
|
||||
decl.zig:515) and bypass `lowerValueBody` for `.naked` bodies (lower statements + cap with
|
||||
`unreachable`, in both body-lowering paths) — a `.naked` 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).
|
||||
- [type_resolver.zig:237](../src/ir/type_resolver.zig#L237) — leave CC `.default` (a `.naked`
|
||||
fn-pointer type has no CC of its own; nakedness 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
|
||||
`func.is_naked` (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.
|
||||
|
||||
@@ -152,25 +154,25 @@ B1.0 (`.pure`) forces these plumbing sites:
|
||||
|
||||
## Phases (xfail→green steps)
|
||||
|
||||
### B1.0 — `abi(.pure)` codegen — ✅ COMPLETE
|
||||
- **B1.0a (lock) — ✅ DONE.** Carried `abi == .pure` into IR `Function.is_pure`; threaded
|
||||
through `decl.zig` (`funcWantsImplicitCtx` skips `.pure` like `.c`; all body-lowering paths
|
||||
bypass `lowerValueBody` for `.pure`, lowering the asm body + capping with `unreachable`) +
|
||||
generic.zig + pack.zig; `emit_llvm` Pass 2 bailed loudly on `func.is_pure`. Locked by
|
||||
`examples/1800-concurrency-pure-asm.sx` + the generic regression (review-found gap).
|
||||
### B1.0 — `abi(.naked)` codegen — ✅ COMPLETE
|
||||
- **B1.0a (lock) — ✅ DONE.** Carried `abi == .naked` into IR `Function.is_naked`; threaded
|
||||
through `decl.zig` (`funcWantsImplicitCtx` skips `.naked` like `.c`; all body-lowering paths
|
||||
bypass `lowerValueBody` for `.naked`, lowering the asm body + capping with `unreachable`) +
|
||||
generic.zig + pack.zig; `emit_llvm` Pass 2 bailed loudly on `func.is_naked`. Locked by
|
||||
`examples/1800-concurrency-naked-asm.sx` + the generic regression (review-found gap).
|
||||
- **B1.0b (green) — ✅ DONE.** `emit_llvm` declaration pass adds LLVM `naked` + `noinline` +
|
||||
`nounwind` for `func.is_pure` and skips `frame-pointer=all` (incompatible with a frameless
|
||||
`nounwind` for `func.is_naked` and skips `frame-pointer=all` (incompatible with a frameless
|
||||
function); Pass 2 emits the body normally (`naked` ⇒ verbatim asm + own `ret`, no
|
||||
prologue). `1800` pinned aarch64 → exit 42 + `.ir`; `1801-concurrency-pure-generic.sx`
|
||||
prologue). `1800` pinned aarch64 → exit 42 + `.ir`; `1801-concurrency-naked-generic.sx`
|
||||
(renamed from `-bail`) proves the generic path emits a naked body (exit 42);
|
||||
`1802-concurrency-pure-asm-x86.sx` x86_64 cross sibling (ir-only here, `.ir` locks `naked`
|
||||
+ `movl $42, %eax`). Unit test `emit: abi(.pure) function gets the naked attribute` asserts
|
||||
`1802-concurrency-naked-asm-x86.sx` x86_64 cross sibling (ir-only here, `.ir` locks `naked`
|
||||
+ `movl $42, %eax`). Unit test `emit: abi(.naked) function gets the naked attribute` asserts
|
||||
`naked` present + `frame-pointer` absent. Suite green (724/0).
|
||||
- **B1.0c (review-hardening) — ✅ DONE.** A param-bearing `.pure` fn emitted invalid LLVM
|
||||
(loud verifier error). Gated the param-alloca loop on `fd.abi != .pure` (decl.zig both
|
||||
- **B1.0c (review-hardening) — ✅ DONE.** A param-bearing `.naked` fn emitted invalid LLVM
|
||||
(loud verifier error). Gated the param-alloca loop on `fd.abi != .naked` (decl.zig both
|
||||
paths + generic.zig) so a naked fn's args stay in registers (read by the asm body) — this
|
||||
*enables* B1.3's `swap_context(from, to)`. Locked by `1803-concurrency-pure-asm-param.sx`.
|
||||
Pack `.pure` (variadic + naked, nonsensical) left unsupported → loud verifier error.
|
||||
*enables* B1.3's `swap_context(from, to)`. Locked by `1803-concurrency-naked-asm-param.sx`.
|
||||
Pack `.naked` (variadic + naked, nonsensical) left unsupported → loud verifier error.
|
||||
|
||||
### 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,7 +209,7 @@ asserting program-emitted ordering contracts.
|
||||
---
|
||||
|
||||
## Gates
|
||||
- **B1.0:** unit `emit_llvm.test.zig` (the `naked` attr present on a `.pure` fn); two
|
||||
- **B1.0:** unit `emit_llvm.test.zig` (the `naked` attr present on a `.naked` fn); two
|
||||
arch-gated examples (aarch64 + x86_64) run end-to-end on a matching host, ir-only on a
|
||||
mismatch (assert `naked` + asm in `.ir`). **OUT of corpus scope, stated loudly:** the
|
||||
*correctness* of any hand-written register save/restore — that's the B1.3 stress harness.
|
||||
@@ -220,24 +222,24 @@ asserting program-emitted ordering contracts.
|
||||
- **B1.5:** `18xx` ordering-contract snapshots under the deterministic `Io`.
|
||||
|
||||
## Kickoff prompt (B1.0b — paste into a fresh session)
|
||||
> Implement Stream B1 step **B1.0b** (`abi(.pure)` real emission) per
|
||||
> Implement Stream B1 step **B1.0b** (`abi(.naked)` 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`
|
||||
> already landed: `Function.is_naked` plumbed, `decl.zig` skips ctx + bypasses implicit-return
|
||||
> for `.naked`, `emit_llvm` Pass 2 bails loudly, `examples/1800-concurrency-naked-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
|
||||
> `func.is_naked` 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
|
||||
> emit_llvm.zig:1339) and emit the `.naked` 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
|
||||
> `examples/1800-concurrency-naked-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
|
||||
> `.ir` + regen (`-Dname=examples/1800-concurrency-naked-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/1802-concurrency-pure-asm-x86.sx` (x86_64 body, `.build
|
||||
> text). (3) Add `examples/1802-concurrency-naked-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
|
||||
> present on an `abi(.naked)` 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