C ABI profile — Types and call conventions

Platform spec article

C ABI profile — Types and call conventions

Back to C ABI profile ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (5)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   C/System V binding rules defer to this hub.

   Context

   Interop.Contracts primitives need a single C profile authority for tier-1 hosts.

   Decision

   This feature hub must own normative MUST/SHOULD for C-compatible foreign libraries. Sibling articles add detail without redefining hub MUST tables.

   Consequences

   Cranelift lowering and foreign library import tooling align to this profile.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/

   Open full ADR page

2. 0002-link-time-standard-tier1 Link-time binding Standard tier-1 Accepted

   dlopen is not Standard conformance for tier-1.

   Context

   Dynamic resolution complicates reproducible builds and CI conformance.

   Decision

   v0.3 Standard tier-1 conformance must use link-time library binding (link-time linking).

   Consequences

   Engine may retain Proposed extern_dlopen paths separately from Standard claims.

   Verification anchors

   compiler/crates/beskid_codegen; Foreign library import.

   Open full ADR page

3. 0003-dynamic-resolution-proposed Runtime dlopen Proposed appendix Accepted

   Dynamic resolution profile is non-Standard.

   Context

   Some hosts want late binding; tier-1 reference path standardizes link-time.

   Decision

   Runtime dlopen / dlsym resolution is demoted to the dynamic resolution profile (Proposed appendix, not Standard).

   Consequences

   Documentation and conformance matrices must not require dlopen for Standard tier-1.

   Verification anchors

   compiler/crates/beskid_engine/src/engine.rs (extern_dlopen, Proposed).

   Open full ADR page

4. 0004-winapi-out-of-stdlib-standard WinAPI outside stdlib Standard Accepted

   Windows user-extern linking not tier-1 Standard in corelib.

   Context

   WinAPI/stdcall surfaces belong in platform packages with distinct conformance tiers.

   Decision

   WinAPI / stdcall as a stdlib concern is out of scope for tier-1 Standard conformance; platform packages may document Proposed mappings separately.

   Consequences

   Platform tier matrix records host-specific tiers.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/

   Open full ADR page

5. 0005-v03-delivery-bands v0.3.0 views v0.3.1 CLayout bands Accepted

   Delivery bands separate Standard views from Proposed layout structs.

   Context

   Implementers need a spec-first schedule when codegen trails text.

   Decision

   Band	Content	Status
   v0.3.0	Interop views, link-time import, symbol overrides	Standard (spec; impl may trail)
   v0.3.1	CLayout primitive structs	Proposed
   Later	Nested FFI structs, enum ABI, foreign-thread entry	Planned

   Consequences

   Articles tag Proposed vs Standard explicitly; CI strict mode can gate premature Standard claims.

   Verification anchors

   /platform-spec/language-meta/interop/c-abi-profile/ and child articles.

   Open full ADR page

Articles

• C ABI profile — C layout types (v0.3.1) repr(C) records for FFI after interop views ship; nested complex types deferred. article Proposed Reviewed Wed May 20
• C ABI profile — Dynamic resolution profile Non-Standard appendix for runtime dlopen/dlsym extern resolution (legacy v0.1 path). article Proposed Reviewed Wed May 20
• C ABI profile — Extern contracts and linking Library and symbol metadata, JIT dlopen resolution, and policy gates for user extern contracts. article Standard Reviewed Fri May 01
• C ABI profile — Interop view types (v0.3.0) CStringView, CBuffer, and CArrayView layouts for user Extern boundaries. article Standard Reviewed Wed May 20
• C ABI profile — Link-time linking Normative link-time binding for user Extern libraries (v0.3 Standard). article Standard Reviewed Sat May 23
• C ABI profile — Platform tier matrix Tier-1 Standard hosts vs Proposed platforms; WinAPI out of stdlib scope. article Standard Reviewed Wed May 20
• C ABI profile — Types and call conventions Permitted C ABI representations for Beskid extern contract parameters and returns in the reference compiler. article Standard Reviewed Fri May 01

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 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
  C ABI profile

  Parent feature hub

Calling convention

For user contract calls lowered through the reference compiler path, parameters and returns are prepared for System V AMD64 when targeting that platform. This matches the explicit CallConv::SystemV selection in the contract call lowering implementation.

Other targets must document their own mapping in a future revision of this article; until then, only the documented tier-1 mapping is normative for Standard conformance claims.

Permitted value shapes (v0.3.0)

The C ABI profile instantiates Interop.Contracts as follows:

• Scalar — bool as i8, u8, i32, i64, f64, unit.
• Interop views — CStringView, CBuffer, CArrayView per interop view types.
• Opaque handle — pointer-sized slot or i64 where documented.
• ref u8 — narrow legacy slice start; prefer CBuffer.

Beskid string and T[] GC values must not appear on user Extern signatures in v0.3.0 Standard.

CLayout structs (primitive fields only) are v0.3.1 — C layout types. Nested complex types are deferred until basic FFI is implemented.

Types with unstable Beskid-only layout must not cross the boundary without an adapter or shim.

Cranelift note

Beskid user code and bridge code are lowered with Cranelift; foreign libraries need only expose C ABI entrypoints compatible with the emitted calls. See also /execution/runtime/ffi/ for additional lowering narrative.