Skip to content

Commit 64686e8

Browse files
phip1611phip1611
committed
doc: reorganize
This is a massive re-organization of the existing documentation. The main goal is to streamline what is provided in the README.md and what is in the lib.rs file. I think, we need to answer some more questions and to redistribute these answers to where users most naturally expect documentation. When in doubt, lib.rs should be preferred and the README should forward to docs.rs. This resolves also many inconsistencies along the way, remove (IMHO) unnecessary pieces, and adds relevant (but yet missing) information.
1 parent 479868f commit 64686e8

File tree

4 files changed

+151
-84
lines changed

4 files changed

+151
-84
lines changed

‎README.md

+22-47
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,42 @@
11
# uefi-rs
22

3+
Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].
4+
35
[![Crates.io](https://img.shields.io/crates/v/uefi)](https://crates.io/crates/uefi)
46
[![Docs.rs](https://docs.rs/uefi/badge.svg)](https://docs.rs/uefi)
57
![License](https://img.shields.io/github/license/rust-osdev/uefi-rs)
68
![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
79
![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
810

9-
## Description
11+
## TL;DR
12+
13+
Develop Rust software that leverages **safe**, **convenient**, and
14+
**performant** abstractions for [UEFI] functionality.
15+
16+
## API and User Documentation
1017

11-
[UEFI] started as the successor firmware to the BIOS in x86 space and developed
12-
to a universal firmware specification for various platforms, such as ARM. It
13-
provides an early boot environment with a variety of [specified][spec]
14-
ready-to-use "high-level" functionality, such as accessing disks or the network.
15-
EFI images, the files that can be loaded by an UEFI environment, can leverage
16-
these abstractions to extend the functionality in form of additional drivers,
17-
OS-specific bootloaders, or different kind of low-level applications.
18+
The main contribution of this project is the `uefi` crate. Please refer to
19+
[`uefi/src/lib.rs`](./uefi/src/lib.rs) (see on [docs.rs](https://docs.rs/uefi))
20+
for comprehensive documentation. This includes an about section, API/user
21+
documentation, the MSRV, example use cases, and pointers to further
22+
documentation.
1823

19-
Our mission is to provide **safe** and **performant** wrappers for UEFI
20-
interfaces, and allow developers to write idiomatic Rust code.
24+
## Repository Structure
2125

2226
This repository provides various crates:
2327

24-
- `uefi-raw`: Raw Rust UEFI bindings for basic structures and functions.
25-
- `uefi`: High-level wrapper around various low-level UEFI APIs. \
28+
- [`uefi-raw`](/uefi-raw/README.md): Raw Rust UEFI bindings for basic structures and functions.
29+
- [`uefi`](/uefi/README.md): High-level wrapper around various low-level UEFI APIs. \
2630
Offers various optional features for typical Rust convenience, such as a
2731
Logger and an Allocator. (_This is what you are usually looking for!_)
28-
- `uefi-macros`: Helper macros. Used by `uefi`.
29-
30-
31-
You can use the abstractions for example to:
32+
This is the **main contribution** of this project.
33+
- [`uefi-macros`](/uefi-macros/README.md): Helper macros used by `uefi` .
3234

33-
- create OS-specific loaders and leverage UEFI boot service
34-
- access UEFI runtime services from an OS
35-
36-
All crates are compatible with all platforms that both the Rust compiler and
37-
UEFI support, such as `i686`, `x86_64`, and `aarch64`). Please note that we
38-
can't test all possible hardware/firmware/platform combinations.
39-
40-
[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
4135

4236
![UEFI App running in QEMU](https://imgur.com/SFPSVuO.png)
4337
Screenshot of an application running in QEMU on an UEFI firmware that leverages
4438
our Rust library.
4539

46-
## User Documentation
47-
48-
<!-- KEEP IN SYNC WITH uefi/README -->
49-
50-
For a quick start, please check out [the UEFI application template](template).
51-
52-
The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
53-
UEFI concepts. Reference documentation for the various crates can be found on
54-
[docs.rs]:
55-
56-
- [docs.rs/uefi](https://docs.rs/uefi)
57-
- [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
58-
- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
59-
60-
For additional information, refer to the [UEFI specification][spec].
61-
62-
[spec]: https://uefi.org/specs/UEFI/2.10
63-
[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD
64-
[docs.rs]: https://docs.rs
65-
66-
### MSRV
67-
68-
See the [uefi package's README](uefi/README.md#MSRV).
6940

7041
## Developer Guide
7142

@@ -136,3 +107,7 @@ This license allows you to use the crate in proprietary programs, but any
136107
modifications to the files must be open-sourced.
137108

138109
The full text of the license is available in the [license file](LICENSE).
110+
111+
112+
113+
[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface

‎uefi/Cargo.toml

+4-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22
name = "uefi"
33
version = "0.29.0"
44
readme = "README.md"
5-
description = "Safe and easy-to-use wrapper for building UEFI apps."
5+
description = """
6+
Develop Rust software that leverages safe, convenient, and performant
7+
abstractions for UEFI functionality.
8+
"""
69

710
authors.workspace = true
811
categories.workspace = true

‎uefi/README.md

+18-27
Original file line numberDiff line numberDiff line change
@@ -6,44 +6,35 @@
66
![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
77
![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
88

9+
## TL;DR
910

10-
For an introduction to the `uefi-rs` project and documentation, please refer to
11-
our main [README].
11+
Develop Rust software that leverages **safe**, **convenient**, and
12+
**performant** abstractions for [UEFI] functionality.
1213

13-
[README]: https://github.com/rust-osdev/uefi-rs/blob/main/README.md
14+
## About
1415

15-
## Optional features
16+
With `uefi`, you have the flexibility to just integrate selected types and
17+
abstractions into your project or to effortlessly create complete EFI
18+
images, addressing the entire spectrum of your development needs.
1619

17-
This crate's features are described in [`src/lib.rs`].
20+
`uefi` works with stable Rust, but additional nightly-only features are
21+
gated behind an `unstable` Cargo feature flag.
1822

19-
[`src/lib.rs`]: src/lib.rs
23+
## Documentation
2024

21-
## User Documentation
25+
Please refer to [`uefi/src/lib.rs`](./src/lib.rs)
26+
(see on [docs.rs](https://docs.rs/uefi)) for comprehensive documentation.
27+
This includes an about section, API/user documentation, the MSRV, example
28+
use cases, and pointers to further documentation.
2229

23-
<!-- KEEP IN SYNC WITH MAIN README -->
24-
25-
For a quick start, please check out [the UEFI application template](template).
26-
27-
The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
28-
UEFI concepts. Reference documentation for the various crates can be found on
29-
[docs.rs]:
30-
31-
- [docs.rs/uefi](https://docs.rs/uefi)
32-
- [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
33-
- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
34-
35-
[spec]: http://www.uefi.org/specifications
36-
[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD
30+
For an introduction to the `uefi-rs` project and this repository, please refer
31+
to our main [README](/README.md).
3732

3833
## MSRV
3934

40-
The minimum supported Rust version is currently 1.70.
35+
<!-- Keep in Sync with lib.rs! -->
4136

37+
The minimum supported Rust version is currently 1.70.
4238
Our policy is to support at least the past two stable releases.
4339

44-
## License
45-
46-
The code in this repository is licensed under the Mozilla Public License 2.
47-
This license allows you to use the crate in proprietary programs, but any modifications to the files must be open-sourced.
4840

49-
The full text of the license is available in the [license file](LICENSE).

‎uefi/src/lib.rs

+107-9
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,87 @@
11
//! Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].
22
//!
3-
//! See the [Rust UEFI Book] for a tutorial, how-tos, and overviews of some
4-
//! important UEFI concepts. For more details of UEFI, see the latest [UEFI
5-
//! Specification][spec].
3+
//! # TL;DR
64
//!
7-
//! Feel free to file bug reports and questions in our [issue tracker], and [PR
8-
//! contributions][contributing] are also welcome!
5+
//! Develop Rust software that leverages **safe**, **convenient**, and
6+
//! **performant** abstractions for [UEFI] functionality.
7+
//!
8+
//! # About
9+
//!
10+
//! With `uefi`, you have the flexibility to just integrate selected types and
11+
//! abstractions into your project or to effortlessly create complete EFI
12+
//! images, addressing the entire spectrum of your development needs.
13+
//!
14+
//! `uefi` works with stable Rust, but additional nightly-only features are
15+
//! gated behind an `unstable` Cargo feature flag.
916
//!
10-
//! # Interaction with uefi services
17+
//! ## Example Use Cases
1118
//!
1219
//! With this crate you can write code for the pre- and post-exit boot services
13-
//! epochs. However, the `uefi` crate unfolds its true potential when
14-
//! interacting with UEFI boot services.
20+
//! epochs. However, the `uefi` crate unfolds its true potential when crafting
21+
//! EFI images interacting with UEFI boot services and eventually exiting them.
22+
//!
23+
//! By EFI images (`image.efi`), we are referring to EFI applications, EFI
24+
//! boot service drivers, and EFI runtime service drivers. An EFI application
25+
//! might be your OS-specific loader technically similar to _GRUB_ or _Limine_.
26+
//!
27+
//! You can also use this crate to parse the UEFI memory map when a bootloader,
28+
//! such as _GRUB_ or _Limine_, passed the UEFI memory map as part of the
29+
//! corresponding boot information to your kernel, or to access runtime services
30+
//! from your kernel. Hence, when you also use utilize `uefi` also in ELF
31+
//! binaries and are not limited to EFI images.
32+
//!
33+
//! ## Supported Architectures
34+
//!
35+
//! `uefi` is compatible with all platforms that both the Rust compiler and
36+
//! UEFI support, such as `i686`, `x86_64`, and `aarch64`). Please note that we
37+
//! can't test all possible hardware/firmware/platform combinations in CI.
38+
//!
39+
//! # API/User Documentation, Documentation Structure, and other Resources
40+
//!
41+
//! In this crate documentation, you find a technical API documentation
42+
//! including various code examples.
43+
//!
44+
//! For a TL;DR quick start with an example on how to create your own EFI
45+
//! application, please check out [the UEFI application template][template]. The
46+
//! [Rust UEFI Book] is a more beginner-friendly tutorial with How-Tos, and
47+
//! overviews of some important UEFI concepts and the abstractions provided by
48+
//! this library. This
49+
//!
50+
//! For more details of UEFI, see the latest [UEFI Specification][spec].
51+
//!
52+
//! # Comparison to other Projects in the Ecosystem
53+
//!
54+
//! ## Rust `std` implementation
55+
//!
56+
//! There is an ongoing effort for a `std` [implementation of the Rust standard
57+
//! library](https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html),
58+
//! that is yet far from being mature. As of Mid-2024, we recommend to use our
59+
//! `uefi` library in a `no_std` binary to create EFI images.
60+
//!
61+
//! We will closely monitor the situation and update the documentation
62+
//! accordingly, once the `std` implementation is more mature.
1563
//!
16-
//! # Crate organisation
64+
//! ## `r-efi`
65+
//!
66+
//! Raw UEFI bindings without high-level convenience similar to our `uefi-raw`
67+
//! crate, which is part of this project, but more feature-complete. It
68+
//! targets a lower-level than our `uefi` crate does.
69+
//!
70+
//! # Library structure & Tips
1771
//!
1872
//! The top-level module contains some of the most used types and macros,
1973
//! including the [`Handle`] and [`Result`] types, the [`CStr16`] and
2074
//! [`CString16`] types for working with UCS-2 strings, and the [`entry`] and
2175
//! [`guid`] macros.
2276
//!
77+
//! ## UEFI Strings
78+
//!
79+
//! Rust string literals are UTF-8 encoded and thus, not compatible with most
80+
//! UEFI interfaces. We provide [`CStr16`] and [`CString16`] for proper working
81+
//! with UCS-2 strings, including various transformation functions from standard
82+
//! Rust strings. You can use [`ctr16!`] to create UCS-2 string literals at
83+
//! compile time.
84+
//!
2385
//! ## Tables
2486
//!
2587
//! The [`SystemTable`] provides access to almost everything in UEFI. It comes
@@ -73,15 +135,51 @@
73135
//! only unfold their potential when you invoke `uefi::helpers::init` as soon
74136
//! as possible in your application.
75137
//!
138+
//! # Discuss and Contribute
139+
//!
140+
//! Feel free to file bug reports and questions in our [issue tracker], and [PR
141+
//! contributions][contributing] are also welcome!
142+
//!
143+
//! You can discuss with us in our [Zulip].
144+
//!
145+
//! # MSRV
146+
//! <!-- Keep in Sync with README! -->
147+
//!
148+
//! The minimum supported Rust version is currently 1.70.
149+
//! Our policy is to support at least the past two stable releases.
150+
//!
151+
//! # License
152+
//! <!-- Keep in Sync with README! -->
153+
//!
154+
//! The code in this repository is licensed under the Mozilla Public License 2.
155+
//! This license allows you to use the crate in proprietary programs, but any
156+
//! modifications to the files must be open-sourced.
157+
//!
158+
//! The full text of the license is available in the [license file][LICENSE].
159+
//!
160+
//! # Trivia and Background
161+
//!
162+
//! [UEFI] started as the successor firmware to the BIOS in x86 space and developed
163+
//! to a universal firmware specification for various platforms, such as ARM. It
164+
//! provides an early boot environment with a variety of [specified][spec]
165+
//! ready-to-use "high-level" functionality, such as accessing disks or the network.
166+
//! EFI images, the files that can be loaded by an UEFI environment, can leverage
167+
//! these abstractions to extend the functionality in form of additional drivers,
168+
//! OS-specific bootloaders, or different kind of low-level applications.
169+
//!
170+
//! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE
76171
//! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
77172
//! [UEFI]: https://uefi.org/
173+
//! [Zulip]: https://rust-osdev.zulipchat.com/
78174
//! [`BootServices`]: table::boot::BootServices
79175
//! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
80176
//! [`SystemTable`]: table::SystemTable
177+
//! [`ctr16!`]: crate::cstr16
81178
//! [`unsafe_protocol`]: proto::unsafe_protocol
82179
//! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md
83180
//! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues
84181
//! [spec]: https://uefi.org/specifications
182+
//! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template
85183
//! [unstable features]: https://doc.rust-lang.org/unstable-book/
86184
87185
#![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))]

0 commit comments

Comments
 (0)