FAQ and troubleshooting

Platform spec article

FAQ and troubleshooting

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

FAQ

Why separate BUILTIN_SPECS and RUNTIME_EXPORT_SYMBOLS?

Names alone are insufficient for Cranelift: BuiltinFnSpec carries parameter and return kinds. The export list additionally includes symbols resolved without going through the spec table (for example version export) and documents the linker surface for AOT.

Can I add a builtin only in runtime?

No (BLT-001). Codegen will not declare the import; JIT fails at finalize or AOT fails at link.

What calling convention is used?

Generated code uses the Cranelift default for the host ISA; runtime exports use extern "C-unwind" so panics across the boundary remain defined for Rust host frames.

Do fiber builtins use Fiber<T> in the ABI?

No. ABI uses raw ids and pointers; generic Fiber<T> is a corelib surface. See Fiber scheduler.

Troubleshooting

Symptom	Likely fix
MissingFunction for channel_receive	Call site uses old symbol; use channel_receive_status / channel_receive_value
CLIF verify failure on builtin call	Arity mismatch—update BUILTIN_SPECS and lowering together
GC heap corruption after new store	Missing gc_write_barrier in lowering for pointer write
array_new always null data pointer	Build runtime with --features arrays_backing if tests need backing storage

Related topics

• Flow and algorithm
• Runtime feature flags