os_image_lens 0.1.0

Dependency-free ELF64 kernel image inspector and load-plan builder for Rust OS development.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# 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

```rust
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](LICENSE).