yggdrasil/yggdrasil-elf
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorder README/doc comment feature list

Browse Source
This commit is contained in:
Christopher Cole 2023-02-15 15:21:13 -08:00
parent db0c3938a0
commit 1181e6b70b
No known key found for this signature in database
GPG Key ID: 0AC856975983E9DB
2 changed files with 70 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
README.md
View File

@ -11,6 +11,41 @@ The `elf` crate provides a pure-safe-rust interface for reading ELF object files
# Capabilities # Capabilities
### ✨ Works in `no_std` environments ✨
This crate provides an elf parsing interface which does not allocate or use any std
features, so it can be used in `no_std` environments such as kernels and bootloaders.
The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface.
All core parsing functionality is the same!
### ✨ Endian-aware ✨
This crate handles translating between file and host endianness when
parsing the ELF contents and provides four endian parsing implementations
optimized to support the different common use-cases for an ELF parsing library.
Parsing is generic across the specifications and each trait impl represents a
specification that encapsulates an interface for parsing integers from some
set of allowed byte orderings.
* `AnyEndian`: Dynamically parsing either byte order at runtime based on the type of ELF object being parsed.
* `BigEndian`/`LittleEndian`: For tools that know they only want to parse a single given byte order known at compile time.
* `NativeEndian`: For tools that know they want to parse the same byte order as the compilation target's byte order.
When the limited specifications are used, errors are properly returned when asked to parse an ELF file
with an unexpected byte ordering.
### ✨ Zero-alloc parser ✨
This crate implements parsing in a way that avoids heap allocations. ELF structures
are parsed and stored on the stack and provided by patterns such as lazily parsed iterators
that yield stack allocated rust types, or lazily parsing tables that only parse out a particular
entry on table.get(index). The structures are copy-converted as needed from the underlying file
data into Rust's native struct representation.
### ✨ Fuzz Tested ✨
Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`).
Memory safety is a core goal, as is providing a safe interface that errors on bad data
over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are
returned when bad or corrupted ELF structures are encountered.
### ✨ Uses only safe interfaces ✨ ### ✨ Uses only safe interfaces ✨
With memory safety a core goal, this crate contains zero unsafe code blocks of With memory safety a core goal, this crate contains zero unsafe code blocks of
its own and only uses safe interface methods from core and std, so you can its own and only uses safe interface methods from core and std, so you can
@ -22,26 +57,6 @@ Note: I'd love to see this crate be enhanced further once rust provides safe tra
See: <https://github.com/rust-lang/project-safe-transmute> See: <https://github.com/rust-lang/project-safe-transmute>
### ✨ Fuzz Tested ✨
Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`).
Memory safety is a core goal, as is providing a safe interface that errors on bad data
over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are
returned when bad or corrupted ELF structures are encountered.
### ✨ Works in `no_std` environments ✨
This crate provides an elf parsing interface which does not allocate or use any std
features, so it can be used in `no_std` environments such as kernels and bootloaders.
The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface.
All core parsing functionality is the same!
### ✨ Zero-alloc parser ✨
This crate implements parsing in a way that avoids heap allocations. ELF structures
are parsed and stored on the stack and provided by patterns such as lazily parsed iterators
that yield stack allocated rust types, or lazily parsing tables that only parse out a particular
entry on table.get(index). The structures are copy-converted as needed from the underlying file
data into Rust's native struct representation.
### ✨ Some zero-copy interfaces ✨ ### ✨ Some zero-copy interfaces ✨
The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes. The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes.
@ -58,21 +73,6 @@ The `ParsingIterator`s are also nice in that you can easily zip/enumerate/filter
how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just
zip/collect them into another type so you only parse/endian-flip each entry once! zip/collect them into another type so you only parse/endian-flip each entry once!
### ✨ Endian-aware ✨
This crate handles translating between file and host endianness when
parsing the ELF contents and provides four endian parsing implementations
optimized to support the different common use-cases for an ELF parsing library.
Parsing is generic across the specifications and each trait impl represents a
specification that encapsulates an interface for parsing integers from some
set of allowed byte orderings.
* `AnyEndian`: Dynamically parsing either byte order at runtime based on the type of ELF object being parsed.
* `BigEndian`/`LittleEndian`: For tools that know they only want to parse a single given byte order known at compile time.
* `NativeEndian`: For tools that know they want to parse the same byte order as the compilation target's byte order.
When the limited specifications are used, errors are properly returned when asked to parse an ELF file
with an unexpected byte ordering.
### ✨ Stream-based lazy i/o interface ✨ ### ✨ Stream-based lazy i/o interface ✨
The `ElfStream` parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of The `ElfStream` parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of
file contents are read lazily on-demand based on what the user wants to parse. file contents are read lazily on-demand based on what the user wants to parse.

70
src/lib.rs
View File

@ -2,6 +2,41 @@
//! //!
//! # Capabilities //! # Capabilities
//! //!
//! ### ✨ Works in `no_std` environments ✨
//! This crate provides an elf parsing interface which does not allocate or use any std
//! features, so it can be used in `no_std` environments such as kernels and bootloaders.
//! The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface.
//! All core parsing functionality is the same!
//!
//! ### ✨ Endian-aware ✨
//! This crate handles translating between file and host endianness when
//! parsing the ELF contents and provides four endian parsing implementations
//! optimized to support the different common use-cases for an ELF parsing library.
//! Parsing is generic across the specifications and each trait impl represents a
//! specification that encapsulates an interface for parsing integers from some
//! set of allowed byte orderings.
//!
//! * [AnyEndian](endian::AnyEndian): Dynamically parsing either byte order at runtime based on the type of ELF object being parsed.
//! * [BigEndian](endian::BigEndian)/[LittleEndian](endian::LittleEndian): For tools that know they only want to parse a single given byte order known at compile time.
//! * [NativeEndian](type@endian::NativeEndian): For tools that know they want to parse the same byte order as the compilation target's byte order.
//!
//! When the limited specifications are used, errors are properly returned when asked to parse an ELF file
//! with an unexpected byte ordering.
//!
//! ### ✨ Zero-alloc parser ✨
//! This crate implements parsing in a way that avoids heap allocations. ELF structures
//! are parsed and stored on the stack and provided by patterns such as lazily parsed iterators
//! that yield stack allocated rust types, or lazily parsing tables that only parse out a particular
//! entry on table.get(index). The structures are copy-converted as needed from the underlying file
//! data into Rust's native struct representation.
//!
//! ### ✨ Fuzz Tested ✨
//! Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`).
//!
//! Memory safety is a core goal, as is providing a safe interface that errors on bad data
//! over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are
//! returned when bad or corrupted ELF structures are encountered.
//!
//! ### ✨ Uses only safe interfaces ✨ //! ### ✨ Uses only safe interfaces ✨
//! With memory safety a core goal, this crate contains zero unsafe code blocks //! With memory safety a core goal, this crate contains zero unsafe code blocks
//! of its own and only uses safe interface methods from core and std, so you can //! of its own and only uses safe interface methods from core and std, so you can
@ -13,26 +48,6 @@
//! //!
//! See: <https://github.com/rust-lang/project-safe-transmute> //! See: <https://github.com/rust-lang/project-safe-transmute>
//! //!
//! ### ✨ Fuzz Tested ✨
//! Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`).
//!
//! Memory safety is a core goal, as is providing a safe interface that errors on bad data
//! over crashing or panicking. Checked integer math is used where appropriate, and ParseErrors are
//! returned when bad or corrupted ELF structures are encountered.
//!
//! ### ✨ Works in `no_std` environments ✨
//! This crate provides an elf parsing interface which does not allocate or use any std
//! features, so it can be used in `no_std` environments such as kernels and bootloaders.
//! The no_std variant merely disables the additional stream-oriented `std:: Read + Seek` interface.
//! All core parsing functionality is the same!
//!
//! ### ✨ Zero-alloc parser ✨
//! This crate implements parsing in a way that avoids heap allocations. ELF structures
//! are parsed and stored on the stack and provided by patterns such as lazily parsed iterators
//! that yield stack allocated rust types, or lazily parsing tables that only parse out a particular
//! entry on table.get(index). The structures are copy-converted as needed from the underlying file
//! data into Rust's native struct representation.
//!
//! ### ✨ Some zero-copy interfaces ✨ //! ### ✨ Some zero-copy interfaces ✨
//! The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes. //! The StringTable, for instance, yields `&[u8]` and `&str` backed by the raw string table bytes.
//! //!
@ -49,21 +64,6 @@
//! how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just //! how you wish. Do you know that you want to do multiple passes over pairs from different tables? Just
//! zip/collect them into another type so you only parse/endian-flip each entry once! //! zip/collect them into another type so you only parse/endian-flip each entry once!
//! //!
//! ### ✨ Endian-aware ✨
//! This crate handles translating between file and host endianness when
//! parsing the ELF contents and provides four endian parsing implementations
//! optimized to support the different common use-cases for an ELF parsing library.
//! Parsing is generic across the specifications and each trait impl represents a
//! specification that encapsulates an interface for parsing integers from some
//! set of allowed byte orderings.
//!
//! * [AnyEndian](endian::AnyEndian): Dynamically parsing either byte order at runtime based on the type of ELF object being parsed.
//! * [BigEndian](endian::BigEndian)/[LittleEndian](endian::LittleEndian): For tools that know they only want to parse a single given byte order known at compile time.
//! * [NativeEndian](type@endian::NativeEndian): For tools that know they want to parse the same byte order as the compilation target's byte order.
//!
//! When the limited specifications are used, errors are properly returned when asked to parse an ELF file
//! with an unexpected byte ordering.
//!
//! ### ✨ Stream-based lazy i/o interface ✨ //! ### ✨ Stream-based lazy i/o interface ✨
//! The [ElfStream] parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of //! The [ElfStream] parser type takes a `std:: Read + Seek` (such as `std::fs::File`) where ranges of
//! file contents are read lazily on-demand based on what the user wants to parse. //! file contents are read lazily on-demand based on what the user wants to parse.