Builtins and symbols

Platform spec feature

Builtins and symbols

Back to ABI and host boundary ◎ Open 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

• Area
  ABI and host boundary

  Parent area

• Area
  Codegen and IR

  Lowering and backend emission consume ABI symbol definitions

• Area
  Runtime

  Runtime builtins export and implement the ABI contract

What this feature specifies

This feature explains the stable ABI contract between generated code, runtime exports, and host execution. It is organized into newcomer-friendly articles that move from model, to flow, to contracts, then practical verification and debugging guidance.

Implementation anchors

• BuiltinFnSpec and BUILTIN_SPECS in compiler/crates/beskid_abi/src/builtins.rs
• RUNTIME_EXPORT_SYMBOLS in compiler/crates/beskid_abi/src/symbols.rs
• Builtin runtime implementations in compiler/crates/beskid_runtime/src/builtins/mod.rs
• Panic and syscall behavior in compiler/crates/beskid_runtime/src/builtins/panic_io.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-EXEC-ABI-0003, D-EXEC-ABI-0004); use the reader ADRs tab for expandable detail.

Articles

• BUILTIN_SPECS is sole Cranelift import sourceCodegen must not invent alternate calling conventions for runtime builtins.
• Contracts and edge casesMUST rules for builtin signatures, return kinds, and export name stability.
• Design modelBuiltinFnSpec catalog, runtime export symbols, and codegen import boundaries.
• ExamplesReading BUILTIN_SPECS, mapping symbols to runtime modules, and typical call patterns.
• FAQ and troubleshootingBuiltin symbol drift, signature mismatches, and codegen/runtime debugging.
• Flow and algorithmFrom lowering call sites through BUILTIN_SPECS to runtime C exports.
• Verification and traceabilityCrate paths and tests that pin builtin specs to runtime exports.