Merge pull request #589 from nicholasbishop/bishop-fewer-feature-lists

Clean up crate feature list documentation

Author: phip1611

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.

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)

book/src/how_to/crate_features.md

@@ -9,3 +9,9 @@ a global allocator.
 
 `uefi-services` is part of the `uefi-rs` project. Please refer to
 <https://github.com/rust-osdev/uefi-rs/> for comprehensive documentation.
+
+## Optional features
+
+This crate's features are described in [`src/lib.rs`].
+  
+[`src/lib.rs`]: src/lib.rs

uefi-services/README.md

@@ -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]

uefi-services/src/lib.rs

@@ -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

uefi/README.md

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