lib-elf

lib-elf is a small, validation-first ELF64 parser for the EriX project, written in Rust.

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, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX ELF library. Its purpose in EriX is to provide reusable ELF primitives and contracts to EriX components.

Functionally, it exposes the ELF APIs, validation tests, and documentation used by dependent repositories. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• expose the lib-elf crate API for ELF behavior used by dependent components
• keep data formats, constants, and validation helpers documented and tested
• provide no-alloc static executable load-plan validation for early loaders
• preserve clean-room, no-external-crate implementation boundaries
• maintain compatibility expectations for downstream repositories

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.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Example (intended usage)

use lib_elf::{build_static_load_plan_into, StaticLoadSegment, StaticLoadTarget};

fn inspect(
    bytes: &[u8],
    segment_storage: &mut [StaticLoadSegment],
) -> Result<(), lib_elf::Error> {
    let plan = build_static_load_plan_into(
        bytes,
        StaticLoadTarget::erix_x86_64_native(),
        segment_storage,
    )?;
    assert!(plan.entry >= plan.image_start && plan.entry < plan.image_end);
    Ok(())
}

Elf64 parses and validates the complete program-header table in place, then produces LoadSegment values through a borrowed iterator without retaining a header vector. This parser/iterator API is available with default features disabled. The default alloc feature adds only owned load-plan convenience. Early system components can use build_static_load_plan_into with caller-provided segment storage. The slice length is the capacity: the library imposes no separate segment ceiling, validates the complete image before mutating the slice, and reports exact required and available entry counts through Error::StorageExhausted.

The filesystem-loader closure uses this no-alloc load-plan API in loaderd to validate disk-backed static bootstrap fixtures before procd materializes the process image. Dynamic root-task boot uses the same allocation-free Elf64 parser to admit native ET_DYN PIE service images so the bootloader can describe a dynamic rootd module while the kernel remains responsible for catalog relocation and seal policy.

The static executable ABI accepts ELF64 little-endian ET_EXEC files tagged with either System V OSABI or the GNU/Linux OSABI byte emitted by some no-std service link steps. This is a parser compatibility rule only; it does not add dynamic linking or ambient loader authority.

Testing strategy

This repo prefers deterministic, authored tests:

• Hand-authored fixtures (small ELF binaries built as part of the workspace or encoded as byte arrays).
• Negative tests for each validation rule (bad magic, truncated headers, out-of-bounds segments, overflow cases, etc.).
• Optional internal mutation harnesses (randomized byte flips) as a smoke test, without relying on external fuzzing infrastructure.

Repository layout

• src/

  • lib.rs — public API surface
  • error.rs — error types
  • elf64/ — internal parsing/validation modules
  • elf_tests_core.rs and elf_tests_load.rs — conformance and regression tests

• docs/

  • api-intent.md (if/when needed)

Governance Principles

lib-elf governance is scoped to reusable ELF contracts shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented APIs rather than component-specific policy.
• It keeps wire formats, constants, parsers, and validation helpers deterministic and testable.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• Breaking API or format changes require coordinated updates in every dependent repository.

Library Boundaries

• lib-elf carries no runtime authority by itself; authority is held by callers that use the library.
• The crate must not hide ambient I/O, allocation policy, or service discovery behind helper APIs.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.