From cc142affb916682f9e348e57480993d8071048df Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Fri, 9 Aug 2024 11:42:51 +0200 Subject: [PATCH 1/5] doc: fix heading level --- uefi/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 22e13860e..36a7935cd 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -13,7 +13,7 @@ //! epochs. However, the `uefi` crate unfolds its true potential when //! interacting with UEFI boot services. //! -//! ## Supported Architectures +//! # Supported Architectures //! //! `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 From 85d03213ff165be8872a4bad754155476174df1f Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Fri, 9 Aug 2024 11:43:47 +0200 Subject: [PATCH 2/5] doc: add section Terminology --- uefi/src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 36a7935cd..e290f589c 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -101,6 +101,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/ From 848fa2f2c93d40d5e0bc0ded29d56c8a21c5c2ad Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Fri, 9 Aug 2024 12:49:47 +0200 Subject: [PATCH 3/5] doc: streamline About section and rename to "Value-add" --- uefi/README.md | 11 +++++++++++ uefi/src/lib.rs | 29 ++++++++++++++++++++++++----- 2 files changed, 35 insertions(+), 5 deletions(-) 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 e290f589c..a7297d86c 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -7,11 +7,30 @@ //! important UEFI concepts. For more details of UEFI, see the latest [UEFI //! Specification][spec]. //! -//! # Interaction with uefi services -//! -//! 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. +//! # 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`._ +//! +//! ## 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 Architectures //! From dbc7fd074cac9448a95a020c43ae56a8871f82c9 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 11 Aug 2024 13:29:15 +0200 Subject: [PATCH 4/5] doc: enhance section "Supported Compiler Versions and Architectures" --- uefi/src/lib.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index a7297d86c..8b2df0e72 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -32,7 +32,11 @@ //! the boot information provided by a bootloader. It also enables access to //! UEFI runtime services from a non-UEFI image kernel. //! -//! # Supported Architectures +//! # 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 From 0d8d13a5b8c12a9db1c97a085a3c472cfcc3749e Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 11 Aug 2024 13:34:58 +0200 Subject: [PATCH 5/5] doc: lib.rs: merge MSRV into Supported Compiler Versions section --- uefi/src/lib.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 8b2df0e72..5caf2c905 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -42,6 +42,12 @@ //! 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, @@ -109,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 //! //!