diff --git a/README.md b/README.md index 768964871..ff0e219ee 100644 --- a/README.md +++ b/README.md @@ -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 +Develop Rust software that leverages **safe**, **convenient**, and +**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 - - - -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 @@ -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 @@ -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 diff --git a/uefi/Cargo.toml b/uefi/Cargo.toml index 2fe9e257b..ad6ec1a1c 100644 --- a/uefi/Cargo.toml +++ b/uefi/Cargo.toml @@ -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 @@ -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 = [] diff --git a/uefi/README.md b/uefi/README.md index 625a39363..d944ddbd4 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -1,4 +1,6 @@ -# 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) @@ -6,44 +8,31 @@ ![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 - - - -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 +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). + diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 4dc526893..404db3e9b 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -1,25 +1,80 @@ //! Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI]. //! -//! See the [Rust UEFI Book] for a tutorial, how-tos, and overviews of some -//! important UEFI concepts. For more details of UEFI, see the latest [UEFI -//! Specification][spec]. +//! # TL;DR //! -//! Feel free to file bug reports and questions in our [issue tracker], and [PR -//! contributions][contributing] are also welcome! +//! Develop Rust software that leverages **safe**, **convenient**, and +//! **performant** abstractions for [UEFI] functionality. //! -//! # Interaction with uefi services +//! # About this Document +//! +//! In this document, you find general information about this crate, such +//! as examples and the technical documentation of the public API, as well +//! as general information about the project, such as license or MSRV +//! requirements. +//! +//! # About `uefi` +//! +//! With `uefi`, you have the flexibility to integrate selected types and +//! abstractions into your project or to conveniently create EFI images, +//! addressing the entire spectrum of your development needs. +//! +//! `uefi` works with stable Rust, but additional nightly-only features are +//! gated behind an `unstable` Cargo feature flag. Please find more information +//! about supported features below. +//! +//! _Note that for producing EFI images, you also need to use a corresponding +//! `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._ +//! +//! ## Example Use Cases //! //! With this crate you can write code for the pre- and post-exit boot services -//! epochs. However, the `uefi` crate unfolds its true potential when -//! interacting with UEFI boot services. +//! epochs. However, the `uefi` crate unfolds its true potential when crafting +//! EFI images interacting with UEFI boot services and eventually exiting them. +//! +//! By EFI images (`image.efi`), we are referring to EFI applications, EFI +//! boot service drivers, and EFI runtime service drivers. An EFI application +//! might be your OS-specific loader technically similar to _GRUB_ or _Limine_. +//! +//! You can also use this crate to parse the UEFI memory map when a bootloader, +//! such as _GRUB_ or _Limine_, passed the UEFI memory map as part of the +//! corresponding boot information to your kernel, or to access runtime services +//! from your kernel. Hence, when you also use utilize `uefi` also in ELF +//! binaries and are not limited to EFI images. //! -//! # Crate organisation +//! ## Supported Architectures +//! +//! `uefi` is 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 in CI. +//! +//! # API/User Documentation, Documentation Structure, and other Resources +//! +//! Down below, you find typical technical documentation of all types, modules, +//! and functions exported by `uefi`. +//! +//! For a TL;DR quick start with an example on how to create your own EFI +//! application, please check out [the UEFI application template][template]. The +//! [Rust UEFI Book] is a more beginner-friendly tutorial with How-Tos, and +//! overviews of some important UEFI concepts and the abstractions provided by +//! this library. +//! +//! For more details of UEFI itself, see the latest [UEFI Specification][spec]. +//! +//! # Library Structure & Tips //! //! The top-level module contains some of the most used types and macros, //! including the [`Handle`] and [`Result`] types, the [`CStr16`] and //! [`CString16`] types for working with UCS-2 strings, and the [`entry`] and //! [`guid`] macros. //! +//! ## UEFI Strings +//! +//! Rust string literals are UTF-8 encoded and thus, not compatible with most +//! UEFI interfaces. We provide [`CStr16`] and [`CString16`] for proper working +//! with UCS-2 strings, including various transformation functions from standard +//! Rust strings. You can use [`ctr16!`] to create UCS-2 string literals at +//! compile time. +//! //! ## Tables //! //! The [`SystemTable`] provides access to almost everything in UEFI. It comes @@ -42,7 +97,7 @@ //! protocol, and see the [`proto`] module for protocol implementations. New //! protocols can be defined with the [`unsafe_protocol`] macro. //! -//! ## Optional crate features +//! ## Optional Cargo crate features //! //! - `alloc`: Enable functionality requiring the [`alloc`] crate from //! the Rust standard library. For example, methods that return a @@ -59,8 +114,6 @@ //! that prints output to the UEFI console. No buffering is done; this //! is not a high-performance logger. //! - `panic_handler`: Add a default panic handler that logs to `stdout`. -//! - `panic-on-logger-errors` (enabled by default): Panic if a text -//! output error occurs in the logger. //! - `unstable`: Enable functionality that depends on [unstable //! features] in the nightly compiler. //! As example, in conjunction with the `alloc`-feature, this gate allows @@ -73,16 +126,76 @@ //! only unfold their potential when you invoke `uefi::helpers::init` as soon //! as possible in your application. //! +//! # Discuss and Contribute +//! +//! 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] for details. +//! +//! # Comparison to other Projects in the Ecosystem +//! +//! ## Rust `std` implementation +//! +//! There is an ongoing effort for a `std` implementation of the Rust standard +//! library. ([Platform description][rustc-uefi-std], +//! [tracking issue][uefi-std-tr-issue]), that is yet far from being mature. As +//! of Mid-2024, we recommend to use our `uefi` library in a `no_std` binary to +//! create EFI images. +//! +//! We will closely monitor the situation and update the documentation +//! accordingly, once the `std` implementation is more mature. +//! +//! ## `r-efi` +//! +//! Raw UEFI bindings without high-level convenience similar to our `uefi-raw` +//! crate, which is part of this project, but more feature-complete. It +//! targets a lower-level than our `uefi` crate does. +//! +//! # MSRV +//! +//! +//! The minimum supported Rust version is currently 1.70. +//! Our policy is to support at least the past two stable releases. +//! +//! # License +//! +//! +//! 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. +//! +//! The full text of the license is available in the [license file][LICENSE]. +//! +//! # Trivia and Background +//! +//! [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 any different kind +//! of low-level applications (such as an [IRC client][uefirc]). +//! +//! [LICENSE]: https://github.com/rust-osdev/uefi-rs/blob/main/uefi/LICENSE //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/ //! [UEFI]: https://uefi.org/ +//! [Zulip]: https://rust-osdev.zulipchat.com //! [`BootServices`]: table::boot::BootServices //! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc //! [`SystemTable`]: table::SystemTable +//! [`ctr16!`]: crate::cstr16 //! [`unsafe_protocol`]: proto::unsafe_protocol //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues +//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html //! [spec]: https://uefi.org/specifications -//! [unstable features]: https://doc.rust-lang.org/unstable-book/ +//! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template +//! [uefi-std-tr-issue]: https://github.com/rust-lang/rust/issues/100499 +//! [uefirc]: https://github.com/codyd51/uefirc #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))] #![cfg_attr(docsrs, feature(doc_auto_cfg))]