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. 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. 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 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] 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 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)]