lib-handoff

A thin, no-policy Rust crate for EriX handoff structures used in early boot and early userspace bootstrap.

This crate defines shared wire-level structs, constants, enums, and validation helpers for:

• bootloader -> kernel
• kernel -> root task
• root task -> critical services

It exists to keep handoff schemas centralized and versioned across repos.

---

Scope

lib-handoff is intentionally minimal:

• shared struct definitions for handoff headers/tables/messages
• version/magic constants and role/type identifiers
• checked size/bounds helpers for parsing and validation
• optional encode/decode helpers for little-endian fixed-layout fields

---

Non-goals

• No boot media parsing (boot.img is handled by lib-bootimg)
• No ELF parsing (lib-elf handles executable structure)
• No authority policy decisions (kernel/root own policy)
• No scheduler, IPC router, or service lifecycle logic
• No dynamic schema negotiation in v1

---

Why this crate exists

Without a shared crate, each stage would re-define the same handoff layout, causing drift and compatibility bugs.

lib-handoff provides one canonical representation used by:

• bootloader (producer for BL -> Kernel handoff)
• kernel (consumer of BL handoff, producer of Kernel -> Root handoff)
• root_task / early service launcher (consumer/producer for Root -> Services startup messages)
• test tooling and fixtures

---

Normative specs

These documents define the protocol semantics and invariants:

• ../docs/handoff/bl-to-kernel.md
• ../docs/handoff/kernel-to-root.md
• ../docs/handoff/root-to-services.md

This crate implements those structures; docs remain normative.

---

Design principles

• Thin wrapper only: represent protocol, do not embed boot policy.
• Version-first: every handoff starts with magic + major/minor version.
• Deterministic layout: fixed-size records where practical, little-endian fields.
• Checked arithmetic: offset/size calculations must never overflow.
• Portability: shared semantic fields are architecture/platform neutral; ABI transport details stay in adapters.
• Zero external crates: clean-room dependency policy.

---

Expected API surface (v1)

Illustrative module split (final names may vary):

• bl_kernel:
  • BlKernelHandoffHeaderV1
  • BlKernelMemRegionV1
  • BlKernelModuleV1
• kernel_root:
  • KernelRootInfoHeaderV1
  • KernelRootModuleDescV1
  • KernelRootUntypedDescV1
• root_services:
  • RootServiceStartEnvelopeV1
  • service role constants
• version:
  • magic/version constants
  • compatibility helpers
• validate:
  • bounds/table checks
  • entry-size/count checks

Invariants

If a handoff buffer is accepted by crate validation helpers:

• magic and version fields are recognized
• header/table offsets and lengths are in-bounds
• entry sizes match expected versioned layout
• count * entry_size arithmetic is overflow-safe
• required reserved fields satisfy v1 rules

Semantic policy checks (for example required module presence, required capability sets, launch policy) remain with caller components.

Security model

lib-handoff is in the trusted bootstrap chain and should be treated as TCB-adjacent.

Threat model:

• input buffers may be malformed or adversarial
• no panic paths should be reachable from malformed data
• acceptance must imply structural safety, never policy correctness

Testing strategy

• Positive fixture tests for valid v1 handoffs
• Negative tests for:
  • wrong magic/version
  • out-of-bounds offsets
  • integer overflow in table math
  • malformed entry size/count combinations
• Cross-repo compatibility tests (producer bytes match consumer decode)
• Determinism tests (same input bytes -> same parse result)

Dependencies

• External crates: none
• Internal dependencies: minimal; prefer no dependency where possible

See clean-room policy in ../docs/policies/no-external-code.md.

Status

Early development.

Protocol docs exist in docs/handoff; this crate is the implementation layer for those schemas. Current role constant set for root->services v1 is split as memd=1, vspaced=2, pagerd=3, procd=4 (>=1024 extension roles).

License

ISC. See LICENSE.