diff --git a/uefi/README.md b/uefi/README.md index 37ad9b40a..962fad270 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -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]. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 22e13860e..5caf2c905 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -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 +//! +//! +//! 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, @@ -86,12 +115,6 @@ //! Contributions in the form of a PR are also highly welcome. Check our //! [contributing guide][contributing] for details. //! -//! # MSRV -//! -//! -//! The minimum supported Rust version is currently 1.70. -//! Our policy is to support at least the past two stable releases. -//! //! # License //! //! @@ -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/