workspace: add uefi-std-example member

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

@@ -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);
+}