Expand description
IndexBus v1 ABI layouts.
This crate is the single source of truth for the shared-memory ABI: Rust defines the layouts; C headers are generated from these definitions.
§v1 rules
- All layouts are
#[repr(C)]and (where required)#[repr(align(64))]. - Layouts are append-only within ABI v1. A newer producer may append extra sections,
and older consumers must validate compatibility using
LayoutHeader. - Optional appended wake sections (see
layouts::wake) must start at a 64-byte aligned offset. - All integer fields are host-endian.
- The ABI assumes a 64-byte cache line for padding/alignment decisions.
§v1 append-only policy (normative)
ABI v1 is append-only:
- Existing exported layout types and fields must not change size, alignment, order, or meaning.
- New capabilities are added by appending new sections at the end of a region.
- Append-only additions must be discoverable via:
LayoutHeader::capabilities(feature presence)LayoutHeader::layout_bytes(mapped byte length)
- Older readers must ignore trailing bytes they do not understand, after validating the base layout and required capabilities.
In practice:
- Concrete exported layouts (e.g.,
layouts::StateLayout256) include explicit padding so any appended sections start at a 64-byte boundary. - Any optional appended section must be capability-gated and validated at runtime before use.
§Validation / initialization
This crate defines layouts; it does not perform mapping or validation.
At runtime, consumers should validate at minimum:
LayoutHeader::is_compatible_v1istrue.- The mapped region length is at least
LayoutHeader::layout_bytes. LayoutHeader::capabilitiescontains all required capability bits for the intended usage.
§Atomics in the ABI
ABI atomic fields are represented as integer-backed newtypes
(IndexbusAtomicU32/IndexbusAtomicU64) so the generated C header stays portable,
while Rust still has an interior-mutability marker.
The contract is:
- Atomic operations are performed at the address of the integer field.
- Size/alignment must match the platform’s
AtomicU32/AtomicU64.
Downstream Rust crates should do atomic operations by casting &IndexbusAtomicU32/&IndexbusAtomicU64
to &AtomicU32/&AtomicU64 at the same address (see indexbus-core internal helpers).
§Header generation
The workspace provides an xtask that generates spec/indexbus_v1.h.
cargo run -p xtask -- gen-headers§ABI sanity checks (doctest)
use core::mem::{align_of, size_of};
use indexbus_abi::layouts::{StateLayout256, WakeCell};
use indexbus_abi::LayoutHeader;
assert_eq!(size_of::<LayoutHeader>(), 16);
assert_eq!(size_of::<WakeCell>(), 64);
assert_eq!(align_of::<WakeCell>(), 64);
assert_eq!(align_of::<StateLayout256>(), 64);
// Concrete state layouts must pad so an appended wake section starts 64-aligned.
assert_eq!(size_of::<StateLayout256>() % 64, 0);Re-exports§
pub use header::caps;pub use header::flags;pub use header::IndexbusAtomicU32;pub use header::IndexbusAtomicU64;pub use header::LayoutHeader;pub use header::INDEXBUS_ABI_VERSION_1;pub use header::INDEXBUS_MAGIC_IBUS;pub use constants::*;