A thin, no-policy Rust crate for EriX handoff structures used in early boot and early userspace bootstrap.
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Erik Inkinen 05ea748d5f
All checks were successful
CI / markdown (push) Successful in 2s
CI / test (push) Successful in 24s
ci: Merge checked source acquisition
Preserve the exact reviewed feature tree and its original history while qualifying the destination against current main providers.
2026-11-14 19:33:19 +02:00
.github feat: encode counted processor topology as immutable boot data 2026-11-13 14:39:42 +02:00
docs docs: distinguish shared segment initialization from mapping policy 2026-11-13 15:41:01 +02:00
src fix: preserve empty memory-map record compatibility 2026-11-13 15:36:07 +02:00
tests feat: describe exact loaded runtime allocations and segment policy 2026-11-13 15:33:12 +02:00
.editorconfig Initial commit 2026-02-26 11:39:01 +01:00
.gitignore Ignore local .ci workspace 2026-04-15 21:52:51 +03:00
.markdownlint-cli2.yaml Tighten CI markdown policy 2026-05-22 15:10:22 +03:00
ARCHITECTURE.md feat: describe exact loaded runtime allocations and segment policy 2026-11-13 15:33:12 +02:00
Cargo.toml Add handoff structures and validation for bootloader, kernel, and root services 2026-02-26 12:52:24 +02:00
CODE_OF_CONDUCT.md docs: Synchronize shared contribution and review policies 2026-09-12 06:38:17 +03:00
CONTRIBUTING.md docs: Align dependency selection and review policy 2026-10-30 19:15:28 +02:00
LICENSE Initial commit 2026-02-26 11:39:01 +01:00
README.md feat: describe exact loaded runtime allocations and segment policy 2026-11-13 15:33:12 +02:00
ROADMAP.md feat: describe exact loaded runtime allocations and segment policy 2026-11-13 15:33:12 +02:00
rustfmt.toml lib-handoff: drop unstable rustfmt options for stable toolchains 2026-03-23 10:19:54 +02:00
SECURITY.md docs: Synchronize shared contribution and review policies 2026-09-12 06:38:17 +03:00

lib-handoff

lib-handoff is the allocation-free Rust owner of EriX's versioned bootloader-to-kernel and kernel-to-root byte layouts.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

  • docs for design documents and normative handoff specifications
  • lib-bootstrap for the separate root-to-service startup protocol

Purpose of This Repository

This repository provides one implementation boundary for the byte contracts that cross EriX's first two boot transitions. It exposes:

  • little-endian decoders for the two fixed headers
  • checked table and range validation
  • allocation-free iterators over memory, module, RAM allocator extent, framebuffer, and dynamic-catalog records
  • a required boot-calibrated processor-clock frequency for explicit hardware-deadline conversion in the kernel
  • constants for the encoded record sizes, identifiers, kinds, and flags
  • the x86_64 recursive-page-table index shared by the bootloader and kernel

validate_blob rejects incompatible versions, size mismatches, native-width conversion failures, metadata that overlaps a header or another metadata range, malformed entry sizes, unknown record values, forbidden writable and executable segment combinations, a missing processor-clock frequency, and non-zero reserved fields. Semantic launch, memory-map, capability, and dependency-graph policy remains with the receiving component.

BootKernel v2.1, v2.2 and v2.3 use the ERIXHK02 magic and keep the 200-byte header. Its 128-byte object records contain counted UTF-8 name spans into the original signed dynlink store; 32-byte dependency records refer to object indices. name_text borrows from the caller's store without copying or truncating names. validate_catalog_store binds each name and payload span, kind, and recorded digest to its exact original store entry, rejects duplicate names, and checks complete segment and dependency table ownership. Callers authenticate the store and payloads and retain the store for every borrowed name. KernelRoot v1.2 and the shared memory, module, framebuffer, and segment records remain unchanged. BootKernel v1 APIs are removed; producers and consumers migrate together.

The optional x86 startup extension describes original page-table, trampoline, real-mode stack, and BSP stack allocations. Validation checks geometry, non-overlap, and complete bootloader reservations. These descriptions grant no memory authority; the kernel must retain the original allocations. See startup resources for offsets and lifetime rules. BootKernel accepts exactly v2.1, v2.2 and v2.3; earlier and unknown minors are rejected. The 2.2 counted processor topology carries immutable u32 IDs through a borrowed view. It preserves the startup descriptor position, checks all metadata overlaps and preflights encoding before any write. Firmware capture, duplicate/BSP checks and actual CPU ownership stay with the producer and native consumer.

Direct Cargo consumers are bootloader, kernel, and rootd.

Clean-Room Policy

EriX follows a strict clean-room philosophy:

  • No external source code may be copied.
  • No external Rust crates are allowed.
  • No code generation tools that embed third-party code.
  • All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

Repository validation requires:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTFLAGS="-D warnings" cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
RUSTFLAGS="-D warnings" cargo build --target x86_64-unknown-none --all-features

The crate is no_std, denies unsafe code and missing public documentation, and has no dependencies.

Governance Principles

lib-handoff governance is limited to shared boot-transition representation and structural validation:

  • Wire sizes are explicit constants, not values derived from host layout.
  • Every wire offset is checked before conversion to native indexing.
  • Full validation covers every referenced descriptor before success.
  • The crate performs no I/O, allocation, service discovery, or policy action.
  • Root-to-service startup messages have one owner, lib-bootstrap; they are not duplicated here.
  • Format changes require coordinated consumer updates. Pre-release formats do not retain unused compatibility fields or aliases.

Library Boundaries

lib-handoff carries metadata, including capability-slot identifiers, but holds no authority. Callers remain responsible for proving that metadata corresponds to installed capabilities and for enforcing boot policy.

Contact

Development occurs in the EriX organization. Decisions require documented rationale in issues or design documents.

Maintainers can be reached at admin@erikinkinen.fi.

BootKernel 2.3 loaded runtime-image descriptions separate whole allocation custody from exact segment mapping policy. Records and hashes convey no ownership; original handover, source verification and native lifetime enforcement remain producer/consumer responsibilities.