- Rust 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Preserve the exact reviewed feature tree and its original history while qualifying the destination against current main providers. |
||
| .github | ||
| docs | ||
| src | ||
| tests | ||
| .editorconfig | ||
| .gitignore | ||
| .markdownlint-cli2.yaml | ||
| ARCHITECTURE.md | ||
| Cargo.toml | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
| ROADMAP.md | ||
| rustfmt.toml | ||
| SECURITY.md | ||
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.