Skip to content

doc: massive overhaul of documentation #1264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 13 commits into from
Closed

doc: massive overhaul of documentation #1264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
79c048a
uefi: remove documentation about already removed feature
phip1611 Jul 28, 2024
676c585
doc: unified new TL;DR/description entry
phip1611 Jul 30, 2024
27ec946
doc: add "About this Document"
phip1611 Jul 30, 2024
d85b4c9
doc: move background info to lib.rs
phip1611 Jul 30, 2024
9f9e5ca
doc: streamline sections Contributing, MSRV, and License
phip1611 Jul 30, 2024
505e70f
doc: add "About" section
phip1611 Jul 30, 2024
e46e74a
doc: extend About section with Example Use Cases
phip1611 Jul 30, 2024
02bc2cf
doc: add Supported Architectures
phip1611 Jul 30, 2024
52954f4
doc: add "Comparison to other Projects in the Ecosystem"
phip1611 Jul 30, 2024
837fe5c
doc: add "API/User Documentation, Documentation Structure, and other …
phip1611 Jul 30, 2024
b9829d7
doc: Crate organization -> Library Structure & Tips
phip1611 Jul 30, 2024
e0fde84
doc: reorder links alphabetically in lib.rs
phip1611 Jul 30, 2024
5c9343f
doc: final streamlining of README files
phip1611 Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 30 additions & 70 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,90 +1,44 @@
# uefi-rs

Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].

[![Crates.io](https://img.shields.io/crates/v/uefi)](https://crates.io/crates/uefi)
[![Docs.rs](https://docs.rs/uefi/badge.svg)](https://docs.rs/uefi)
![License](https://img.shields.io/github/license/rust-osdev/uefi-rs)
![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)

## Description

[UEFI] started as the successor firmware to the BIOS in x86 space and developed
to a universal firmware specification for various platforms, such as ARM. It
provides an early boot environment with a variety of [specified][spec]
ready-to-use "high-level" functionality, such as accessing disks or the network.
EFI images, the files that can be loaded by an UEFI environment, can leverage
these abstractions to extend the functionality in form of additional drivers,
OS-specific bootloaders, or different kind of low-level applications.

Our mission is to provide **safe** and **performant** wrappers for UEFI
interfaces, and allow developers to write idiomatic Rust code.

This repository provides various crates:

- `uefi-raw`: Raw Rust UEFI bindings for basic structures and functions.
- `uefi`: High-level wrapper around various low-level UEFI APIs. \
Offers various optional features for typical Rust convenience, such as a
Logger and an Allocator. (_This is what you are usually looking for!_)
- `uefi-macros`: Helper macros. Used by `uefi`.
## TL;DR
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I think we should drop the tl;dr header here since the section is just one sentence. Have this content come directly after the "Rusty wrapper for the Unified Extensible Firmware Interface." sentence.


Develop Rust software that leverages **safe**, **convenient**, and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: For clarity I would add a few words at the start of the sentence like "This crate makes it easy to develop Rust software [..].". Makes it clearer that we aren't necessarily the ones making the safe/convenient/performant software, but rather we're helping users of the crate do that.

**performant** abstractions for [UEFI] functionality.

You can use the abstractions for example to:
## API and User Documentation

- create OS-specific loaders and leverage UEFI boot service
- access UEFI runtime services from an OS

All crates are compatible with all platforms that both the Rust compiler and
UEFI support, such as `i686`, `x86_64`, and `aarch64`). Please note that we
can't test all possible hardware/firmware/platform combinations.

[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
The main contribution of this project is the `uefi` crate.
Please refer to [docs.rs](https://docs.rs/uefi) for comprehensive documentation
of the **latest stable release**. The latest not necessarily yet published
documentation can be found in [`src/lib.rs`](./uefi/src/lib.rs), which can also
be locally build by running `$ cargo xtask doc --open`.

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

## User Documentation

<!-- KEEP IN SYNC WITH uefi/README -->

For a quick start, please check out [the UEFI application template](template).

The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
UEFI concepts. Reference documentation for the various crates can be found on
[docs.rs]:

- [docs.rs/uefi](https://docs.rs/uefi)
- [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)

For additional information, refer to the [UEFI specification][spec].

[spec]: https://uefi.org/specs/UEFI/2.10
[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD
[docs.rs]: https://docs.rs

### MSRV

See the [uefi package's README](uefi/README.md#MSRV).

## Developer Guide

### Project structure

This project contains multiple sub-crates:
### Repository Structure

- `uefi`: defines the standard UEFI tables / interfaces.
The objective is to stay unopinionated and safely wrap most interfaces.
Additional opinionated features (such as a Logger) are feature-gated.

- `uefi-macros`: procedural macros that are used to derive some traits
in `uefi`.
This repository provides various crates:

- `uefi-raw`: raw types that closely match the definitions in the UEFI
Specification. Safe wrappers for these types are provided by the `uefi`
crate. The raw types are suitable for implementing UEFI firmware.
- [`uefi-raw`](/uefi-raw/README.md): Raw Rust UEFI bindings for basic structures and functions.
- [`uefi`](/uefi/README.md): High-level wrapper around various low-level UEFI APIs. \
Offers various optional features for typical Rust convenience, such as a
Logger and an Allocator.
This is the **main contribution** of this project.
- [`uefi-macros`](/uefi-macros/README.md): Helper macros used by `uefi`.
- [`uefi-test-runner`](/uefi-test-runner/README.md): a UEFI application that runs our unit / integration tests.

- `uefi-test-runner`: a UEFI application that runs unit / integration tests.

[log]: https://github.com/rust-lang-nursery/log

Expand Down Expand Up @@ -123,11 +77,14 @@ most of the library's functionality.
Check out the testing project's [`README.md`](uefi-test-runner/README.md) for
prerequisites for running the tests.

## Contributing
## Discuss and Contribute

We welcome issues and pull requests! For instructions on how to set up a
development environment and how to add new protocols, check out
[CONTRIBUTING.md](CONTRIBUTING.md).
For general discussions, feel free to join us in our [Zulip] and ask
your questions there.

Further, you can submit bugs and also ask questions in our [issue tracker].
Contributions in form of a PR are also highly welcome. Check our
[contributing guide](./CONTRIBUTING.md) for details.

## License

Expand All @@ -136,3 +93,6 @@ This license allows you to use the crate in proprietary programs, but any
modifications to the files must be open-sourced.

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

[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
[Zulip]: https://rust-osdev.zulipchat.com
6 changes: 5 additions & 1 deletion uefi/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@
name = "uefi"
version = "0.29.0"
readme = "README.md"
description = "Safe and easy-to-use wrapper for building UEFI apps."
description = """
Develop Rust software that leverages safe, convenient, and performant
abstractions for UEFI functionality.
"""

authors.workspace = true
categories.workspace = true
Expand All @@ -13,6 +16,7 @@ repository.workspace = true
rust-version.workspace = true

[features]
# KEEP this feature list in sync with doc in lib.rs!
default = [ "log-debugcon" ]
alloc = []

Expand Down
57 changes: 23 additions & 34 deletions uefi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,38 @@
# uefi-rs
# `uefi`

Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].

[![Crates.io](https://img.shields.io/crates/v/uefi)](https://crates.io/crates/uefi)
[![Docs.rs](https://docs.rs/uefi/badge.svg)](https://docs.rs/uefi)
![License](https://img.shields.io/github/license/rust-osdev/uefi-rs)
![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)

## TL;DR

For an introduction to the `uefi-rs` project and documentation, please refer to
our main [README].

[README]: https://github.com/rust-osdev/uefi-rs/blob/main/README.md

## Optional features

This crate's features are described in [`src/lib.rs`].

[`src/lib.rs`]: src/lib.rs

## User Documentation

<!-- KEEP IN SYNC WITH MAIN README -->

For a quick start, please check out [the UEFI application template](template).

The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
UEFI concepts. Reference documentation for the various crates can be found on
[docs.rs]:

- [docs.rs/uefi](https://docs.rs/uefi)
- [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
Develop Rust software that leverages **safe**, **convenient**, and
**performant** abstractions for [UEFI] functionality.

[spec]: http://www.uefi.org/specifications
[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD
## About

## MSRV
With `uefi`, you have the flexibility to integrate selected types and
abstractions into your project or to conveniently create EFI images, addressing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Here and elsewhere, let's standardize on always saying UEFI instead of EFI. I've heard people mention confusion around this on a few occasions, since it's not obvious without some research that we mean the same thing when we say EFI and UEFI.

the entire spectrum of your development needs.

The minimum supported Rust version is currently 1.70.
`uefi` works with stable Rust, but additional nightly-only features are
gated behind an `unstable` Cargo feature flag.

Our policy is to support at least the past two stable releases.
_Note that for producing EFI images, you also need to use a corresponding `uefi`
compiler target of Rust, such as `x86_64-unknown-uefi`._

## License
## API and User Documentation

The code in this repository is licensed under the Mozilla Public License 2.
This license allows you to use the crate in proprietary programs, but any modifications to the files must be open-sourced.
Please refer to [docs.rs](https://docs.rs/uefi) for comprehensive documentation
of the **latest stable release**. The latest not necessarily yet published
documentation can be found in [`src/lib.rs`](./src/lib.rs), which can also be
locally build by running `$ cargo xtask doc --open`.

The full text of the license is available in the [license file](LICENSE).
For an introduction to the `uefi-rs` project and this repository, please refer
to our main [README](https://github.com/rust-osdev/uefi-rs/blob/main/README.md).
<!-- ^ This link can't be relative as it also should work in the packaged crate
on crates.io. -->
Loading