Update and reorganize documentation

Author: GabrielMajeri

BUILDING.md

@@ -1,43 +1,55 @@
-# Creating UEFI applications
+# Building and running UEFI applications
+
+## UEFI binaries
 
 UEFI applications are simple COFF (Windows) executables, with the special
 `EFI_Application` subsystem, and some limitations (such as no dynamic linking).
-Rust supports building UEFI applications for the
+
+The Rust compiler supports building UEFI applications for the
 [`aarch64-unknown-uefi`], [`i686-unknown-uefi`], and [`x86_64-unknown-uefi`]
 targets.
 
-## Template
+[`aarch64-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/aarch64_unknown_uefi.rs
+[`i686-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/i686_unknown_uefi.rs
+[`x86_64-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs
+
+## Building
+
+- Install a `nightly` version of the Rust [toolchain](https://rust-lang.github.io/rustup/concepts/toolchains.html):
+
+  `rustup toolchain install nightly`
 
-The [template](template) subdirectory contains a minimal example of a UEFI
-application. Copy it to a new directory to get started.
+  It is not currently possible to build the core crate with a stable version of the Rust compiler.
 
-- [template/.cargo/config](template/.cargo/config) file sets some `build-std` options.
-- [template/Cargo.toml](template/Cargo.toml) shows the necessary
-  dependencies. Note that when creating your project the
-  [`uefi`](https://crates.io/crates/uefi) and
-  [`uefi-services`](https://crates.io/crates/uefi-services) dependencies should
-  be changed to the latest releases on [crates.io](https://crates.io).
-- [template/src/main.rs](template/src/main.rs) has a minimal entry point that
-  initializes services and exits successfully.
+- You need to add the `rust-src` toolchain [component](https://rust-lang.github.io/rustup/concepts/components.html)
+  (if it's not already installed), which Cargo will use to build the core crates for the UEFI target:
 
-## Building and running
+  `rustup component add --toolchain nightly rust-src`
+
+- Build this crate using the `nightly` toolchain:
 
-- Build using a `nightly` version of the compiler:
   `cargo +nightly build --target x86_64-unknown-uefi`.
 
 - The `target` directory will contain a `x86_64-unknown-uefi` subdirectory,
-  where you will find the `uefi_app.efi` file - a normal UEFI executable.
+  where you will find a `<crate name>.efi` file - a normal UEFI executable.
+
+## Running
 
-- To run this on a real computer:
+- To run an `.efi` executable on a real computer:
   - Find a USB drive which is FAT12 / FAT16 / FAT32 formatted
   - Copy the file to the USB drive, to `/EFI/Boot/Bootx64.efi`
   - In the UEFI BIOS, choose "Boot from USB" or similar
 
 - To run this in QEMU:
   - You will need a recent version of QEMU as well as OVMF to provide UEFI support
   - Check the [`build.py`](uefi-test-runner/build.py) script for an idea of
-    what arguments to pass to QEMU
+    what arguments to pass to QEMU.
 
-[`aarch64-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/aarch64_unknown_uefi.rs
-[`i686-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/i686_unknown_uefi.rs
-[`x86_64-unknown-uefi`]: https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs
+    In principle, you need to replicate the file structure described above for an USB drive,
+    then [mount the directory as if it were a FAT drive][qemu-vvfat].
+
+[qemu-vvfat]: https://en.wikibooks.org/wiki/QEMU/Devices/Storage#Virtual_FAT_filesystem_(VVFAT)
+
+## Template
+
+The [template](template) provides a quick way to get started building UEFI applications.

CONTRIBUTING.md

@@ -13,8 +13,9 @@ First, change to the `uefi-test-runner` directory:
 cd 'uefi-test-runner'
 ```
 
-Please take a quick look at the README for an overview of the system requirements
-of the test runner.
+Please take a quick look at the test runner project's [`README`](uefi-test-runner/README.md)
+for an overview of the required dependencies. In addition, the [`BUILDING`](BUILDING.md)
+document is useful if it's your first time building and running an UEFI executable.
 
 Make some changes in your favourite editor / IDE:
 I use [VS Code][code] with the [RLS][rls] extension.

README.md

@@ -19,12 +19,11 @@ This crate makes it easy to both:
 The objective is to provide **safe** and **performant** wrappers for UEFI interfaces,
 and allow developers to write idiomatic Rust code.
 
-Check out @gil0mendes [blog post on getting started with UEFI in Rust][gm-blog].
+Check out [the UEFI application template](template) for a quick start.
 
 **Note**: this crate currently has only been tested with **64-bit** UEFI on x86/ARM.
 
 [UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
-[gm-blog]: https://gil0mendes.io/blog/an-efi-app-a-bit-rusty/
 [rustc-custom]: https://doc.rust-lang.org/rustc/targets/custom.html
 
 ![uefi-rs running in QEMU](https://imgur.com/SFPSVuO.png)
@@ -54,30 +53,6 @@ This project contains multiple sub-crates:
 
 [log]: https://github.com/rust-lang-nursery/log
 
-## Building kernels which use UEFI
-
-This crate makes it easy to start building simple applications with UEFI.
-However, there are some limitations you should be aware of:
-
-- The global logger / allocator **can only be set once** per binary.
-  It is useful when just starting out, but if you're building a real OS you will
-  want to write your own specific kernel logger and memory allocator.
-
-- To support advanced features such as [higher half kernel] and [linker scripts]
-  you will want to build your kernel as an ELF binary.
-
-In other words, the best way to use this crate is to create a small binary which
-wraps your actual kernel, and then use UEFI's convenient functions for loading
-it from disk and booting it.
-
-This is similar to what the Linux kernel's [EFI stub] does: the compressed kernel
-is an ELF binary which has little knowledge of how it's booted, and the boot loader
-uses UEFI to set up an environment for it.
-
-[higher half kernel]: https://wiki.osdev.org/Higher_Half_Kernel
-[linker scripts]: https://sourceware.org/binutils/docs/ld/Scripts.html
-[EFI stub]: https://www.kernel.org/doc/Documentation/efi-stub.txt
-
 ## Documentation
 
 The docs for the latest published crate version can be found at
@@ -88,11 +63,12 @@ the [UEFI specification][spec] for detailed information.
 
 [spec]: http://www.uefi.org/specifications
 
-## Sample code
+## Tests
 
-An example UEFI app is built in the `uefi-test-runner` directory.
+The `uefi-test-runner` directory contains a sample UEFI app which exercises
+most of the library's functionality.
 
-Check out the testing [README.md](uefi-test-runner/README.md) for instructions on how to run the crate's tests.
+Check out the testing project's [`README.md`](uefi-test-runner/README.md) for instructions on how to run the tests.
 
 ## Building UEFI programs
 

template/README.md

@@ -0,0 +1,42 @@
+# UEFI application template
+
+This directory contains a minimal example of a UEFI application.
+Copy it to a new directory to get started.
+
+Check out the [`BUILDING.md`](../BUILDING.md) document for more instructions on
+how to build and run a UEFI application developed using `uefi-rs`.
+
+## File structure
+
+- [`template/.cargo/config`](template/.cargo/config) file sets some `build-std` options.
+- [`template/Cargo.toml`](template/Cargo.toml) shows the necessary
+  dependencies. Note that when creating your project the
+  [`uefi`](https://crates.io/crates/uefi) and
+  [`uefi-services`](https://crates.io/crates/uefi-services) dependencies should
+  be changed to the latest releases on [crates.io](https://crates.io).
+- [`template/src/main.rs`](template/src/main.rs) has a minimal entry point that
+  initializes the `uefi-services` crate and exits successfully.
+
+## Building kernels which use UEFI
+
+This template makes it easy to start building simple applications with UEFI.
+However, there are some limitations you should be aware of:
+
+- The global logger / allocator **can only be set once** per binary.
+  It is useful when just starting out, but if you're building a real OS you will
+  want to write your own specific kernel logger and memory allocator.
+
+- To support advanced features such as [higher half kernel] and [linker scripts]
+  you will want to build your kernel as an ELF binary.
+
+In other words, the best way to use this crate is to create a small binary which
+wraps your actual kernel, and then use UEFI's convenient functions for loading
+it from disk and booting it.
+
+This is similar to what the Linux kernel's [EFI stub] does: the compressed kernel
+is an ELF binary which has little knowledge of how it's booted, and the boot loader
+uses UEFI to set up an environment for it.
+
+[higher half kernel]: https://wiki.osdev.org/Higher_Half_Kernel
+[linker scripts]: https://sourceware.org/binutils/docs/ld/Scripts.html
+[EFI stub]: https://www.kernel.org/doc/Documentation/efi-stub.txt

uefi-test-runner/README.md

@@ -4,7 +4,7 @@ This file documents the process of building and running the test suite.
 
 ## Prerequisites
 
-Besides all the [core library requirements](https://github.com/rust-osdev/uefi-rs/blob/master/BUILDING.md#Prerequisites) for building a UEFI app, the tests have additional requirements:
+Besides all the [core library requirements](../BUILDING.md) for building a UEFI app, the tests have additional requirements:
 
 - [QEMU](https://www.qemu.org/): the most recent version of QEMU is recommended.
 - [Python 3](https://www.python.org): at least version 3.6 is required.