repo: init uefi-std-example

This is a minimal template to build Rust apps with Rust's std support
for UEFI and our additional `uefi` functionality. It isn't build in CI
yet, but might serve as a base for now.

Author: phip1611

Cargo.lock

@@ -5,6 +5,7 @@ members = [
     "uefi",
     "uefi-macros",
     "uefi-raw",
+    "uefi-std-example",
     "uefi-test-runner",
     "xtask",
 ]

Cargo.toml

@@ -77,6 +77,8 @@ This project contains multiple sub-crates:
   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.
 
 [log]: https://github.com/rust-lang-nursery/log

README.md

@@ -3,6 +3,7 @@
 - [Introduction](introduction.md)
 - [Tutorial](tutorial/introduction.md)
   - [Creating a UEFI Application](tutorial/app.md)
+    - [Combining Rust `std` with `uefi`](tutorial/rust-std.md)
   - [Building](tutorial/building.md)
   - [Running in a VM](tutorial/vm.md)
   - [Running on Hardware](tutorial/hardware.md)

book/src/SUMMARY.md

@@ -0,0 +1,73 @@
+# Combining Rust `std` with `uefi`
+
+## TL;DR
+
+In Mid-2024, we recommend to stick to our normal guide. Use this document as
+guide and outlook for the future of UEFI and Rust.
+
+## About
+
+In the `uefi` crate, we provide tooling to create a `no_std` + `no_main`
+binary, i.e., an UEFI image, in a convenient way. However, there is also the
+option to create a "standard" binary with Rust. The result is the same, but the
+build process and the overall programming is much more similar to regular
+Rust binaries written for Operating Systems, such as Linux, Windows, or macOS.
+
+## Standard binary vs `no_std` binary
+
+A Rust standard binary is a binary that uses the Rust standard library. This
+means that the Rust standard library (_`std` implementation_) is implemented for
+the given platform. A `no_std` (strictly speaking, `no_std` + `no_main`) on the
+other hand can only use the `core` library, but not `std`. Thus, you need to
+write more functionality on your own or use libraries, such as the `uefi` crate.
+
+## About `std` for `uefi`
+
+Using `std` is always the recommended and standard way. However, the `std`
+implementation is not feature-complete and work in progress
+(Mid-2024, Rust stable 1.80), and will also be it in the coming months and
+probably years. Over time, you will need less and less specific features of
+`uefi` and can utilize standard and well-known OS-independent APIs in `std`
+instead. Just as you would to in the typical Linux application, for example.
+
+The `uefi` crate is suited to extend the functionality of these "standard
+binaries".
+
+## Code Example
+
+Please refer to [`<repo>/uefi-std-example`](/uefi-std-example/README.md) to
+see a specific example. The relevant `main.rs` looks as follows:
+
+```rust
+// Note: In Rust 1.82.0-nightly and before, the `uefi_std` feature is
+// required for accessing `std::os::uefi::env::*`. The other default
+// functionality doesn't need a nightly toolchain (with Rust 1.80 and later),
+// but with that limited functionality you - currently - also can't integrate
+// the `uefi` crate.
+#![feature(uefi_std)]
+
+use std::os::uefi as uefi_std;
+use uefi::runtime::ResetType;
+use uefi::{Handle, Status};
+
+/// Performs the necessary setup code for the `uefi` crate.
+fn setup_uefi_crate() {
+  let st = uefi_std::env::system_table();
+  let ih = uefi_std::env::image_handle();
+
+  // Mandatory setup code for `uefi` crate.
+  unsafe {
+    uefi::table::set_system_table(st.as_ptr().cast());
+
+    let ih = Handle::from_ptr(ih.as_ptr().cast()).unwrap();
+    uefi::boot::set_image_handle(ih);
+  }
+}
+
+fn main() {
+  println!("Hello World from uefi_std");
+  setup_uefi_crate();
+  println!("UEFI-Version is {}", uefi::system::uefi_revision());
+  uefi::runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
+}
+```

book/src/tutorial/rust-std.md

@@ -21,6 +21,7 @@ pkgs.mkShell {
     rustToolchain
 
     # Other
+    mdbook
     yamlfmt
     which # used by "cargo xtask fmt"
   ];

shell.nix

@@ -0,0 +1,11 @@
+[package]
+name = "uefi-std-example"
+version = "0.1.0"
+authors = ["The Rust OSDev team"]
+publish = false
+edition = "2021"
+
+[dependencies]
+# Attention: Don't activate the panic_handler feature, as it will clash with
+# the one coming from `std`.
+uefi = { path = "../uefi", features = ["alloc"], default-features = false }

uefi-std-example/Cargo.toml

@@ -0,0 +1,18 @@
+# Minimal Rust App using `std` and `uefi`
+
+Minimal example of a "standard Rust application" that showcases how `uefi` can
+be utilized and enhance the developers experience, when `std` is available.
+
+For simplicity, this example is minimal and the documentation is focused on
+`x86_64-unknown-uefi`. However, it works similar for other supported UEFI
+platforms.
+
+## Build
+
+Build the app using
+`$ cargo +nightly build --target x86_64-unknown-uefi`. To build it from the root
+directory (the Cargo workspace), append `-p uefi-std-example`.
+
+## Run
+
+The resulting `.efi` file can be found in `target/x86_64-unknown-uefi/<debug|release>/uefi-std-example.efi`.

uefi-std-example/README.md

@@ -0,0 +1,31 @@
+// Note: In Rust 1.82.0-nightly and before, the `uefi_std` feature is
+// required for accessing `std::os::uefi::env::*`. The other default
+// functionality doesn't need a nightly toolchain (with Rust 1.80 and later),
+// but with that limited functionality you - currently - also can't integrate
+// the `uefi` crate.
+#![feature(uefi_std)]
+
+use std::os::uefi as uefi_std;
+use uefi::runtime::ResetType;
+use uefi::{Handle, Status};
+
+/// Performs the necessary setup code for the `uefi` crate.
+fn setup_uefi_crate() {
+    let st = uefi_std::env::system_table();
+    let ih = uefi_std::env::image_handle();
+
+    // Mandatory setup code for `uefi` crate.
+    unsafe {
+        uefi::table::set_system_table(st.as_ptr().cast());
+
+        let ih = Handle::from_ptr(ih.as_ptr().cast()).unwrap();
+        uefi::boot::set_image_handle(ih);
+    }
+}
+
+fn main() {
+    println!("Hello World from uefi_std");
+    setup_uefi_crate();
+    println!("UEFI-Version is {}", uefi::system::uefi_revision());
+    uefi::runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
+}