diff --git a/README.md b/README.md index 1d67cea61..5700e1a01 100644 --- a/README.md +++ b/README.md @@ -2,70 +2,98 @@ [![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) -![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs) ![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] is the successor to the BIOS. It provides an early boot environment for -OS loaders, hypervisors and other low-level applications. While it started out -as x86-specific, it has been adopted on other platforms, such as ARM. +[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. \ + Most probably, you want to use this crate. +- `uefi-services`: Optional Rust convenience with a global allocator and a + `log`-based logger implementation. -This crate makes it easy to both: - - Write UEFI applications in Rust (for `i686`, `x86_64`, or `aarch64`) - - Call UEFI functions from an OS (usually built with a [custom target][rustc-custom]) +You can use the abstractions for example to: -The objective is to provide **safe** and **performant** wrappers for UEFI interfaces, -and allow developers to write idiomatic Rust code. +- create OS-specific loaders and leverage UEFI boot service +- access UEFI runtime services from an OS -Check out [the UEFI application template](template) for a quick start. +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 -[rustc-custom]: https://doc.rust-lang.org/rustc/targets/custom.html -![uefi-rs running in QEMU](https://imgur.com/SFPSVuO.png) +![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) +- [docs.rs/uefi-services](https://docs.rs/uefi-services) + +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 -## Project structure +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. -- `uefi-macros`: procedural macros that are used to derive some traits in `uefi`. +- `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-services`: provides a panic handler, and initializes the `alloc` / `logger` features. +- `uefi-services`: provides a panic handler, and initializes + the `alloc` / `logger` features. - `uefi-test-runner`: a UEFI application that runs unit / integration tests. [log]: https://github.com/rust-lang-nursery/log -## Documentation - -The [uefi-rs book] contains a tutorial, how-tos, and overviews of some -important UEFI concepts. - -Reference documentation 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) -- [docs.rs/uefi-services](https://docs.rs/uefi-services) - -For additional information, refer to the [UEFI specification][spec]. - -[spec]: http://www.uefi.org/specifications -[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD - -## Building and testing uefi-rs +### Building and testing uefi-rs Use the `cargo xtask` command to build and test the crate. Available commands: + - `build`: build all the UEFI packages - `--release`: build in release mode - `--target {x86_64,ia32,aarch64}`: choose target UEFI arch @@ -77,9 +105,10 @@ Available commands: - `--warnings-as-errors`: treat warnings as errors - `run`: build `uefi-test-runner` and run it in QEMU - `--ci`: disable some tests that don't work in the CI - - `--disable-kvm`: disable hardware accelerated virtualization support in QEMU. - Especially useful if you want to run the tests under - [WSL](https://docs.microsoft.com/en-us/windows/wsl) on Windows. + - `--disable-kvm`: disable hardware accelerated virtualization support in + QEMU. + Especially useful if you want to run the tests under + [WSL](https://docs.microsoft.com/en-us/windows/wsl) on Windows. - `--example `: run an example instead of the main binary. - `--headless`: run QEMU without a GUI - `--ovmf-code `: path of an OVMF code file @@ -94,18 +123,16 @@ 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. -## MSRV - -See the [uefi package's README](uefi/README.md#MSRV). - ## Contributing -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). +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). ## 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. +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).