Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit b35ffb8

Browse files
Merge pull request #589 from nicholasbishop/bishop-fewer-feature-lists
Clean up crate feature list documentation
2 parents 235bc84 + 2b0aaed commit b35ffb8

File tree

7 files changed

+43
-55
lines changed

7 files changed

+43
-55
lines changed

‎README.md

Lines changed: 1 addition & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -30,23 +30,9 @@ Check out [the UEFI application template](template) for a quick start.
3030

3131
This project contains multiple sub-crates:
3232

33-
- `uefi` (top directory): defines the standard UEFI tables / interfaces.
33+
- `uefi`: defines the standard UEFI tables / interfaces.
3434
The objective is to stay unopinionated and safely wrap most interfaces.
3535

36-
**Optional crate features:**
37-
38-
- `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
39-
- For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
40-
- It is up to the user to provide a `#[global_allocator]`.
41-
- `global_allocator`: implements a `#[global_allocator]` using UEFI functions.
42-
- This allows you to use all abstractions from the `alloc` crate from the Rust standard library
43-
during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
44-
**This is optional**, so you can provide a custom `#[global_allocator]` as well.
45-
- There's no guarantee of the efficiency of UEFI's allocator.
46-
- `logger`: logging implementation for the standard [`log`] crate.
47-
- Prints output to UEFI console.
48-
- No buffering is done: this is not a high-performance logger.
49-
5036
- `uefi-macros`: procedural macros that are used to derive some traits in `uefi`.
5137

5238
- `uefi-services`: provides a panic handler, and initializes the `alloc` / `logger` features.

‎book/src/SUMMARY.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
- [How-to](how_to/introduction.md)
99
- [Using Protocols](how_to/protocols.md)
1010
- [Drawing to the Screen](how_to/drawing.md)
11-
- [Crate Features](how_to/crate_features.md)
1211
- [Concepts](concepts/introduction.md)
1312
- [Boot Stages](concepts/boot_stages.md)
1413
- [Tables](concepts/tables.md)

‎book/src/how_to/crate_features.md

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎uefi-services/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,9 @@ a global allocator.
99

1010
`uefi-services` is part of the `uefi-rs` project. Please refer to
1111
<https://github.com/rust-osdev/uefi-rs/> for comprehensive documentation.
12+
13+
## Optional features
14+
15+
This crate's features are described in [`src/lib.rs`].
16+
17+
[`src/lib.rs`]: src/lib.rs

‎uefi-services/src/lib.rs

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,16 @@
1414
//! Library code can simply use global UEFI functions
1515
//! through the reference provided by `system_table`.
1616
//!
17+
//! ## Optional crate features
18+
//!
19+
//! - `logger` (enabled by default): Initialize a global logger.
20+
//! - `panic_handler` (enabled by default): Register a panic handler. A
21+
//! panic handler must be provided for your program to compile, but
22+
//! you can choose to provide your own if you don't want to use this
23+
//! one.
24+
//! - `qemu`: On x86_64, make qemu exit with code 3 if a panic
25+
//! occurs. This feature assumes the program is running under QEMU.
26+
//!
1727
//! [`exit_boot_services`]: uefi::table::SystemTable::exit_boot_services
1828
1929
#![no_std]

‎uefi/README.md

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,22 +24,12 @@ Check out the [UEFI application template] for a quick start.
2424

2525
## Optional features
2626

27-
- `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
28-
- For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
29-
- It is up to the user to provide a `#[global_allocator]`.
30-
- `global_allocator`: implements a `#[global_allocator]` using UEFI functions.
31-
- This allows you to use all abstractions from the `alloc` crate from the Rust standard library
32-
during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
33-
**This is optional**, so you can provide a custom `#[global_allocator]` as well.
34-
- There's no guarantee of the efficiency of UEFI's allocator.
35-
- `logger`: logging implementation for the standard [`log`] crate.
36-
- Prints output to UEFI console.
37-
- No buffering is done: this is not a high-performance logger.
27+
This crate's features are described in [`src/lib.rs`].
3828

3929
See also the [`uefi-services`] crate, which provides a panic handler and
4030
initializes the `global_allocator` and `logger` features.
4131

42-
[`log`]: https://github.com/rust-lang-nursery/log
32+
[`src/lib.rs`]: src/lib.rs
4333
[`uefi-services`]: https://crates.io/crates/uefi-services
4434

4535
## Documentation

‎uefi/src/lib.rs

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,28 @@
1515
//! The `proto` module contains the standard UEFI protocols, which are normally provided
1616
//! by the various UEFI drivers and firmware layers.
1717
//!
18-
//! ## Optional crate features:
18+
//! ## Optional crate features
1919
//!
20-
//! - `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
21-
//! - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
22-
//! - It is up to the user to provide a `#[global_allocator]`.
23-
//! - `global_allocator`: implements a `#[global_allocator]` using UEFI functions.
24-
//! - This allows you to use all abstractions from the `alloc` crate from the Rust standard library
25-
//! during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
26-
//! **This is optional**, so you can provide a custom `#[global_allocator]` as well.
27-
//! - There's no guarantee of the efficiency of UEFI's allocator.
28-
//! - `logger`: logging implementation for the standard [`log`] crate.
29-
//! - Prints output to UEFI console.
30-
//! - No buffering is done: this is not a high-performance logger.
20+
//! - `alloc`: Enable functionality requiring the [`alloc`] crate from
21+
//! the Rust standard library. For example, methods that return a
22+
//! `Vec` rather than filling a statically-sized array. This requires
23+
//! a global allocator; you can use the `global_allocator` feature or
24+
//! provide your own.
25+
//! - `global_allocator`: Implement a [global allocator] using UEFI
26+
//! functions. This is a simple allocator that relies on the UEFI pool
27+
//! allocator. You can choose to provide your own allocator instead of
28+
//! using this feature, or no allocator at all if you don't need to
29+
//! dynamically allocate any memory.
30+
//! - `logger`: Logging implementation for the standard [`log`] crate
31+
//! that prints output to the UEFI console. No buffering is done; this
32+
//! is not a high-performance logger.
33+
//! - `panic-on-logger-errors` (enabled by default): Panic if a text
34+
//! output error occurs in the logger.
35+
//!
36+
//! The `global_allocator` and `logger` features require special
37+
//! handling to perform initialization and tear-down. The
38+
//! [`uefi-services`] crate provides an `init` method that takes care of
39+
//! this.
3140
//!
3241
//! ## Adapting to local conditions
3342
//!
@@ -36,6 +45,9 @@
3645
//!
3746
//! For example, a PC with no network card might not contain a network driver,
3847
//! therefore all the network protocols will be unavailable.
48+
//!
49+
//! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
50+
//! [`uefi-services`]: https://crates.io/crates/uefi-services
3951
4052
#![feature(abi_efiapi)]
4153
#![feature(maybe_uninit_slice)]

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /