Forem: Ayush

Handling ExitBootServices Event in Rust std

Ayush — Fri, 07 Apr 2023 10:37:12 +0000

Hello everyone. Recently, there was a discussion about the exact scope/boundary of Rust std for UEFI. In this post, I am going to go over the different stages of UEFI and define what std for UEFI aims to target. Additionally, I will go over how the current implementation handles ExitBootServices().

Background

Unlike Operating Systems, UEFI is a collection of stages in the boot sequence, each with its own set of available resources/functionality. As such, it is vital to remember where in the UEFI boot stages a binary is supposed to be run. Here is a simple diagram of the different Boot Stages in UEFI.

Now I will go over each stage and their relation to Rust std.

SEC – Security Phase

The Security (SEC) phase is the first phase in the PI Architecture and is responsible for the following:

Handling all platform restart events
Creating a temporary memory store
Serving as the root of trust in the system
Passing handoff information to the PEI Foundation

Rust std implementation should not be used here. In fact, even the {arch}-unknown-uefi target is not meant to be used in this phase.

PEI – Pre-EFI Initialization

The PEI phase initially operates with the platform in a nascent state, leveraging only on-processor resources, such as the processor cache as a call stack, to dispatch Pre-EFI Initialization Modules (PEIMs). These PEIMs are responsible for the following:

Initializing some permanent memory complement
Describing the memory in Handoff Blocks (HOBs)
Describing the firmware volume locations in HOBs
Passing control into the Driver Execution Environment (DXE) phase.

Rust std implementation should not be used here. In fact, even the {arch}-unknown-uefi target is not meant to be used in this phase.

DXE – Driver Execution Environment

There are several components in the DXE phase:

DXE Foundation
DXE Dispatcher
A set of DXE Drivers

Rust std implementation can be used here.

BDS – Boot Device Select

The BDS phase is responsible for the following:

Initializing console devices
Loading device drivers
Attempting to load and execute boot selections

Rust std implementation can be used here.

TSL – Transient System Load

This is the stage between boot device selection and handoff to the OS. At this point, one may enter the UEFI shell or execute a UEFI application such as the OS boot loader.

Rust std implementation can be used here.

RT – Runtime

The UEFI hands off to the operating system (OS) after ExitBootServices() is executed. A UEFI-compatible OS is now responsible for exiting boot services triggering the firmware to unload all no longer needed code and data, leaving only runtime services code/data, e.g., SMM and ACPI.[86] A typical modern OS will prefer to use its own programs (such as kernel drivers) to control hardware devices.

Since any UEFI stuff still running needs to be started in one of the earlier stages, it is possible to use Rust std. However, it is up to the developer to deal with dangling/invalid pointers once ExitBootServices is called.

Also, the allocator, console, and a lot of other stuff are unavailable at this point. While the std will try to ensure the invalid pointers are not accessed, it cannot provide functionality that no longer exists.

I will not recommend using Rust std for writing Runtime Drivers unless you are absolutely sure of what you are doing.

AL - After Life

The After Life (AL) phase consists of persistent UEFI drivers used for storing the state of the system during the OS orderly shutdown, sleep, hibernate or restart processes.

Similar to RT, I would not recommend using Rust std in this phase.

Handling ExitBootServices()

The Rust std now registers a callback when EVT_SIGNAL_EXIT_BOOT_SERVICES is signaled. This callback makes BootServices unavailable. The most significant consequence of this is that the provided Allocator no longer works.

Since, all the memory in Rust std is allocated with the memory type EfiLoaderData, it is not really valid at after this point. Feel free to comment at the PR if you would like to see this configurable.

An additional function, boot_services has been added under std::os::uefi::env. This function ensures that BootServices are still valid before returning the pointer. However, it is still possible to circumvent this by just directly using the system_table function.

Conclusion

Hopefully, this post will clarify when and where Rust std for UEFI should be used.

Consider supporting me if you like my work.

Helpful Resources

Compiler generate custom entry for any target

Ayush — Sat, 18 Mar 2023 10:38:12 +0000

Hello everyone. While implementing Rust std for UEFI, I came across an interesting problem. The signature of the entry function in Rust did not match the UEFI entry signature. Initially, I just used a hacky way to get things to work. However, later I made some changes to upstream Rust to make generating entry functions with custom signatures much easier. In this post, I will show how to implement generating such an entry function in upstream Rust through the example of UEFI.

Read my prior post for an in-depth explanation of everything that goes on before Rust main.

Background

UEFI expects the entry function to have the following signature:

use r_efi::efi;

extern "efiapi" fn _start(image_handle: efi::Handle, system_table: *mut efi::SystemTable) -> efi::Status;

Currently, the Rust compiler generates a custom LLVM function that calls the Rust entry. In earlier versions of Rust, generating a custom entry function would have needed modification to many different modules in upstream Rust. However, since #104045 and #104001 have been merged, only a few files need to be modified.

It is important to note that the Rust lang_start has the following signature:

fn lang_start<T: crate::process::Termination + 'static>(
    main: fn() -> T,
    argc: isize,
    argv: *const *const u8,
) -> isize;

Thus even a custom entry function has to finally call this lang_start.

Implementation

Now I will go through the two main steps needed for custom entry function.

Modifying Target spec

The target spec now contains the entry function's name and ABI. This means it is also possible to modify the name and ABI by using a target specification Json instead of modifying the compiler.

For the UEFI entry name, we need to modify compiler/rustc_target/src/spec/uefi_msvc_base.rs:

diff --git a/compiler/rustc_target/src/spec/uefi_msvc_base.rs b/compiler/rustc_target/src/spec/uefi_msvc_base.rs
index 8968d3c8fc1..a50a55ad7e0 100644
--- a/compiler/rustc_target/src/spec/uefi_msvc_base.rs
+++ b/compiler/rustc_target/src/spec/uefi_msvc_base.rs
@@ -46,6 +46,7 @@ pub fn opts() -> TargetOptions {
         stack_probes: StackProbeType::Call,
         singlethread: true,
         linker: Some("rust-lld".into()),
+ entry_name: "efi_main".into(),
         ..base
     }
 }

For the entry ABI, we need to modify compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs:

diff --git a/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs b/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs
index a7ae17839da..9bc74ad2999 100644
--- a/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs
+++ b/compiler/rustc_target/src/spec/x86_64_unknown_uefi.rs
@@ -5,12 +5,13 @@
 // The win64 ABI is used. It differs from the sysv64 ABI, so we must use a windows target with
 // LLVM. "x86_64-unknown-windows" is used to get the minimal subset of windows-specific features.

-use crate::spec::Target;
+use crate::{abi::call::Conv, spec::Target};

 pub fn target() -> Target {
     let mut base = super::uefi_msvc_base::opts();
     base.cpu = "x86-64".into();
     base.max_atomic_width = Some(64);
+ base.entry_abi = Conv::X86_64Win64;

     // We disable MMX and SSE for now, even though UEFI allows using them. Problem is, you have to
     // enable these CPU features explicitly before their first use, otherwise their instructions

Implement LLVM entry generation

Now we need to implement the actual LLVM code to generate for our target. For UEFI, we will pass the SystemTable and ImageHandle in argv and set the value of argc to 2. For this, we need to make the following changes to compiler/rustc_codegen_ssa/src/base.rs:

diff --git a/compiler/rustc_codegen_ssa/src/base.rs b/compiler/rustc_codegen_ssa/src/base.rs
index abc510e360d..8be75552efd 100644
--- a/compiler/rustc_codegen_ssa/src/base.rs
+++ b/compiler/rustc_codegen_ssa/src/base.rs
@@ -430,9 +430,11 @@ fn create_entry_fn<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
         rust_main_def_id: DefId,
         entry_type: EntryFnType,
     ) -> Bx::Function {
- // The entry function is either `int main(void)` or `int main(int argc, char **argv)`,
- // depending on whether the target needs `argc` and `argv` to be passed in.
- let llfty = if cx.sess().target.main_needs_argc_argv {
+ // The entry function is either `int main(void)` or `int main(int argc, char **argv)`, or
+ // `Status efi_main(Handle hd, SystemTable *st)` depending on the target.
+ let llfty = if cx.sess().target.os.contains("uefi") {
+ cx.type_func(&[cx.type_i8p(), cx.type_i8p()], cx.type_isize())
+ } else if cx.sess().target.main_needs_argc_argv {
             cx.type_func(&[cx.type_int(), cx.type_ptr_to(cx.type_i8p())], cx.type_int())
         } else {
             cx.type_func(&[], cx.type_int())
@@ -496,8 +498,12 @@ fn create_entry_fn<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
         };

         let result = bx.call(start_ty, None, start_fn, &args, None);
- let cast = bx.intcast(result, cx.type_int(), true);
- bx.ret(cast);
+ if cx.sess().target.os.contains("uefi") {
+ bx.ret(result);
+ } else {
+ let cast = bx.intcast(result, cx.type_int(), true);
+ bx.ret(cast);
+ }

         llfn
     }
@@ -508,7 +514,18 @@ fn get_argc_argv<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
     cx: &'a Bx::CodegenCx,
     bx: &mut Bx,
 ) -> (Bx::Value, Bx::Value) {
- if cx.sess().target.main_needs_argc_argv {
+ if cx.sess().target.os.contains("uefi") {
+ // Params for UEFI
+ let param_handle = bx.get_param(0);
+ let param_system_table = bx.get_param(1);
+ let arg_argc = bx.const_int(cx.type_isize(), 2);
+ let arg_argv = bx.alloca(cx.type_array(cx.type_i8p(), 2), Align::ONE);
+ bx.store(param_handle, arg_argv, Align::ONE);
+ let arg_argv_el1 =
+ bx.gep(cx.type_ptr_to(cx.type_i8()), arg_argv, &[bx.const_int(cx.type_int(), 1)]);
+ bx.store(param_system_table, arg_argv_el1, Align::ONE);
+ (arg_argc, arg_argv)
+ } else if cx.sess().target.main_needs_argc_argv {
         // Params from native `main()` used as args for rust start function
         let param_argc = bx.get_param(0);
         let param_argv = bx.get_param(1);

Note: While the generation code seems to use i8 pointers, the generated LLVM IR actually uses Opque Pointers.

Conclusion

As outlined in this post, it should now be much easier to implement generating custom entry functions for Rust targets. This can be especially useful for embedded or some custom OS use cases.

Consider supporting me if you like my work.

Validating Json Request in axum

Ayush — Tue, 17 Jan 2023 13:31:12 +0000

I have been playing around with axum, and it has been quite a fun web framework. While using it, I came across what is a relatively common use case of validating the request JSON. However, I could not find any extractor for this. Thus I decided to write my own and share it with everyone. While I haven't put it in a crate, feel free to use the code as you wish.

Axum Extractors

An extractor allows us to pick apart the incoming request to get the parts our HTTP handler needs. More about extractors can be found here. There are two important traits when talking about extractors:

FromRequestParts: This is used if the extractor does not need access to the request body.
FromRequest: This is used if the extractor does need access to the request body. (we will be using this)

Implementation

I will use validator crate for the actual validation.

Here is the code for our validated JSON extractor:

use axum::{async_trait, extract::FromRequest, Json, RequestExt};
use hyper::{Request, StatusCode};
use validator::Validate;

pub struct ValidatedJson<J>(pub J);

#[async_trait]
impl<S, B, J> FromRequest<S, B> for ValidatedJson<J>
where
    B: Send + 'static,
    S: Send + Sync,
    J: Validate + 'static,
    Json<J>: FromRequest<(), B>,
{
    type Rejection = (StatusCode, &'static str);

    async fn from_request(req: Request<B>, _state: &S) -> Result<Self, Self::Rejection> {
        let Json(data) = req
            .extract::<Json<J>, _>()
            .await
            .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid JSON body"))?;
        data.validate()
            .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid JSON body"))?;
        Ok(Self(data))
    }
}

I am using (StatusCode, &'static str) for error response since all the responses in my server are of this type. Feel free to use whatever you prefer.

It is important to note that extractors can use other extractors themselves. So we do not need to replicate the Json extractor.

Conclusion

As you can see, writing a custom extractor is relatively straightforward, especially when compared to writing a tower middleware.

Using Rust main from custom entry point (Part 3)

Ayush — Thu, 27 Oct 2022 16:52:12 +0000

Even though GSoC 2022 has ended, I am still working on getting Rust std PR merged into the master. In the initial PR, I still used the entry function described in the prior post. However, this had many limitations, and thus I have finally transitioned to using a compiler-generated entry function.

Limitations of the older method

In the initial PR, I used an extern efi_main function called the compiler-generated main function. This had the following limitations:

The efi_main function is generated in all projects using std. This means it will be present when using the no_main attribute or library crate, thus diminishing the usefulness of std in libraries and drivers. It also rules out anything that does not want to use Heap allocation since Rust does some Heap allocations during the runtime setup.
Trying to pass pointers to SystemTable and ImageHandle as argv caused errors when building in release mode. This meant I was doing initialization from a function with no runtime setup and could thus cause all kinds of UB in case of panics.
Added a layer of redirection.

The new implementation

If you are unaware of everything that goes on before Rust main, then you should read my previous post about this. I am replacing the compiler-generated C main in the new implementation with the Win64 efi_main function. Inspecting the LLVM-IR of a simple application, we can see the generated efi_main:

; Function Attrs: noredzone nounwind
define win64cc i64 @efi_main(ptr %0, ptr %1) unnamed_addr #4 {
top:
  %_9.i = alloca ptr, align 8
  %2 = alloca [2 x ptr], align 8
  store ptr %0, ptr %2, align 8
  %3 = getelementptr inbounds ptr, ptr %2, i64 1
  store ptr %1, ptr %3, align 8
  call void @llvm.lifetime.start.p0(i64 8, ptr nonnull %_9.i)
  store ptr @_ZN11hello_world4main17h57c4996130ab67deE, ptr %_9.i, align 8
; call std::rt::lang_start_internal
  %4 = call i64 @_ZN3std2rt19lang_start_internal17hd4c288149f777b4aE(ptr noundef nonnull align 1 %_9.i, ptr noalias noundef nonnull readonly align 8 dereferenceable(24) @vtable.0, i64 2, ptr nonnull %2, i8 2) #6
  call void @llvm.lifetime.end.p0(i64 8, ptr nonnull %_9.i)
  ret i64 %4
}

What this function does is pass an array [ImageHandle, *mut SystemTable] as argv and 2 as argc to Rust lang_start. We then initialize the global variables from Rust sys::init() function.

Benefits of new implementation

no_main attribute works as intended now since std::os::uefi::init() is part of public API, this allows using Rust std in cases where we want to initialize something before the Heap is available (in some driver) but would still like to use std after initialization.
Allows UEFI to work like all other Rust platforms since efi_main is only generated in places where C main would typically be generated.
It seems to improve startup speed.

Conclusion

With this implementation, one of the major blockers for the PR has been resolved. While implementing this, I also modified the Rust target specification to allow specifying the Entry Function name and ABI, which might enable making compiler-generated entry functions easier for other targets. Feel free to comment on the PR and follow it if interested.

Helpful Links

GSoC22: Final Blog Post

Ayush — Mon, 05 Sep 2022 16:52:12 +0000

Hello everyone. This is probably the final blog post I write before Google Summer of Code 2022 ends (hopefully not the final uefi one). In this post, I will summarize my GSoC22 work to make it more accessible to everyone.

PRs

Just a list of all PRs I opened as a part of GSoC22. While other people created some additional PRs to fix problems I found during my work; I do not include them since I wasn’t the one who found the solution for those.

Blog Posts

Conclusion

I will continue working on getting Rust std PR merged since it is still unmerged. I also have some more UEFI Rust Projects lined up, and I think I will keep working on them for the foreseeable future. Feel free to check out and experiment with using Rust for UEFI (with or without std).

Writing UEFI Protocol in Rust

Ayush — Sat, 27 Aug 2022 16:52:12 +0000

Hello everyone. As a part of Porting Rust std for UEFI, I had to write a hacky implementation of pipes (using UEFI Variables) for piping output from launched programs. However, this implementation had some problems and failed to run tests using the feature panic_abort_tests.

Since I had some time this week, I decided to write a Protocol to fix the pipes. Along the way, I also found many ways to shoot myself on foot. So I decided to write this post documenting all the gotchas I discovered while writing a new protocol in Rust. This post will only contain 1 of the two protocols I decided to create, internally named UEFI_COMMAND_PROTOCOL.

Note: This Protocol is not public API and thus should not be relied upon/used outside of Rust std, at least for the foreseeable future.

Protocol Definition

The UEFI_COMMAND_PROTOCOL has a straightforward use: to share the Handles of pipes (stdout, stderr, stdin) with the image to be started. It might contain more stuff in the future, but for right now, that is all it does. It is installed on all UEFI executables launched using the Rust std::process::Command API and needs Pipes (In case they don’t need any kinds of Pipes, this Protocol will not be installed).

Structure

Here is the Rust Structure to define the Protocol:

#[repr(C)]
pub struct Protocol {
    pub stdout: r_efi::efi::Handle,
    pub stderr: r_efi::efi::Handle,
    pub stdin: r_efi::efi::Handle,
}

As you can see, there is not much to it.

Guid

Here is the protocol GUID:

pub const PROTOCOL_GUID: r_efi::efi::Guid = r_efi::efi::Guid::from_fields(
    0xc3cc5ede,
    0xb029,
    0x4daa,
    0xa5,
    0x5f,
    &[0x93, 0xf8, 0x82, 0x5b, 0x29, 0xe7],
);

Protocol Usage

When constructing and installing a Protocol from Rust, some things must be kept in mind. Here are some of the lessons I learned the hard way:

The Protocol should be non-movable

By default, all Rust variables are movable in memory. Once a UEFI Protocol is registered, it has to be valid until it is uninstalled. Installing a Protocol whose interface is on the stack can lead to all sorts of UB. In my particular case, I decided to use Heap allocated Protocol in std::box::Box. From what I understand, there are ways to move the contents of Box in memory. However, for my simple needs, it was sufficient since I was not performing any operations on Box once the Protocol was installed.

In practice, the code looks something like this:

let mut protocol = Box::new(uefi_command_protocol::new(stdout, stderr, stdin));
install_interface(&mut command handle, &mut protocol).unwrap();
// Do something with Command

For internal usage, I have wrappers that handle uninstalling the protocol on Drop to play nice with Rust memory management. It might be possible to have a better solution using rust std::pin::Pin wrapper, but I haven’t used it personally.

Use EFI_BOOT_SERVICES.InstallProtocolInterface() and EFI_BOOT_SERVICES.UninstallProtocolInterface()

Most modern UEFI drivers use the EFI_BOOT_SERVICES.InstallMultipleProtocolInterfaces() and EFI_BOOT_SERVICES.UninstallMultipleProtocolInterfaces() for installing and uninstalling protocols on a handle. However, rustc currently doesn’t support variable arguments for UEFI. For more information about this, you can look at this issue.

Taking care of lifetimes

You need to make sure to strictly define the lifetimes of protocols with their lifetimes as expected by UEFI. I wrote some structures in Rust std to make the internal working easier. However, having a difference in lifetimes can lead to everything ranging from CPU exceptions to an infinite loop.

Also take care of any data the protocol points to.

Taking care of Rust Drop Order

There will be cases when you want the strictly define the drop order of members of Protocol wrapper structures. I found this great answer for this. However, the rule of thumb is that Rust, by default, drops members in the same order they were declared. So make sure to keep this in mind.

Avoid storing Rust-specific types in Protocol

Storing dynamic data in UEFI Protocol is generally not a great idea. However, Rust-specific types (Vec, Box, etc) can lead to all kinds of UB since all Rust types are movable by default. I worked around this by storing pointers to a struct that wraps over the Rust-specific type. A simple example is the following:

struct PipeData {
    data: VecDequeue<u8>
}

#[repr(C)]
pub struct Protocol {
    data: *mut PipeData
}

Conclusion

Since there are not many examples of Rust usage in UEFI drivers, there are not many standard practices established yet. With this post, I hope to help anyone trying to use Rust for UEFI driver development. Finally, with the new UEFI_COMMAND_PROTOCOL and UEFI_PIPE_PROTOCOL, Rust std port can now use complete libtest (even should_panic, which was previously broken). This is useful since even if you go the no_std route, you can still use std to test your no_std code. Finally, feel free to check out Rust std for UEFI.

UEFI Rust std has a new home

Ayush — Fri, 05 Aug 2022 15:14:12 +0000

Hello everyone. All my work on UEFI Rust std has been moved to tianocore/rust. This should help with allowing more contribution from both Tianocore and Rust’s sides. This post is just a sort of introduction to the new repository and how to get started.

Documentation

The documentation of the std implementation for UEFI can be found at src/doc/rustc/src/platform-support/unknown-uefi.md. This can be built by using x.py:

./x.py doc src/doc/rustc/ --open

It outlines the requirements and the limitations of the current std for UEFI. It also contains a few examples to get users started.

Development Workflow

The tianocore/rust repository accepts PRs. I will also accept patches in the edk2 mailing list (my email: ayushdevel1325@gmail.com).

Running Tests locally

Running Tests for UEFI is done using remote-test-server and remote-test-client as outlined in my previous post. The only thing I would like to change from that guide is the command to run tests:

RUST_TEST_THREADS=1 TEST_DEVICE_ADDR="localhost:12345" ./x.py test src/test/ui/{FILE or Directory} --target x86_64-unknown-uefi --stage 1

Running tests in single-threaded, even on the host side, fixes a lot of tests that fail due to timeout.

Conclusion

This post was just to spread the word about this work so more people can experiment and provide their feedback about it.

Writing an Allocator for UEFI

Ayush — Thu, 23 Jun 2022 11:15:12 +0000

Hello everyone, we will discuss how to write the Allocator for UEFI in this post. More specifically, the Allocator is for the DEX phase in UEFI. We will be using uefi-spec-rs, which is my wrapper around r-efi for use in the std.

UEFI Memory Memory Management Services

First, let us look at the Memory Management Services we will be using in UEFI.

AllocatePool

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_ALLOCATE_POOL) (
  IN EFI_MEMORY_TYPE PoolType,
  IN UINTN Size,
  OUT VOID **Buffer
);

Description

This function allocates a memory region of Size bytes from the memory of type PoolType and returns the address of the allocated memory in the location referenced by Buffer. This function allocates pages from EfiConventionalMemory as needed to grow the requested pool type.

Note: All allocations are eight-byte aligned.

Status Codes Returned

EFI_SUCCESS : The requested number of bytes was allocated.
EFI_OUT_OF_RESOURCES : The pool requested could not be allocated.
EFI_INVALID_PARAMETER : PoolType is in the range EfiMaxMemoryType..0x6FFFFFFF.
EFI_INVALID_PARAMETER : PoolType is EfiPersistentMemory.
EFI_INVALID_PARAMETER : Buffer is NULL.

FreePool

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_FREE_POOL) (
  IN VOID *Buffer
);

Description

This function returns the memory specified by Buffer to the system. In return, the memory’s type is EfiConventionalMemory. The freed Buffer must have been allocated by AllocatePool().

Status Code Returned

EFI_SUCCESS : The memory was returned to the system.
EFI_INVALID_PARAMETER : Buffer was invalid.

Writing a basic allocator

First, we will write an allocator which works for alignment <= 8 bytes. To make a global allocator, we need to implement the’ GlobalAlloc’ trait. In the case of std, we would implement this trait on the System allocator. However, since I would like to test things out, I will be implementing the allocator as an example in the uefi-spec-rs crate.

static mut GLOBAL_SYSTEM_TABLE: GlobalData<efi::SystemTable> = GlobalData::new();

#[global_allocator]
static GLOBAL_ALLOCATOR: Allocator = Allocator;

struct Allocator;

unsafe impl GlobalAlloc for Allocator {
    unsafe fn alloc(&self, layout: core::alloc::Layout) -> *mut u8 {
      todo!()
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: core::alloc::Layout) {
      todo!()
    }
}

Here we create an empty struct (Allocator) as a placeholder for System and implement GlobalAlloc on it. The GLOBAL_SYSTEM_TABLE stores an AtomicPtr to the SystemTable. I will also be adding a way to access the SystemTable in std::os::uefi. However, I will not be exposing the static mutable variable there.

Implement alloc

Firstly, we need to be aware of a few things:

The layout.size() supplied in GlobalAlloc can be 0. It is up to the implementation to check for that case.
According to docs, we should return the NULL pointer in case of errors.
The alloc function should not unwind.

Keeping all that in mind, here is the basic implementation of alloc:

unsafe fn alloc(&self, layout: core::alloc::Layout) -> *mut u8 {
    let st = unsafe {
        match GLOBAL_SYSTEM_TABLE.get_mut() {
            Ok(x) => x,
            Err(_) => return core::ptr::null_mut(),
        }
    };


    let mut ptr: *mut core::ffi::c_void = core::ptr::null_mut();
    let align = layout.align();
    let size = layout.size();

    if size == 0 || align > 8 {
        return core::ptr::null_mut();
    }

    let r = memory_allocation_services::allocate_pool(st, efi::LOADER_DATA, size, &mut ptr);

    if r.is_err() || ptr.is_null() {
        return core::ptr::null_mut();
    }

    ptr.cast()
}

This is pretty simple. We fail for alignment > 0. we also fail if the ptr is null after allocation or if the error status is returned.

Implement dealloc

We need to check that size is non-zero. The only error that FreePool() returns is in the case of invalid ptr, so ideally, this should not happen in System allocator. However, I am adding the assert for now to improve debugging. That assert will probably be removed in production.

unsafe fn dealloc(&self, ptr: *mut u8, layout: core::alloc::Layout) {
    let st = unsafe {
        match GLOBAL_SYSTEM_TABLE.get_mut() {
            Ok(x) => x,
            Err(_) => return core::ptr::null_mut(),
        }
    };

    if layout.size() != 0 {
        let r = memory_allocation_services::free_pool(st, ptr.cast());
        assert!(r.is_ok());
    }
}

Testing the new allocator

We just add a efi_main function that initializes the GLOBAL_SYSTEM_TABLE and we should be good to use the alloc types:

pub fn efi_run() -> efi::Status {
    let st = unsafe {
        match GLOBAL_SYSTEM_TABLE.get_mut() {
            Ok(x) => x,
            Err(_) => return efi::Status::ABORTED,
        }
    };

    let s: String;
    let mut v: Vec<u16>;

    // Create string and convert to UTF-16. We need a terminating NUL, since UEFI uses C-String
    // style wide-strings.
    s = String::from("Hello World!\n");
    v = s.encode_utf16().collect();
    v.push(0);

    // Print the string on console-out.
    let r = simple_text_output::output_string(st, v.as_mut_slice());
    if r.is_err() {
        efi::Status::ABORTED
    } else {
        efi::Status::SUCCESS
    }
}

#[export_name = "efi_main"]
pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
    let r = unsafe { GLOBAL_SYSTEM_TABLE.init(st) };
    if r.is_err() {
        return efi::Status::ABORTED;
    }

    efi_run()
}

This example works as expected.

Getting allocations > 8-byte align to work

While the previous allocator works for many cases, there is a clever way to work around the 8-byte alignment limit. This is used in the windows allocator as well as r-efi-alloc.

Implement alloc

The new alloc function looks like this:

unsafe fn alloc(&self, layout: core::alloc::Layout) -> *mut u8 {
    let st = unsafe {
        match GLOBAL_SYSTEM_TABLE.get_mut() {
            Ok(x) => x,
            Err(_) => return core::ptr::null_mut(),
        }
    };

    let align = layout.align();
    let size = layout.size();

    if size == 0 {
        return core::ptr::null_mut();
    }

    let mut ptr: *mut core::ffi::c_void = core::ptr::null_mut();
    let aligned_size = align_size(size, align);

    let r =
        memory_allocation_services::allocate_pool(st, efi::LOADER_DATA, aligned_size, &mut ptr);

    if r.is_err() || ptr.is_null() {
        return core::ptr::null_mut();
    }

    unsafe { align_ptr(ptr.cast(), align) }
}

The magic happens in the align_size and the align_ptr functions.

In align_size function, we just allocate extra padding in case align is greater than 8. This padding will later be used in the align_ptr function.

fn align_size(size: usize, align: usize) -> usize {
    if align > POOL_ALIGNMENT {
        // Allocate extra padding in order to be able to satisfy the alignment.
        size + align
    } else {
        size
    }
}

In the align_ptr function we store the original address as Header in front of the aligned_ptr.

#[repr(C)]
struct Header(*mut u8);

unsafe fn align_ptr(ptr: *mut u8, align: usize) -> *mut u8 {
    if align > POOL_ALIGNMENT {
        let offset = align - (ptr.addr() & (align - 1));

        // SAFETY: `MIN_ALIGN` <= `offset` <= `layout.align()` and the size of the allocated
        // block is `layout.align() + layout.size()`. `aligned` will thus be a correctly aligned
        // pointer inside the allocated block with at least `layout.size()` bytes after it and at
        // least `MIN_ALIGN` bytes of padding before it.
        let aligned = unsafe { ptr.add(offset) };

        // SAFETY: Because the size and alignment of a header is <= `MIN_ALIGN` and `aligned`
        // is aligned to at least `MIN_ALIGN` and has at least `MIN_ALIGN` bytes of padding before
        // it, it is safe to write a header directly before it.
        unsafe { core::ptr::write((aligned as *mut Header).offset(-1), Header(ptr)) };

        aligned
    } else {
        ptr
    }
}

Note: the align_ptr function assumes that the allocation size has been increased beforehand by align_size.

Implement dealloc

The new dealloc looks like this:

unsafe fn dealloc(&self, ptr: *mut u8, layout: core::alloc::Layout) {
    let st = unsafe {
        match GLOBAL_SYSTEM_TABLE.get_mut() {
            Ok(x) => x,
            Err(_) => return,
        }
    };

    if layout.size() != 0 {
        let ptr = unsafe { unalign_ptr(ptr, layout.align()) };
        let r = memory_allocation_services::free_pool(st, ptr.cast());
        assert!(r.is_ok());
    }
}

The unalign_ptr function basically undoes what the align_ptr function did and gives back the original pointer.

#[inline]
unsafe fn unalign_ptr(ptr: *mut u8, align: usize) -> *mut u8 {
    if align > POOL_ALIGNMENT {
        // SAFETY: Because of the contract of `System`, `ptr` is guaranteed to be non-null
        // and have a header readable directly before it.
        unsafe { core::ptr::read((ptr as *mut Header).offset(-1)).0 }
    } else {
        ptr
    }
}

The same example as before should work even now without any change.

Conclusion

With this, we now have a global allocator. I will soon be integrating it into the Rust std. In the next post, we will discuss implementing stdin for UEFI.

Helpful Links

uefi-spec-rs

Using Rust main from a custom entry point

Ayush — Mon, 20 Jun 2022 18:42:12 +0000

Hello everyone. In this post, we will deep dive into the crux of the main() function and look behind the scenes. By the end, we will have some understanding of Rust runtime. Primarily, I will describe my current implementation of efi_main to hook into Rust runtime.

C Runtime

First, we need to get some things out of the way. In “C”, the first function is not int main(int argc, char *argv[]). While this might surprise some of you, C does have a runtime, and it is called Crt0. It is mostly written in assembly and linked to almost every C Program. This example is for Linux x86-64 with AT&T syntax, without an actual C runtime.

.text

.globl _start

_start: # _start is the entry point known to the linker
    xor %ebp, %ebp # effectively RBP := 0, mark the end of stack frames
    mov (%rsp), %edi # get argc from the stack (implicitly zero-extended to 64-bit)
    lea 8(%rsp), %rsi # take the address of argv from the stack
    lea 16(%rsp,%rdi,8), %rdx # take the address of envp from the stack
    xor %eax, %eax # per ABI and compatibility with icc
    call main # %edi, %rsi, %rdx are the three args (of which first two are C standard) to main

    mov %eax, %edi # transfer the return of main to the first argument of _exit
    xor %eax, %eax # per ABI and compatibility with icc
    call _exit # terminate the program

This _start function then calls the all too familiar main function in C. With this out of the way; we are now going to talk about Rust Runtime and all the things behind the scenes that make a simple “Hello World” program work.

Rust Runtime

Everyone can already guess that the Rust runtime is much more complicated than the C Runtime. Also, almost every OS is very well integrated with C, while Rust must do most of the heavy lifting of integrating with the OS itself. If you want a detailed explanation, you should look at Michael Gattozzi’s blog post which goes into great detail about it.

I will give you a quick tldr: “C” main() -> “Rust” lang_start -> “Rust” lang_start_internal -> “Rust” init() -> “Rust” sys::init() -> “Rust” main().

Is everyone still with me? Good. Now I will briefly explain all the functions I just mentioned.

C main()

This is generated by rustc. Taking a look at code at compiler/rustc_codegen_ssa/src/base.rs:

    fn create_entry_fn<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
        cx: &'a Bx::CodegenCx,
        rust_main: Bx::Value,
        rust_main_def_id: DefId,
        use_start_lang_item: bool,
    ) -> Bx::Function {
        // The entry function is either `int main(void)` or `int main(int argc, char **argv)`,
        // depending on whether the target needs `argc` and `argv` to be passed in.
        let llfty = if cx.sess().target.main_needs_argc_argv {
            cx.type_func(&[cx.type_int(), cx.type_ptr_to(cx.type_i8p())], cx.type_int())
        } else {
            cx.type_func(&[], cx.type_int())
        };
...

As we can see, one of the two signatures of `main` is used. Incidentally, as you can see, neither of these main functions has a signature valid for UEFI, but that’s not too important right now.

This generated `main` basically calls the following function on the list, i.e., `lang_start`.

### Rust lang\_start()

This function is pretty simple, it just calls the `lang_start_internal`. Incidently, this can also be defined by us if we want. The issue tracking this can be found [here](https://github.com/rust-lang/rust/issues/29633). This function signature is as follows:

rust
fn lang_start(
main: fn() -> T,
argc: isize,
argv: *const *const u8,
) -> isize;


### Rust lang\_start\_internal()

It basically calls the `init` and then the `main` function. It also prevents unwinding in the `init` and `main` functions, which is a requirement. The function signature is as follows:

rust
fn lang_start_internal(
main: &(dyn Fn() -> i32 + Sync + crate::panic::RefUnwindSafe),
argc: isize,
argv: *const *const u8,
) -> Result {


### Rust init()

This function sets up stack\_guard for the current thread. It also calls the `sys::init()` function. The signature for it is the following:

rust
unsafe fn init(argc: isize, argv: *const *const u8);


This is also the function where heap memory starts coming to play.

### Rust sys::init()

This function sets up platform-specific stuff. This is just an empty function on some platforms, while it does a lot of stuff on others. It is generally defined under `std/sys/<platform>/mod.rs` The function signature is as follows:

rust
pub fn init(argc: isize, argv: *const *const u8) {


### Rust main()

This is the function where most normal programs start execution. By this point, it is assumed that all the `std` stuff that needs initialization must be done and available for the user.

## But wait, who calls the C main()?

This is precisely the question I had after reading about all these functions. The answer, though, is a bit less clear. It depends on the platform. The OS `crt0` on most platforms calls the C `main`. On others, well, people just seem to use a custom entry point like `efi_main` and not use `main()`. Since I wanted to use `main` but had a custom entry point with a custom signature, I had to do a hacky implementation to make things work.



## Using efi\_main() with Rust runtime

Since we have established that Rust generates a C `main` function for every Rust program, all we need to do is call `main` and be done with it. However, the problem is how to pass SystemTable and SystemHandle to Rust. Without those pointers, we cannot do much in UEFI. Thus they need to be stored globally somewhere.

After some thought, I have concluded that I will do it in the `sys::init()` function rather than the `efi_main`. The reasons for this are as follows:

1. The `efi_main` currently calls to “C” `main`, so we are jumping language boundaries here.
2. At some point, I would like to replace the `efi_main` with an autogenerated function or even a function written in assembly. For now, I am writing it in Rust, but that might not be the case in the future. Thus it should be as less complicated as possible.
3. `sys::init` seems kinda the natural place for it.

Now, the question is how to get it to reach `sys::init()`. The answer is pretty simple. We can use pointers.

My current implementation looks like the following:

rust

[no_mangle]

pub unsafe extern "efiapi" fn efi_main(
handle: efi::Handle,
st: *mut efi::SystemTable,
) -> efi::Status {
const argc: isize = 2;
let handle_ptr: *const u8 = handle.cast();
let st_ptr: *const u8 = st.cast();
let argv: *const *const u8 = [handle_ptr, st_ptr, core::ptr::null()].as_ptr();

match main(argc, argv) {
    0 => {
        print_pass(st);
        efi::Status::SUCCESS
    }
    _ => {
        print_fail(st);
        efi::Status::ABORTED
    } // Or some other status code
}

}


I just cast both SystemTable and SystemHandle pointers as `*const u8` in the `efi_main`. Then in the `sys::init()`, I cast them back to their original selves. The null at the end is something someone in zulipchat suggested.

And well, it kind of works. This simple hack allows us to get the SystemTable and SystemHandle all the way to `sys::init()`. They can be accessed in the following way:

rust
pub unsafe fn init(argc: isize, argv: *const *const u8) {
let args: &[*const u8] = unsafe { crate::slice::from_raw_parts(argv, argc as usize) };

let handle: r_efi::efi::Handle = args[0] as r_efi::efi::Handle;
let st: *mut r_efi::efi::SystemTable = args[1] as *mut r_efi::efi::SystemTable;

}


Now comes the catch, if we look at the function calling this, the line where the new Thread is created needs an allocator, or else it panics.

rust
// One-time runtime initialization.
// Runs before main.
// SAFETY: must be called only once during runtime initialization.
// NOTE: this is not guaranteed to run, for example when Rust code is called externally.

[cfg_attr(test, allow(dead_code))]

unsafe fn init(argc: isize, argv: *const *const u8) {
unsafe {
sys::init(argc, argv);

    let main_guard = sys::thread::guard::init();
    // Next, set up the current Thread with the guard information we just
    // created. Note that this isn't necessary in general for new threads,
    // but we just do this to name the main thread and to give it correct
    // info about the stack bounds.
    let thread = Thread::new(Some(rtunwrap!(Ok, CString::new("main"))));
    thread_info::set(main_guard, thread);
}

}




We can add a `return` before the thread creation and get to `main` perfectly. However, that is a bit of cheating, so this is where I will leave it for now.



## Conclusion

Initially, I set out to print “Hello World” from `main` in this post. However, after getting burned multiple times, I have finally decided to save it for later. The following post will look at creating and initializing the System Allocator. Spoiler, the `thread_info::set` will start panicking after that, so we will not be able to print “Hello World” even in the next post. Still, we are one step closer to a usable std for UEFI.



## Helpful Links

1. [Rust’s Runtime Post by Michael Gattozzi](https://blog.mgattozzi.dev/rusts-runtime/)

Use Restricted std in UEFI

Ayush — Thu, 16 Jun 2022 00:00:00 +0000

Hello Everyone; in my last post, I set up the development environment for working on adding Rust support for UEFI. In this post, I will get a restricted version of std (basically a glorified core + alloc) to work for the x86_64 UEFI target. We will be starting with the no_std hello_world program from the last post.

Add env module for UEFI in std

Add uefi Module

First, I will add uefi module under library/std/src/sys. To do this, we will create a new file library/std/src/sys/uefi/mod.rs. We will point everything other than the env module to the unsupported module. The contents of library/std/src/sys/uefi/mod.rs are given below:

//! Platform-specific extensions to `std` for UEFI platforms.
//!
//! Provides access to platform-level information on UEFI platforms, and
//! exposes Unix-specific functions that would otherwise be inappropriate as
//! part of the core `std` library.
//!
//! It exposes more ways to deal with platform-specific strings ([`OsStr`],
//! [`OsString`]), allows to set permissions more granularly, extract low-level
//! file descriptors from files and sockets, and has platform-specific helpers
//! for spawning processes.
//!
//! [`OsStr`]: crate::ffi::OsStr
//! [`OsString`]: crate::ffi::OsString

#![deny(unsafe_op_in_unsafe_fn)]

#[path = "../unsupported/alloc.rs"]
pub mod alloc;
#[path = "../unsupported/args.rs"]
pub mod args;
#[path = "../unix/cmath.rs"]
pub mod cmath;
pub mod env;
#[path = "../unsupported/fs.rs"]
pub mod fs;
#[path = "../unsupported/io.rs"]
pub mod io;
#[path = "../unsupported/locks/mod.rs"]
pub mod locks;
#[path = "../unsupported/net.rs"]
pub mod net;
#[path = "../unsupported/os.rs"]
pub mod os;
#[path = "../windows/os_str.rs"]
pub mod os_str;
#[path = "../unix/path.rs"]
pub mod path;
#[path = "../unsupported/pipe.rs"]
pub mod pipe;
#[path = "../unsupported/process.rs"]
pub mod process;
#[path = "../unsupported/stdio.rs"]
pub mod stdio;
#[path = "../unsupported/thread.rs"]
pub mod thread;
#[path = "../unsupported/thread_local_key.rs"]
pub mod thread_local_key;
#[path = "../unsupported/time.rs"]
pub mod time;

#[path = "../unsupported/common.rs"]
#[deny(unsafe_op_in_unsafe_fn)]
mod common;
pub use common::*;

As you can see, cmath, os_str, and path point to the unix or windows module instead of unsupported. This is because unsupported does not provide any definition for those. The cmath unix module API can be provided by compiler-builtins, so that should work. However, os_str and path are simply placeholders for now.

Implement env module

The env module is very basic and we just need to define a few constants for it. Here are the contents of library/std/src/sys/uefi/env.rs:

pub mod os {
    pub const FAMILY: &str = "";
    pub const OS: &str = "";
    pub const DLL_PREFIX: &str = "";
    pub const DLL_SUFFIX: &str = "";
    pub const DLL_EXTENSION: &str = "";
    pub const EXE_SUFFIX: &str = ".efi";
    pub const EXE_EXTENSION: &str = "efi";
}

Export UEFI module contents

This can be done by adding the following lines to library/std/sys/mod.rs:

     } else if #[cfg(target_family = "wasm")] {
         mod wasm;
         pub use self::wasm::*;
+ } else if #[cfg(target_os = "uefi")] {
+ mod uefi;
+ pub use self::uefi::*;
     } else if #[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] {
         mod sgx;
         pub use self::sgx::*;

And we now have the env module implemented. These constants are exposed under std::env::consts.

Build the new toolchain

We will now need to build the toolchain again:

./x.py build --stage 1

stage1 should now be pointing to this new toolchain.

Now, we will try to print these constants to UEFI in a very primitive manner (since io, strings, etc have not been implemented yet).

Compile hello_world with std

Firstly, we will remove the no_std attribute and panic_handler from src/main.rs. Then we will update .cargo/config.toml with the following contents:

[unstable]
build-std = ["std", "compiler_builtins"]
build-std-features = ["compiler-builtins-mem"]

On trying to compile the project now, we get the following error:

error[E0463]: can't find crate for `panic_abort`

error[E0658]: use of unstable library feature 'restricted_std'
  |
  = help: add `#![feature(restricted_std)]` to the crate attributes to enable

Some errors have detailed explanations: E0463, E0658.
For more information about an error, try `rustc --explain E0463`.
error: could not compile `hello_world` due to 2 previous errors

The first error is a bug in build-std. It doesn’t know how to handle panic_abort vs panic_unwind, so it doesn’t use either crate, resulting in the above error. It can be fixed by adding panic_abort to .cargo/config.toml.

The second error can be fixed by adding the restricted_std feature to the src/main.rs.

Trying to build now and ………. It fails. We get the following error:

error: linking with `rust-lld` failed: exit status: 1
  |
  = note: "rust-lld" "-flavor" "link" "/NOLOGO" "/entry:efi_main" "/subsystem:efi_application" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/hello_world-bf96c91d419b97ff.3aumljakx58twtt1.rcgu.o" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/hello_world-bf96c91d419b97ff.11wx9iybsb4s2x54.rcgu.o" "/LIBPATH:/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps" "/LIBPATH:/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/debug/deps" "/LIBPATH:/var/home/ayush/Documents/Programming/Rust/rust/build/x86_64-unknown-linux-gnu/stage1/lib/rustlib/target/lib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libr_efi-44f0e2c98ca397ed.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libstd-0f82fcd1446bb823.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libpanic_abort-6267bb336da2fa77.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/librustc_demangle-12ba4dfb1ce0974e.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libstd_detect-af3466d26b0b584c.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libhashbrown-282ed18a03cc159e.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/librustc_std_workspace_alloc-d47af0fe9b191470.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libunwind-8ad628841136827a.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libcfg_if-f793ff480fd551b6.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/liblibc-249d18e9ef84acfd.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/liballoc-4b1b3794d0343e8a.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/librustc_std_workspace_core-3a7d1ce70363f171.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libcore-73e7a0474be04fb7.rlib" "/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/libcompiler_builtins-4f95060227077e02.rlib" "/NXCOMPAT" "/LIBPATH:/var/home/ayush/Documents/Programming/Rust/rust/build/x86_64-unknown-linux-gnu/stage1/lib/rustlib/target/lib" "/OUT:/var/home/ayush/Documents/Programming/Rust/uefi/hello_world/target/target/debug/deps/hello_world-bf96c91d419b97ff.efi" "/OPT:REF,NOICF" "/DEBUG" "/NODEFAULTLIB"
  = note: rust-lld: error: undefined symbol: __CxxFrameHandler3
          >>> referenced by libstd-0f82fcd1446bb823.rlib(std-0f82fcd1446bb823.std.ea9c30f6-cgu.2.rcgu.o):(.xdata)
          >>> referenced by libstd-0f82fcd1446bb823.rlib(std-0f82fcd1446bb823.std.ea9c30f6-cgu.2.rcgu.o):(.xdata)


error: could not compile `hello_world` due to previous error

This error is, well, a bit weird. We can fix the build for now by providing a blank implementation of __CxxFrameHandler3, but this needs more research. The following lines need to be added to src/main.rs:

#[no_mangle]
pub extern "C" fn __CxxFrameHandler3() {}

The application builds and runs fine now.

Print EXE_EXTENSION constant

Now we will print EXE_EXTENSION to the console. Since we do not have io and string implemented yet, we will have to do it in a primitive way using u16 arrays. The final src/main.rs is given below:

#![no_main]
#![feature(restricted_std)]

use r_efi::efi;
use std::env::consts;

#[no_mangle]
pub extern "C" fn __CxxFrameHandler3() {}

fn print_efi(s: &[u16], st: *mut efi::SystemTable) -> Result<(), r_efi::base::Status> {
    let r = unsafe { ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16) };

    if r.is_error() {
        Err(r)
    } else {
        Ok(())
    }
}

fn print_newline(st: *mut efi::SystemTable) -> Result<(), r_efi::base::Status> {
    let mut s = [0;2];
    create_const_uefi_str("\n", &mut s);
    print_efi(&s, st)
}

fn create_const_uefi_str(const_str: &str, uefi_array: &mut [u16]) {
    let mut i = 0;
    for v in const_str.bytes() {
        uefi_array[i] = v as u16;
        i += 1;
    }

    uefi_array[i] = 0x0000u16;
}

fn print_env_constants(st: *mut efi::SystemTable) -> Result<(), r_efi::base::Status> {
    let mut exe_extension_heading = [0; 16];
    create_const_uefi_str("exe_extension: ", &mut exe_extension_heading);
    print_efi(&exe_extension_heading, st)?;
    let mut exe_extension = [0; 5];
    create_const_uefi_str(consts::EXE_EXTENSION, &mut exe_extension);
    print_efi(&exe_extension, st)?;
    print_newline(st)
}

#[export_name = "efi_main"]
pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
    let r = print_env_constants(st);

    if let Err(x) = r {
        return x;
    }

   efi::Status::SUCCESS
}

Here is the program running under qemu:

With this, we are using our new std for UEFI.

Edit

The __CxxFrameHandler3 blank implementation is no longer required in the master branch. I was previously basing my changes on the v1.61.0 tag. However, from now, I am going to work on master directly.

Conclusion

Technically, we are now using std (even though none of it has yet been implemented). Now I will slowly start implementing parts of std starting with allocation. I also wanted to find a way to use the normal Rust main function instead of the current efi_main. However, this still does not seem possible (see #29633). So, let’s get allocation working and replace all the arrays with vectors in this code.

Google Summer of Code 2022

Ayush — Tue, 14 Jun 2022 00:00:00 +0000

Hello everyone, I am Ayush Singh, a second-year student at the Indian Institute of Technology, Dhanbad, India. As a part of Google Summer of Code 2022, I will be working on Adding Rust Support for building UEFI Applications and Modules under the Tianocore organization. In this post, I will describe this project’s goals and set up my development environment.

You can follow my GSoC-related blog posts using this feed. I will currently be working under my personal fork. In the future, it might be moved into the edk2-staging repository. The final goal is to have the support merged upstream. However, that might not be immediately possible.

Project Goals

The current project goals, as discussed with the mentors, are given below:

Get most of Rust-std running under the UEFI target
Add testing support for UEFI target
Pass all the general tests of library/std
Possibly add support for ARM and RISCV UEFI targets (currently, only X86_64, AARCH64, and I686 are present)

Setting up Development Environment

Setup Rust

Install Rustup

I will be using rustup to install and manage Rust since I will be working with multiple versions of standard libraries and compilers.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

It will ask for some options, but I just set it to default.

Install Rust toolchains

I will be installing stable as well as nightly toolchains. For Stable:

rustup toolchain install stable

For Nightly:

rustup toolchain install nightly

Finally, add ~/.cargo/bin to PATH. Alternatively, we can just source $HOME/.cargo/env.

Setup rust project

Setup Git Repository

I will mostly follow the Getting Started section of the rustc-dev-guide for this. First, we need to clone the rust-lang/rust repository. I prefer using ssh:

git clone git@github.com:rust-lang/rust.git

Next, I will add my personal fork as a remote:

git remote add personal git@github.com:Ayush1325/rust.git

Install depenencies

Rust repository contains a script (x.py) to help us install most of the dependencies we need and configures the bootstrapping process. However, since we need to compile to a different target, we need to build rust-lld, which requires extra dependencies. Since I am using Fedora, I will list the command I used to install dependencies:

sudo dnf install ccache cmake python ninja-build llvm-devel llvm-libunwind-devel zlib-devel lld clang clang-tools-extra qemu

Next, we will use the script to configure our build.

./x.py setup

Since I will mostly work on library/std, I select the library option during configuration. We will need to modify the generated config.toml since we will need rust-lld for cross-compilation. Here is my config.toml:

# Includes one of the default files in src/bootstrap/defaults
profile = "library"
changelog-seen = 2

[llvm]
download-ci-llvm = "if-available"
ccache = true

[rust]
lld = true
incremental = true

Build toolchain

Now, we will build the local toolchain using the following command:

./x.py build --stage 1

We build the stage1 compiler since we will need to use this compiler to build sample applications for testing (Since we cannot use the testing framework yet).

Finally, we will add this newly built toolchain using rustup:

rustup toolchain link stage1 build/x86_64-unknown-linux-gnu/stage1

Now we can use this toolchain to build any rust project.

Build a UEFI hello_world

Now to check that our new toolchain works, we will build a simple hello world application (no_std).

Create a binary application

cargo new hello_world

Configure Cargo

First, we need to add the r-efi crate to Cargo.toml as follows:

[dependencies]
r-efi = "4.0"

Next, we will add a file .cargo/config.toml to configure building core and alloc. This way we do not need to specify build-std option at the commmand line.

[unstable]
build-std = ["core", "compiler_builtins"]
build-std-features = ["compiler-builtins-mem"]

Finally, we will set the current project to use our local toolchain:

rustup override set stage1

Main Code

Here is the code for src/main.rs file:

#![no_main]
#![no_std]

use r_efi::efi;

#[panic_handler]
fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}

#[export_name = "efi_main"]
pub extern "C" fn main(_h: efi::Handle, st: *mut efi::SystemTable) -> efi::Status {
    let s = [
        0x0048u16, 0x0065u16, 0x006cu16, 0x006cu16, 0x006fu16, // "Hello"
        0x0020u16, // " "
        0x0057u16, 0x006fu16, 0x0072u16, 0x006cu16, 0x0064u16, // "World"
        0x0021u16, // "!"
        0x000au16, // "\n"
        0x0000u16, // NUL
    ];

    // Print "Hello World!".
    let r =
        unsafe { ((*(*st).con_out).output_string)((*st).con_out, s.as_ptr() as *mut efi::Char16) };
    if r.is_error() {
        return r;
    }

    // Wait for key input, by waiting on the `wait_for_key` event hook.
    let r = unsafe {
        let mut x: usize = 0;
        ((*(*st).boot_services).wait_for_event)(1, &mut (*(*st).con_in).wait_for_key, &mut x)
    };
    if r.is_error() {
        return r;
    }

    efi::Status::SUCCESS
}

Build and Test application

We can build the application using a normal cargo build now. To test the application, we will use qemu. To test out EFI applications in qemu, I have written a small python script. The hello_world.efi file that should be inside target/x86_64-unknown-uefi/debug/. Here is the output screenshot:

Conclusion

With this, we can start implementing parts of std for UEFI and testing them in actual applications. Feel free to ask/make any suggestions on the Tianocore mailing list.

Important Links

Using KConfig with Rust

Ayush — Mon, 14 Mar 2022 16:49:49 +0000

Background

Hello everyone, I am currently working on KConfig bindings for Rust as a part of the Season of KDE 2022. The wrappers for most of the significant aspects of KConfig are complete, so I decided to rewrite the Introduction to KConfig Docs in Rust. The bindings are still not stable and will probably change before the end of the Season of KDE. Still, this post should also help me test out the bindings outside tests. The kconfig bindings can be found here.

The bindings currently use the git version of qttypes since I had to merge some upstream changes that are needed for these bindings. So they are not ready for prime time just yet.

Introduction to KConfig

The KConfig Class

The KConfig object is used to access a given configuration object. The config object can be created in the following ways:

// a plain old read/write config object
let config = KConfig::with_file("myapprc");

// a specific file in the filesystem
// currently must be an INI style file
let full_path = KConfig::with_file("/etc/kderc");

// not merged with global values
let global_free = KConfig::new("config", OpenFlags::NO_GLOBALS, QStandardPathLocation::AppDataLocation);

// not merged with globals or the $KDEDIRS hierarchy
let simple_config = KConfig::new("simple_rc", OpenFlags::SIMPLE_CONFIG, QStandardPathLocation::AppDataLocation);

// outside the standard config resource
let data_resource = KConfig::new("data", OpenFlags::SIMPLE_CONFIG, QStandardPathLocation::AppDataLocation);

// with custom backend
let custom_backend = KConfig::with_backend("config", "backend", QStandardPathLocation::AppDataLocation);

Special Configuration Objects

Each application has its own configuration object that uses the name provided to KAboutData appended with “rc” as its name. So an app named “myapp” would have the default configuration object of “myapprc” (located in $HOME/.config/). This configuration file can be retrieved in this way:

let config = KSharedConfigPtr::default();

The default configuration object for the application is accessed when no name is specified when creating a KConfig object. So we could also do this instead - but it would be slower because it would have to parse the whole file again:

let config = KConfig::default();

Finally there is a global configuration object, kdeglobals, that is shared by every application. It holds such information as the default application shortcuts for various actions. It is “blended” into the configuration object if the kconfig::kconfig::OpenFlags::INCLUDE_GLOBALS flag is passed to the KConfig constructor, which is the default.

Commonly Useful Methods

To save the current state of the configuration object we call the sync() method. This method is also called when the object is destroyed. If no changes have been made or the resource reports itself as non-writable (such as in the case of the user not having write permissions to the file) then no disk activity occurs. sync() merges changes performed concurrently by other processes - local changes have priority, though.

If we want to make sure that we have the latest values from disk we can call reparse_configuration() which calls sync() and then reloads the data from disk.

If we need to prevent the config object from saving already made modifications to disk we need to call mark_as_clean(). A particular use case for this is rolling back the configuration to the on-disk state by calling mark_as_clean() followed by reparse_configuration(). Listing all groups in a configuration object is as simple as calling group_list() as in this code snippet:

let config = KSharedConfigPtr::default();

let group_list = config.group_list();
for group in &group_list {
    log::debug!("next group: {}", group);
}

KSharedConfig

The KSharedConfig class is a reference counted pointer to a KConfig . It thus provides a way to reference the same configuration object from multiple places in your application without the extra overhead of separate objects or concerns about synchronizing writes to disk even if the configuration object is updated from multiple code paths. Accessing a KSharedConfig object is as easy as this:

let config = KSharedConfig::open_config("ksomefilerc", OpenFlags::FULL_CONFIG, QStandardPathLocation::GenericConfigLocation);

KSharedConfig is generally recommended over using KConfig itself.

KConfigGroup

Now that we have a configuration object, the next step is to actually use it. The first thing we must do is to define which group of key/value pairs we wish to access in the object. We do this by creating a KConfigGroup object:

let mut config = KConfig::default();
let mut general_group = config.group("General");
let colors_group = config.group("Colors");

Config groups can be nested as well:

let sub_group2 = general_group.group("Dialogs");

Reading Entries

With a KConfigGroup object in hand reading entries is now quite straight forward:

let account_name = general_group.read_qstring_entry("Account").unwrap();
let color = QColor::from_qvariant(colors_group.read_qvariant_entry("background", QColor::from(Qt::white).to_qvariant()).unwrap());
let list = QStringList::from_qvariant(general_group.read_qvariant_entry("List", QStringList::default().to_qvariant()).unwrap());
let path = general_group.read_path_entry("SaveTo", "defaultPath".into());

In the example above, one can mix reads from different KConfigGroup objects created on the same KConfig object. The bindings currently contain three read methods:

read_qstring_entry() for reading QString values
read_entry() for reading QVariant values that can later be converted to any of the other types
read_path_entry() which returns a file system path.

If no such key currently exists in the configuration object, the default value is returned instead. If there is a localized (e.g. translated into another language) entry for the key that matches the current locale, that is returned.

Writing Entries

Setting new values is similarly straightforward:

general_group.write_qstring_entry("Account", "accountName".into(), WriteConfigFlags::NORMAL);
general_group.write_path_entry("SaveTo", "savePath".into(), WriteConfigFlags::NORMAL);
color_group.write_qvariant_entry("background", QColor::from_name("white").into(), WriteConfigFlags::NORMAL);
config.sync();

Once we are done writing entries, sync() must be called on the config object for it to be saved to disk. We can also simply wait for the object to be destroyed, which triggers an automatic sync() if necessary.

KDesktopFile: A Special Case

When is a configuration file not a configuration file? When it is a desktop file. These files, which are essentially configuration files at their heart, are used to describe entries for application menus, mimetypes, plugins and various services. When accessing a .desktop file, one should instead use the KDesktopFile class which, while a KConfig class offering all the capabilities described above, offers a set of methods designed to make accessing standard attributes of these files consistent and reliable.

Kiosk: Lockdown and User/Group Profiles

KConfig provides a powerful set of lockdown and configuration definition capabilities, collectively known as “Kiosk”, that many system administrators and system integrators rely on. While most of this framework is provided transparently to the application, there is occasion when an application will want to check on the read/write status of a configuration object. Entries in configuration objects that are locked down using the kiosk facilities are said to be immutable. An application can check for immutability of entire configuration objects, groups or keys as shown in this example:

let config = KGlobal::config();

if config.is_immutable() {
    log::debug!("configuration object is immutable");
}

let group = config.group("General".into());
if group.is_immutable() {
    log::debug!("group General is immutable");
}

if group.is_entry_immutable("URL".into()) {
    log::debug!("URL entry in group General is immutable");
}

This can be useful in particular situations where an action should be taken when an item is immutable. For instance, the KDE panels will not offer configuration options to the user or allow them to otherwise change the order of applets and icons when the panel’s configuration object is marked as immutable.

Conclusion

Since most of the work on base KConfig bindings is done, I will now be working on KConfigXT implementation in Rust. Instead to a wrapper, I will be generating Rust code from the kcfg files. Some work has already been done, however, it does not seem like I will be able to complete it anytime soon. Anyone interested in contributing to Rust/QML development is welcome. Here are some important project links:

KConfig Rust Bindings: The bindings I am currently working on.
qmetaobject
cxx-qt