Skip to content

doc: add comprehensive About section to lib.rs [doc: 3/N] #1291

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 13, 2024
Merged

doc: add comprehensive About section to lib.rs [doc: 3/N] #1291

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cc142af
doc: fix heading level
phip1611 Aug 9, 2024
85d0321
doc: add section Terminology
phip1611 Aug 9, 2024
848fa2f
doc: streamline About section and rename to "Value-add"
phip1611 Aug 9, 2024
dbc7fd0
doc: enhance section "Supported Compiler Versions and Architectures"
phip1611 Aug 11, 2024
0d8d13a
doc: lib.rs: merge MSRV into Supported Compiler Versions section
phip1611 Aug 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions uefi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,17 @@ This crate makes it easy to develop Rust software that leverages **safe**,
![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)

## Value-add and Use Cases

`uefi` supports writing code for both pre- and post-exit boot services
epochs, but its true strength shines when you create UEFI images that heavily
interact with UEFI boot services. Still, you have the flexibility to just
integrate selected types and abstractions into your project, for example to
parse the UEFI memory map.

_Note that for producing UEFI images, you also need to use a corresponding
`uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._

For an introduction to the `uefi-rs` project and documentation, please refer to
our main [README].

Expand Down
50 changes: 39 additions & 11 deletions uefi/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,47 @@
//! important UEFI concepts. For more details of UEFI, see the latest [UEFI
//! Specification][spec].
//!
//! # Interaction with uefi services
//! # Value-add and Use Cases
//!
//! With this crate you can write code for the pre- and post-exit boot services
//! epochs. However, the `uefi` crate unfolds its true potential when
//! interacting with UEFI boot services.
//! `uefi` supports writing code for both pre- and post-exit boot services
//! epochs, but its true strength shines when you create UEFI images that heavily
//! interact with UEFI boot services. Still, you have the flexibility to just
//! integrate selected types and abstractions into your project, for example to
//! parse the UEFI memory map.
//!
//! ## Supported Architectures
//! _Note that for producing UEFI images, you also need to use a corresponding
//! `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._
//!
//! ## Example Use Cases
//!
//! This library significantly simplifies the process of creating **UEFI images**
//! by abstracting away much of the UEFI API complexity and by providing
//! convenient wrappers. When we mention UEFI images, we are talking about UEFI
//! applications, UEFI boot service drivers, and EFI runtime service drivers,
//! which typically have the `.efi` file extension. For instance, an UEFI
//! application could be an OS-specific loader, similar to _GRUB_ or _Limine_.
//!
//! Additionally, you can use this crate in non-UEFI images (such as a kernel
//! in ELF format) to perform tasks like parsing the UEFI memory map embedded in
//! the boot information provided by a bootloader. It also enables access to
//! UEFI runtime services from a non-UEFI image kernel.
//!
//! # Supported Compiler Versions and Architectures
//!
//! `uefi` works with stable Rust, but additional nightly-only features are
//! gated behind the `unstable` Cargo feature. Please find more information
//! about additional crate features below.
//!
//! `uefi` is compatible with all platforms that both the Rust compiler and
//! UEFI support, such as `i686`, `x86_64`, and `aarch64`. Please note that we
//! can't test all possible hardware/firmware/platform combinations in CI.
//!
//! ## MSRV
//! <!-- Keep in Sync with README! -->
//!
//! The minimum supported Rust version is currently 1.70.
//! Our policy is to support at least the past two stable releases.
//!
//! # Crate organisation
//!
//! The top-level module contains some of the most used types and macros,
Expand Down Expand Up @@ -86,12 +115,6 @@
//! Contributions in the form of a PR are also highly welcome. Check our
//! [contributing guide][contributing] for details.
//!
//! # MSRV
//! <!-- Keep in Sync with README! -->
//!
//! The minimum supported Rust version is currently 1.70.
//! Our policy is to support at least the past two stable releases.
//!
//! # License
//! <!-- Keep in Sync with README! -->
//!
Expand All @@ -101,6 +124,11 @@
//!
//! The full text of the license is available in the [license file][LICENSE].
//!
//! # Terminology
//!
//! Both "EFI" and "UEFI" can be used interchangeably, such as "UEFI image" or
//! "EFI image". We prefer "UEFI" in our crate and its documentation.
//!
//! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE
//! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
//! [UEFI]: https://uefi.org/
Expand Down