From 859db02616375f17c136492bd9ad9359690d3fe1 Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:29:22 -0500 Subject: [PATCH 1/6] uefi: Improve the feature list docstring section Use paragraphs instead of bullets, add `panic-on-logger-errors`, and mention `uefi-services` can be used to initialize the allocator and logger. --- uefi/src/lib.rs | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index f30646fc7..efecfcd5a 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -15,19 +15,28 @@ //! The `proto` module contains the standard UEFI protocols, which are normally provided //! by the various UEFI drivers and firmware layers. //! -//! ## Optional crate features: +//! ## Optional crate features //! -//! - `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library. -//! - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`). -//! - It is up to the user to provide a `#[global_allocator]`. -//! - `global_allocator`: implements a `#[global_allocator]` using UEFI functions. -//! - This allows you to use all abstractions from the `alloc` crate from the Rust standard library -//! during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory. -//! **This is optional**, so you can provide a custom `#[global_allocator]` as well. -//! - There's no guarantee of the efficiency of UEFI's allocator. -//! - `logger`: logging implementation for the standard [`log`] crate. -//! - Prints output to UEFI console. -//! - No buffering is done: this is not a high-performance logger. +//! - `alloc`: Enable functionality requiring the [`alloc`] crate from +//! the Rust standard library. For example, methods that return a +//! `Vec` rather than filling a statically-sized array. This requires +//! a global allocator; you can use the `global_allocator` feature or +//! provide your own. +//! - `global_allocator`: Implement a [global allocator] using UEFI +//! functions. This is a simple allocator that relies on the UEFI pool +//! allocator. You can choose to provide your own allocator instead of +//! using this feature, or no allocator at all if you don't need to +//! dynamically allocate any memory. +//! - `logger`: Logging implementation for the standard [`log`] crate +//! that prints output to the UEFI console. No buffering is done; this +//! is not a high-performance logger. +//! - `panic-on-logger-errors` (enabled by default): Panic if a text +//! output error occurs in the logger. +//! +//! The `global_allocator` and `logger` features require special +//! handling to perform initialization and tear-down. The +//! [`uefi-services`] crate provides an `init` method that takes care of +//! this. //! //! ## Adapting to local conditions //! @@ -36,6 +45,9 @@ //! //! For example, a PC with no network card might not contain a network driver, //! therefore all the network protocols will be unavailable. +//! +//! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc +//! [`uefi-services`]: https://crates.io/crates/uefi-services #![feature(abi_efiapi)] #![feature(maybe_uninit_slice)] From cc53255b0d3eee8c43864cff19eec18986db24fc Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:31:31 -0500 Subject: [PATCH 2/6] uefi: Simplify features list in README Link to the src/lib.rs file instead of listing out the optional features so that we don't have to worry about keeping the text in sync. --- uefi/README.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/uefi/README.md b/uefi/README.md index 2b75fd035..65fbb4536 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -24,22 +24,12 @@ Check out the [UEFI application template] for a quick start. ## Optional features -- `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library. - - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`). - - It is up to the user to provide a `#[global_allocator]`. -- `global_allocator`: implements a `#[global_allocator]` using UEFI functions. - - This allows you to use all abstractions from the `alloc` crate from the Rust standard library - during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory. - **This is optional**, so you can provide a custom `#[global_allocator]` as well. - - There's no guarantee of the efficiency of UEFI's allocator. -- `logger`: logging implementation for the standard [`log`] crate. - - Prints output to UEFI console. - - No buffering is done: this is not a high-performance logger. +This crate's features are described in [`src/lib.rs`]. See also the [`uefi-services`] crate, which provides a panic handler and initializes the `global_allocator` and `logger` features. -[`log`]: https://github.com/rust-lang-nursery/log +[`src/lib.rs`]: src/lib.rs [`uefi-services`]: https://crates.io/crates/uefi-services ## Documentation From cee3d77c2cdc8a0c4d3f4faf9b565a820bc72f9d Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:32:27 -0500 Subject: [PATCH 3/6] uefi-services: Add feature list to crate docstring --- uefi-services/src/lib.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/uefi-services/src/lib.rs b/uefi-services/src/lib.rs index 3fed88b7e..d430f8b7e 100644 --- a/uefi-services/src/lib.rs +++ b/uefi-services/src/lib.rs @@ -14,6 +14,16 @@ //! Library code can simply use global UEFI functions //! through the reference provided by `system_table`. //! +//! ## Optional crate features +//! +//! - `logger` (enabled by default): Initialize a global logger. +//! - `panic_handler` (enabled by default): Register a panic handler. A +//! panic handler must be provided for your program to compile, but +//! you can choose to provide your own if you don't want to use this +//! one. +//! - `qemu`: On x86_64, make qemu exit with code 3 if a panic +//! occurs. This feature assumes the program is running under QEMU. +//! //! [`exit_boot_services`]: uefi::table::SystemTable::exit_boot_services #![no_std] From 16e8f23a7a8b681cc4cf51a56886519ed112e989 Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:32:52 -0500 Subject: [PATCH 4/6] uefi-services: Link to feature list docstring in the README --- uefi-services/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/uefi-services/README.md b/uefi-services/README.md index dd8e1033f..885916dd4 100644 --- a/uefi-services/README.md +++ b/uefi-services/README.md @@ -9,3 +9,9 @@ a global allocator. `uefi-services` is part of the `uefi-rs` project. Please refer to for comprehensive documentation. + +## Optional features + +This crate's features are described in [`src/lib.rs`]. + +[`src/lib.rs`]: src/lib.rs From f12ad2853db54aa2560227c4ffc61d49bd13a37b Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:33:35 -0500 Subject: [PATCH 5/6] readme: Drop crate feature list The feature lists are covered in the crate docstrings now, and the crate READMEs link to that source as well. Drop the list here so we don't have to worry about keeping them in sync. --- README.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/README.md b/README.md index 9d8571bb4..69172582f 100644 --- a/README.md +++ b/README.md @@ -30,23 +30,9 @@ Check out [the UEFI application template](template) for a quick start. This project contains multiple sub-crates: -- `uefi` (top directory): defines the standard UEFI tables / interfaces. +- `uefi`: defines the standard UEFI tables / interfaces. The objective is to stay unopinionated and safely wrap most interfaces. - **Optional crate features:** - - - `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library. - - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`). - - It is up to the user to provide a `#[global_allocator]`. - - `global_allocator`: implements a `#[global_allocator]` using UEFI functions. - - This allows you to use all abstractions from the `alloc` crate from the Rust standard library - during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory. - **This is optional**, so you can provide a custom `#[global_allocator]` as well. - - There's no guarantee of the efficiency of UEFI's allocator. - - `logger`: logging implementation for the standard [`log`] crate. - - Prints output to UEFI console. - - No buffering is done: this is not a high-performance logger. - - `uefi-macros`: procedural macros that are used to derive some traits in `uefi`. - `uefi-services`: provides a panic handler, and initializes the `alloc` / `logger` features. From 2b0aaed34bf8e1042c9c2698ee72a2a13dc60de5 Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 26 Nov 2022 21:36:22 -0500 Subject: [PATCH 6/6] book: Drop crate features page This is covered by the uefi/uefi-services crate documention. Drop the list from here so we don't have to worry about keeping it in sync. --- book/src/SUMMARY.md | 1 - book/src/how_to/crate_features.md | 15 --------------- 2 files changed, 16 deletions(-) delete mode 100644 book/src/how_to/crate_features.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index bbd162689..90a59589b 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,7 +8,6 @@ - [How-to](how_to/introduction.md) - [Using Protocols](how_to/protocols.md) - [Drawing to the Screen](how_to/drawing.md) - - [Crate Features](how_to/crate_features.md) - [Concepts](concepts/introduction.md) - [Boot Stages](concepts/boot_stages.md) - [Tables](concepts/tables.md) diff --git a/book/src/how_to/crate_features.md b/book/src/how_to/crate_features.md deleted file mode 100644 index 47acdd799..000000000 --- a/book/src/how_to/crate_features.md +++ /dev/null @@ -1,15 +0,0 @@ -# Optional Crate Features - -There are several optional crate features provided by the `uefi` crate. - -- `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library. - - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`). - - It is up to the user to provide a `#[global allocator]`. -- `global_allocator`: implements a `#[global allocator]` using UEFI functions. - - This allows you to use all abstractions from the `alloc` crate from the Rust standard library - during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory. - **This is optional**, so you can provide a custom `#[global allocator]` as well. - - There's no guarantee of the efficiency of UEFI's allocator. -- `logger`: logging implementation for the standard [`log`] crate. - - Prints output to the UEFI boot services standard text output. - - No buffering is done: this is not a high-performance logger.