Flow and algorithm

Platform spec article

Flow and algorithm

Back to Builtins and symbols ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0003-builtin-specs-sole-clif-source BUILTIN_SPECS is sole Cranelift import source Accepted

   Codegen must not invent alternate calling conventions for runtime builtins.

   Context

   Hand-written Cranelift calls bypass the shared ABI catalog and desynchronize JIT, AOT, and runtime extern "C-unwind" implementations.

   Decision

   Rule	Detail
   Catalog	BUILTIN_SPECS in beskid_abi::builtins is the sole source of Cranelift import signatures (ABI-002)
   Codegen	declare_builtin_imports builds FuncIds only from specs
   Diverging builtins	AbiReturnKind::Never for panic so unreachable blocks are correct
   Parity	Symbol strings in specs must match RUNTIME_EXPORT_SYMBOLS entries (ABI-001)

   Consequences

   New builtins require spec, BUILTIN_SPECS, symbols.rs, and beskid_runtime::builtins in one change set.

   Verification anchors

   compiler/crates/beskid_codegen; compiler/crates/beskid_abi/src/builtins.rs.

   Open full ADR page

2. 0004-runtime-c-unwind-exports Runtime builtins use C-unwind exports Accepted

   no_mangle extern C-unwind symbols implement the stable host surface.

   Context

   Generated code calls runtime entrypoints across JIT relink and AOT link. Rust panics across the boundary must use the platform unwind ABI expected by Cranelift call sites.

   Decision

   Rule	Detail
   Export attribute	Implementations use #[unsafe(no_mangle)] pub extern "C-unwind" in beskid_runtime::builtins
   Registry	RUNTIME_EXPORT_SYMBOLS lists every export the linker/JIT registers
   Layout types	BeskidStr { ptr, len } and BeskidArray { ptr, len, cap } are normative payload headers
   Families	Allocation, GC, fibers, channels, interop dispatch, IO, and panic share one catalog

   Consequences

   Host tooling resolves imports by symbol name + BUILTIN_SPECS signature, not Rust mangling.

   Verification anchors

   compiler/crates/beskid_runtime/src/builtins/mod.rs; compiler/crates/beskid_runtime/src/lib.rs re-exports.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for builtin signatures, return kinds, and export name stability. article Standard Reviewed Fri May 22
• Design model BuiltinFnSpec catalog, runtime export symbols, and codegen import boundaries. article Standard Reviewed Fri May 22
• Examples Reading BUILTIN_SPECS, mapping symbols to runtime modules, and typical call patterns. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Builtin symbol drift, signature mismatches, and codegen/runtime debugging. article Standard Reviewed Fri May 22
• Flow and algorithm From lowering call sites through BUILTIN_SPECS to runtime C exports. article Standard Reviewed Fri May 22
• Verification and traceability Crate paths and tests that pin builtin specs to runtime exports. article Standard Reviewed Fri May 22

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Builtins and symbols

  Parent feature hub

Purpose

Trace how a builtin reference in CLIF becomes a live function pointer at run time. Registry diagram: design model.

Lowering to import declaration

1. HIR/lowering selects a runtime operation (allocate string, fiber_yield, etc.).
2. Codegen emits a call to the stable symbol string (for example alloc, not a mangled Rust name).
3. During JIT compile, declare_builtin_imports walks BUILTIN_SPECS in declaration order.
4. For each spec, codegen maps AbiParamKind::Ptr to the host pointer type and I64 to i64, then sets return type from AbiReturnKind.

Runtime entry

1. Generated code calls using the platform default calling convention (SysV on Linux x86_64).
2. The runtime builtin enters enter_runtime_scope / GC rules as needed (alloc, barriers).
3. Fiber/channel builtins park or enqueue work via beskid_runtime::scheduler without exposing scheduler internals to CLIF.

String builtin algorithm (str_concat)

1. Read BeskidStr headers for left and right operands.
2. Allocate a fresh buffer via alloc for combined byte length.
3. Copy UTF-8 payload; return new { ptr, len } handle.
4. On allocation failure or null inputs, trap via panic (no implicit Option at ABI layer).

GC barrier hook

1. Lowering emits gc_write_barrier(parent, child) after pointer stores when concurrent GC is active.
2. Runtime barrier ensures tri-color invariant (see Memory and GC).
3. Phase A may simplify barrier work when only one mutator runs; symbol remains reserved.

Related topics

• Contracts and edge cases
• compiler/crates/beskid_abi/src/builtins.rs — full spec table