Design model

Platform spec article

Design model

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

Document the dual registry that connects Beskid lowered code to the host runtime: symbolic names for the linker (RUNTIME_EXPORT_SYMBOLS) and machine signatures for Cranelift (BUILTIN_SPECS).

Primary actors

Actor	Artifact
beskid_abi::builtins	BuiltinFnSpec { symbol, params, returns } entries
beskid_abi::symbols	SYM_* constants + RUNTIME_EXPORT_SYMBOLS list
beskid_codegen	declare_builtin_imports builds Cranelift FuncIds from specs
beskid_runtime::builtins	#[unsafe(no_mangle)] pub extern "C-unwind" implementations

Builtin families

Family	Examples	Consumer
Allocation / values	alloc, str_new, str_concat, array_new	All backends
GC	gc_write_barrier, gc_collect, gc_root_handle	Lowering + host snapshots
Fibers	fiber_spawn, fiber_yield, fiber_join_value	corelib_concurrency
Channels / hubs	channel_send, hub_wait_receive_value	Concurrency package
Sync	mutex_lock, wait_group_wait	Runtime scheduler
Interop	interop_dispatch_unit, interop_dispatch_ptr	Tagged interop lowering
IO / faults	syscall_write, panic, panic_str	Corelib + traps
Diagnostics	test_bytes_ptr (test-only)	Compiler tests

Return kinds include AbiReturnKind::Never for diverging panic calls so Cranelift marks unreachable correctly.

Data layout contracts

• BeskidStr: { ptr, len } UTF-8 bytes (immutable; length in bytes).
• BeskidArray: { ptr, len, cap }; element storage optional behind runtime arrays_backing feature (Runtime feature flags).

Registry diagram

flowchart LR
  specs[BUILTIN_SPECS signatures]
  names[RUNTIME_EXPORT_SYMBOLS]
  clif[Cranelift imports]
  nm[no_mangle exports]
  specs --> clif
  names --> nm
  clif -->|same symbol string| nm

Related topics

• ABI versioning — when to bump version after symbol changes
• Flow and algorithm