diff --git a/README.md b/README.md index 01c656cf2..e08448eca 100644 --- a/README.md +++ b/README.md @@ -11,77 +11,37 @@ This crate makes it easy to develop Rust software that leverages **safe**, ![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 - -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 - ![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). +## API and User Documentation + -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). +The main contribution of this project is the [`uefi` crate](./uefi/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`](./uefi/src/lib.rs), which can also +be locally viewed by running `$ cargo xtask doc --open`. ## 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`. - -- `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-std-example`: Example UEFI app but as Rust standard binary. - -- `uefi-test-runner`: a UEFI application that runs unit / integration tests. +This repository provides various crates: -[log]: https://github.com/rust-lang-nursery/log +- [`uefi`](/uefi/README.md): High-level wrapper around various low-level UEFI + APIs. This crate makes it easy to develop Rust software that leverages safe, + convenient, and performant abstractions for UEFI functionality. + This is the **main contribution** of this project. +- [`uefi-raw`](/uefi-raw/README.md): Raw ABI-compatible types that closely + match the definitions in the UEFI Specification. They are suitable for + implementing UEFI firmware or creating interfaces to it. +- [`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 integration tests. +- [`uefi-std-example`](/uefi-std-example/README.md): Example UEFI app but as + Rust standard binary. ### Building and testing uefi-rs diff --git a/uefi/README.md b/uefi/README.md index 69e168975..63cf83180 100644 --- a/uefi/README.md +++ b/uefi/README.md @@ -22,29 +22,18 @@ parse the UEFI memory map. _Note that for producing UEFI 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]. - -[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 - -## 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). +## API and User Documentation + + +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 viewed by running `$ cargo xtask doc --open`. + +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). + [UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs index e9a4e037b..3368cd27c 100644 --- a/uefi/src/lib.rs +++ b/uefi/src/lib.rs @@ -205,17 +205,17 @@ //! [`BootServices`]: table::boot::BootServices //! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc //! [`SystemTable`]: table::SystemTable -//! [`r-efi`]: https://crates.io/crates/r-efi -//! [`entry-macro`]: uefi_macros::entry //! [`ctr16!`]: crate::cstr16 +//! [`entry-macro`]: uefi_macros::entry +//! [`r-efi`]: https://crates.io/crates/r-efi //! [`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/ -//! [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 +//! [unstable features]: https://doc.rust-lang.org/unstable-book/ #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))] #![cfg_attr(docsrs, feature(doc_auto_cfg))]