From 79c048a060700ecb875382a4093ca972d539262f Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 28 Jul 2024 15:31:32 +0200 Subject: [PATCH 01/13] uefi: remove documentation about already removed feature --- uefi/Cargo.toml | 1 + uefi/src/lib.rs | 4 +--- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/uefi/Cargo.toml b/uefi/Cargo.toml index 2fe9e257b..adeb43acb 100644 --- a/uefi/Cargo.toml +++ b/uefi/Cargo.toml @@ -13,6 +13,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/src/lib.rs b/uefi/src/lib.rs index 4dc526893..13b07da4b 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -42,7 +42,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 +59,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 From 676c58557dbfa393f44a7b2be1dc1b7e7cc3bf9d Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 09:36:11 +0200 Subject: [PATCH 02/13] doc: unified new TL;DR/description entry The main idea here is to: - tell that `uefi` is not only for EFI images but also apps that interact with UEFI functionality, such as parsing a memory map from a pre-defined chunk of memory. - streamline the doc --- README.md | 9 +++++++++ uefi/Cargo.toml | 5 ++++- uefi/README.md | 8 +++++++- uefi/src/lib.rs | 5 +++++ 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 768964871..974de52d1 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,18 @@ # 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) +## TL;DR + +Develop Rust software that leverages **safe**, **convenient**, and +**performant** abstractions for [UEFI] functionality. + ## Description [UEFI] started as the successor firmware to the BIOS in x86 space and developed @@ -136,3 +143,5 @@ 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 diff --git a/uefi/Cargo.toml b/uefi/Cargo.toml index adeb43acb..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 diff --git a/uefi/README.md b/uefi/README.md index 625a39363..17a9808f6 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,6 +8,10 @@ ![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 + +Develop Rust software that leverages **safe**, **convenient**, and +**performant** abstractions for [UEFI] functionality. For an introduction to the `uefi-rs` project and documentation, please refer to our main [README]. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 13b07da4b..c27f57516 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -1,5 +1,10 @@ //! Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI]. //! +//! # TL;DR +//! +//! Develop Rust software that leverages **safe**, **convenient**, and +//! **performant** abstractions for [UEFI] functionality. +//! //! 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]. From 27ec94655f73c5aef0699d1a0044b88280c6eecd Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 11:00:03 +0200 Subject: [PATCH 03/13] doc: add "About this Document" This prepares what the following commits will provide. --- uefi/src/lib.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index c27f57516..eaa683823 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -12,6 +12,13 @@ //! Feel free to file bug reports and questions in our [issue tracker], and [PR //! contributions][contributing] are also welcome! //! +//! # 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. +//! //! # Interaction with uefi services //! //! With this crate you can write code for the pre- and post-exit boot services From d85b4c9ee31c6899bd047af6b0a351f03b9c195f Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 09:43:03 +0200 Subject: [PATCH 04/13] doc: move background info to lib.rs This is the beginning of moving all relevant information from README.md to lib.rs. The main idea is to have `lib.rs` as main entry point into the documentation instead of an inconsistent mixture between the README and the lib.rs file. --- README.md | 8 -------- uefi/src/lib.rs | 12 ++++++++++++ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 974de52d1..104e32735 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,6 @@ Develop Rust software that leverages **safe**, **convenient**, and ## 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. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index eaa683823..f8386083d 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -83,6 +83,17 @@ //! only unfold their potential when you invoke `uefi::helpers::init` as soon //! as possible in your application. //! +//! # 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]). +//! //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/ //! [UEFI]: https://uefi.org/ //! [`BootServices`]: table::boot::BootServices @@ -93,6 +104,7 @@ //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues //! [spec]: https://uefi.org/specifications //! [unstable features]: https://doc.rust-lang.org/unstable-book/ +//! [uefirc]: https://github.com/codyd51/uefirc #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))] #![cfg_attr(docsrs, feature(doc_auto_cfg))] From 9f9e5ca21ab529cab463282a8d72ab3707404cb0 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:59:19 +0200 Subject: [PATCH 05/13] doc: streamline sections Contributing, MSRV, and License Copy MSRV, License, and Contributing sections to lib.rs and streamline it with the README equivalents. We should also include these information in lib.rs, as it is the main entry point into everything relevant about the library. At least, it should from now on. The big benefit is that the documentation on `docs.rs` then covers everything relevant. --- README.md | 12 ++++++++---- uefi/src/lib.rs | 29 ++++++++++++++++++++++++++--- 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 104e32735..10261436a 100644 --- a/README.md +++ b/README.md @@ -122,11 +122,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 @@ -137,3 +140,4 @@ 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/src/lib.rs b/uefi/src/lib.rs index f8386083d..8fc87da73 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -9,9 +9,6 @@ //! important UEFI concepts. For more details of UEFI, see the latest [UEFI //! Specification][spec]. //! -//! Feel free to file bug reports and questions in our [issue tracker], and [PR -//! contributions][contributing] are also welcome! -//! //! # About this Document //! //! In this document, you find general information about this crate, such @@ -83,6 +80,30 @@ //! 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. +//! +//! # 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 @@ -94,8 +115,10 @@ //! 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 From 505e70f68daf0f19d46314b90256ca2b658cecd5 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:00:03 +0200 Subject: [PATCH 06/13] doc: add "About" section The About section is a more comprehensive write-up of the TL;DR section mentioned earlier. It should guide the user to know what they can do with this lib. --- uefi/README.md | 12 ++++++++++++ uefi/src/lib.rs | 13 +++++++++++++ 2 files changed, 25 insertions(+) diff --git a/uefi/README.md b/uefi/README.md index 17a9808f6..249359d72 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -13,6 +13,18 @@ Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI]. Develop Rust software that leverages **safe**, **convenient**, and **performant** abstractions for [UEFI] functionality. +## About + +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. + +_Note that for producing EFI images, you also need to use a corresponding `uefi` +compiler target of Rust, such as `x86_64-unknown-uefi`._ + For an introduction to the `uefi-rs` project and documentation, please refer to our main [README]. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 8fc87da73..a4e5884c4 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -16,6 +16,19 @@ //! 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`._ +//! //! # Interaction with uefi services //! //! With this crate you can write code for the pre- and post-exit boot services From e46e74ac508a97fedb258409dcf28810fb4a299f Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 11:07:02 +0200 Subject: [PATCH 07/13] doc: extend About section with Example Use Cases --- uefi/src/lib.rs | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index a4e5884c4..859162cc1 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -29,11 +29,21 @@ //! _Note that for producing EFI images, you also need to use a corresponding //! `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._ //! -//! # Interaction with uefi services +//! ## 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 //! From 02bc2cf7545082e8eaa0f2574e059bfdac9d6b2e Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 11:07:22 +0200 Subject: [PATCH 08/13] doc: add Supported Architectures --- README.md | 4 ---- uefi/src/lib.rs | 6 ++++++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 10261436a..4a4b43927 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,6 @@ You can use the abstractions for example to: - 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 ![UEFI App running in QEMU](https://imgur.com/SFPSVuO.png) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 859162cc1..40bd912b1 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -45,6 +45,12 @@ //! from your kernel. Hence, when you also use utilize `uefi` also in ELF //! binaries and are not limited to EFI images. //! +//! ## 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. +//! //! # Crate organisation //! //! The top-level module contains some of the most used types and macros, From 52954f4eaeea5a6978c41a4a0f251c89bb056c7b Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:20:07 +0200 Subject: [PATCH 09/13] doc: add "Comparison to other Projects in the Ecosystem" This is especially interesting as the `std` implementation of Rust is upcoming --- uefi/src/lib.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 40bd912b1..4063b4ff5 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -118,6 +118,25 @@ //! 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 //! //! @@ -157,6 +176,8 @@ //! [spec]: https://uefi.org/specifications //! [unstable features]: https://doc.rust-lang.org/unstable-book/ //! [uefirc]: https://github.com/codyd51/uefirc +//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html +//! [uefi-std-tr-issue]: https://github.com/rust-lang/rust/issues/100499 #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))] #![cfg_attr(docsrs, feature(doc_auto_cfg))] From 837fe5c62098be91a4b1eb0ef72c908fbe3751e7 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:23:54 +0200 Subject: [PATCH 10/13] doc: add "API/User Documentation, Documentation Structure, and other Resources" This is logically following the About section. --- uefi/README.md | 17 ----------------- uefi/src/lib.rs | 18 ++++++++++++++---- 2 files changed, 14 insertions(+), 21 deletions(-) diff --git a/uefi/README.md b/uefi/README.md index 249359d72..f74409807 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -36,23 +36,6 @@ 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) - -[spec]: http://www.uefi.org/specifications -[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD - ## MSRV The minimum supported Rust version is currently 1.70. diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 4063b4ff5..eedd3aec4 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -5,10 +5,6 @@ //! Develop Rust software that leverages **safe**, **convenient**, and //! **performant** abstractions for [UEFI] functionality. //! -//! 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]. -//! //! # About this Document //! //! In this document, you find general information about this crate, such @@ -51,6 +47,19 @@ //! 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]. +//! //! # Crate organisation //! //! The top-level module contains some of the most used types and macros, @@ -174,6 +183,7 @@ //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues //! [spec]: https://uefi.org/specifications +//! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template //! [unstable features]: https://doc.rust-lang.org/unstable-book/ //! [uefirc]: https://github.com/codyd51/uefirc //! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html From b9829d74d4b5d92d88e099bf2f5c4d2b6d33d61c Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:25:07 +0200 Subject: [PATCH 11/13] doc: Crate organization -> Library Structure & Tips Also added "UEFI Strings" subsection --- uefi/src/lib.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index eedd3aec4..7d6d63332 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -60,13 +60,21 @@ //! //! For more details of UEFI itself, see the latest [UEFI Specification][spec]. //! -//! # Crate organisation +//! # 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 @@ -179,6 +187,7 @@ //! [`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 From e0fde842a433d7c71dec8433a10cf0c3dd2c253c Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 11:15:13 +0200 Subject: [PATCH 12/13] doc: reorder links alphabetically in lib.rs --- uefi/src/lib.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index 7d6d63332..404db3e9b 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -191,12 +191,11 @@ //! [`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 //! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template -//! [unstable features]: https://doc.rust-lang.org/unstable-book/ -//! [uefirc]: https://github.com/codyd51/uefirc -//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html //! [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))] From 5c9343fc0f056982d33c5b7052acca0739decaa6 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Tue, 30 Jul 2024 10:38:42 +0200 Subject: [PATCH 13/13] doc: final streamlining of README files Now, the README are the entry into the repository and guide the user to the actual documentation in lib.rs respectively on docs.rs. --- README.md | 71 +++++++++++--------------------------------------- uefi/README.md | 30 +++++++-------------- 2 files changed, 24 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 4a4b43927..ff0e219ee 100644 --- a/README.md +++ b/README.md @@ -13,73 +13,32 @@ Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI]. Develop Rust software that leverages **safe**, **convenient**, and **performant** abstractions for [UEFI] functionality. -## Description +## API and User Documentation -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`. - - -You can use the abstractions for example to: - -- create OS-specific loaders and leverage UEFI boot service -- access UEFI runtime services from an OS - -[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: - -- `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. +### Repository Structure -- `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 diff --git a/uefi/README.md b/uefi/README.md index f74409807..d944ddbd4 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -25,26 +25,14 @@ gated behind an `unstable` Cargo feature flag. _Note that for producing EFI images, you also need to use a corresponding `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._ -For an introduction to the `uefi-rs` project and documentation, please refer to -our main [README]. +## API and User Documentation -[README]: https://github.com/rust-osdev/uefi-rs/blob/main/README.md +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`. -## Optional features - -This crate's features are described in [`src/lib.rs`]. - -[`src/lib.rs`]: src/lib.rs - -## 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). +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). +