os_image_lens

Dependency-free, no_std-first ELF64 kernel image inspector and load-plan builder for Rust OS development.

os_image_lens takes a byte slice (&[u8]) and helps you answer, deterministically and safely:

• Is this a valid ELF64 image?
• What are the PT_LOAD segments?
• Which file ranges must be copied into memory?
• Which memory ranges must be zero-filled (BSS tail)?
• What is the overall virtual address span of loadable segments?

Design principles

• No dependencies: this crate does not depend on any external crate.
• no_std by default: host-side testing can be done with the std feature.
• Allocation-free: iterators stream program headers / load segments without allocating.
• Strict bounds checking: the parser never reads beyond the provided byte slice.
• No unsafe code: parsing is done via explicit byte decoding.

Quick example

use os_image_lens::{Elf64, LoadSegmentKind};

fn plan(bytes: &[u8]) -> Result<(), os_image_lens::Error> {
    let elf = Elf64::parse(bytes)?;
    elf.validate_for_loading()?;

    for seg in elf.load_segments() {
        let seg = seg?;

        match seg.kind() {
            LoadSegmentKind::CopyFromFile { file_range } => {
                let _segment_bytes = &bytes[file_range.start..file_range.end];
            }
            LoadSegmentKind::ZeroFill => {}
        }

        let _where_in_memory = seg.vaddr_range();
        let _to_zero = seg.zero_range();
        let _perms = seg.permissions();
    }

    Ok(())
}

Documentation

• docs/MANUAL.md: the ultra-detailed manual (concepts + API walkthrough).
• docs/QUICKSTART.md: minimal integration steps for bootloaders and kernels.
• docs/LOAD_PLAN.md: how to execute the load plan correctly.
• docs/ELF64_SPEC_SUMMARY.md: practical ELF64 subset used by this crate.
• docs/ERROR_MODEL.md: error taxonomy and how to react to errors.
• docs/NO_STD_AND_TESTING.md: no_std expectations and host-side tests.
• docs/SECURITY.md: threat model, fuzzing notes, and hardening guidance.
• docs/INTEGRATION_GUIDE.md: recommended patterns and common pitfalls.
• docs/CI_AND_RELEASE.md: CI, tags, crates.io publish, doc.rs notes.
• docs/FAQ.md: common questions and troubleshooting.

License

MIT. See LICENSE.