mu_rust_helpers

Mu Rust Helper Code

OTHER License

Stars
1
Committers
8
View Code on GitHub View on X
Ecosystems: VS Code Extension, Playwright, Windows, TypeScript, Windows UI Library (WinUI)

Bot releases are visible (Hide)

mu_rust_helpers - v1.0.1

Published by github-actions[bot] 25 days ago

What's Changed

Updates the crate version in anticipation of a v1.0.1 tagged release.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

  • N/A

Integration Instructions

  • N/A

Full Changelog: https://github.com/microsoft/mu_rust_helpers/compare/v1.0.0...v1.0.1

mu_rust_helpers - v1.0.0

Published by github-actions[bot] 26 days ago

What's Changed

Add a test for free_pool()

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added new test_free_pool unit test for free_pool, test passes.

Integration Instructions

N/A


Adds a test for allocate pool wrapper.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Run Test with PASS result

Integration Instructions

N/A


Add a test for free_pages()

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added new test_free_pages unit test for free_pages, test passes.

Integration Instructions

N/A


⚠️ Breaking Changes

Modified locate_protocol to return an Option<&'static mut I>. There are many protocols that are only indicators of events/feature availability. These protocols are installed with null pointers; without this change, locate_protocol panics due to dereferencing the null protocol interface.

  • Impacts functionality?: Now allows indicator protocols to be located using the BootServices struct
  • Impacts security?
  • Breaking change? The return of locate_protocol now has an extra Option layer that will need to be handled.
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added and ran tests for locate_protocol

Integration Instructions

Update existing locate_protocol usage to handle Option.

New non-Indicator protocol patterns:

let protocol_interface = boot_services.locate_protocol(&ADVANCED_LOGGER_PROTOCOL, None)?.ok_or(efi::Status::INCOMPATIBLE_VERSION)?;

let protcol_interface = match boot_services.locate_protocol(&ADVANCED_LOGGER_PROTOCOL, None) {
    Ok(Some(protcol_interface)) => protcol_interface,
    Ok(None) => {
        return efi::Status::INCOMPATIBLE_VERSION;
    }
    Err(status) => {
        return status;
    }
};

Indicator protocol patterns:

boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None)?;

match boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None) {
    Err(status) => Err(status)?,
    Ok(..) => { /* do stuff */ }

    // or more pedantic
    Ok(Some(inteface)) => Err(efi::Status::INCOMPATIBLE_VERSION)?,
    Ok(None) => { /* do stuff */ }
};


let located = boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None).is_ok_and(|option| option.is_none());

// or just
let located = boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None).is_ok();

Those are example patterns.


Adding various GUID helpers:
guid! macro to create const efi::Guid from a GUID string.
guid_fmt! macro to format an efi::Guid for printing.
guid_to_uuid! macro to use an efi::Guid as a uuid::Uuid.
guid::CALLER_ID to replicate gEfiCallerIdGuid from AutoGen.c.
guid::ZERO for filling data structs.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Various unit tests as well as use in an EDK2 project with results verified in hardware.

Integration Instructions

Include uuid crate and mu_rust_helpers::guid as dependencies.
See tests module for code samples.
guid_fmt! returns a core::fmt::Arguments which can be passed to debugln!


🐛 Bug Fixes

Modified locate_protocol to return an Option<&'static mut I>. There are many protocols that are only indicators of events/feature availability. These protocols are installed with null pointers; without this change, locate_protocol panics due to dereferencing the null protocol interface.

  • Impacts functionality?: Now allows indicator protocols to be located using the BootServices struct
  • Impacts security?
  • Breaking change? The return of locate_protocol now has an extra Option layer that will need to be handled.
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added and ran tests for locate_protocol

Integration Instructions

Update existing locate_protocol usage to handle Option.

New non-Indicator protocol patterns:

let protocol_interface = boot_services.locate_protocol(&ADVANCED_LOGGER_PROTOCOL, None)?.ok_or(efi::Status::INCOMPATIBLE_VERSION)?;

let protcol_interface = match boot_services.locate_protocol(&ADVANCED_LOGGER_PROTOCOL, None) {
    Ok(Some(protcol_interface)) => protcol_interface,
    Ok(None) => {
        return efi::Status::INCOMPATIBLE_VERSION;
    }
    Err(status) => {
        return status;
    }
};

Indicator protocol patterns:

boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None)?;

match boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None) {
    Err(status) => Err(status)?,
    Ok(..) => { /* do stuff */ }

    // or more pedantic
    Ok(Some(inteface)) => Err(efi::Status::INCOMPATIBLE_VERSION)?,
    Ok(None) => { /* do stuff */ }
};

let located = boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None).is_ok_and(|option| option.is_none());

// or just
let located = boot_services.locate_protocol(&VARIABLE_WRITE_ARCH_PROTOCOL_GUID, None).is_ok();

Those are example patterns.


🔐 Security Impacting

Added Rust wrappers for all four variable services within runtime services. Additionally added a UEFI variable name streaming iterator that wraps around GetNextVariableName(), allowing for easy iteration through all UEFI variable names. Credit to Edwin Zhang (@edwinzMSFT) for creating the runtime_services crate and adding boilerplate functions.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added 19 unit tests, which all pass. Additionally, @edwinzMSFT modified a driver to intake these wrappers and saw preliminary success.

Integration Instructions

Replace existing calls to variable services within runtime services with calls to wrappers included in the runtime_services crate.


📖 Documentation Updates

Added Rust wrappers for all four variable services within runtime services. Additionally added a UEFI variable name streaming iterator that wraps around GetNextVariableName(), allowing for easy iteration through all UEFI variable names. Credit to Edwin Zhang (@edwinzMSFT) for creating the runtime_services crate and adding boilerplate functions.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Added 19 unit tests, which all pass. Additionally, @edwinzMSFT modified a driver to intake these wrappers and saw preliminary success.

Integration Instructions

Replace existing calls to variable services within runtime services with calls to wrappers included in the runtime_services crate.


Added UEFI sections descriptions in documentation.
Minor changes to certain unchecked methods which were not marked unsafe, not sure if that was deliberate or just missed.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Ran following commands and they all passed.

Cargo build
Cargo fmt
Cargo test --all
Cargo doc

Integration Instructions

N/A


Adding various GUID helpers:
guid! macro to create const efi::Guid from a GUID string.
guid_fmt! macro to format an efi::Guid for printing.
guid_to_uuid! macro to use an efi::Guid as a uuid::Uuid.
guid::CALLER_ID to replicate gEfiCallerIdGuid from AutoGen.c.
guid::ZERO for filling data structs.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

Various unit tests as well as use in an EDK2 project with results verified in hardware.

Integration Instructions

Include uuid crate and mu_rust_helpers::guid as dependencies.
See tests module for code samples.
guid_fmt! returns a core::fmt::Arguments which can be passed to debugln!


add Event, Timer, and Task priority services with their respective unit tests and documentation.
add allocation services
add protocol handler services

For details on how to complete to complete these options and their meaning refer to CONTRIBUTING.md.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
    • Some services have unit tests (Event, Timer, and Task priority), and the other ones will be unit tested in another PR.
  • Includes documentation?
    • Some services have documentation (Event, Timer, and Task priority), and the other ones will be documented in another PR.

How This Was Tested

Event, Timer, and Task priority services have unit tests.

Integration Instructions

N/A


Full Changelog: https://github.com/microsoft/mu_rust_helpers/compare/v0.1.0...v1.0.0

mu_rust_helpers - v0.1.0 Latest Release

Published by github-actions[bot] 4 months ago

What's Changed

Adds the build and test Azure pipeline YAML file and GitHub workflow
files for GitHub automation.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

  • Mu Rust Helper PR gate

Integration Instructions

  • N/A - Local CI

Add TplMutex helper and basic boot services for tpl sevices use in the mutex.

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
    • unit tests for testing the locking behavior of TplMutex
    • unit tests for testing the creation of StandardBootServices
  • Includes documentation?
    • Documentation for public function made in tpl_mutex.rs and boot_services.rs

How This Was Tested

With unit tests

Integration Instructions

N/A


Full Changelog: https://github.com/microsoft/mu_rust_helpers/compare/...v0.1.0

Related Projects
elfcore

A Rust crate for creating memory dumps of running processes on Linux

07 Apr 2023 47
mu_feature_uefi_variable

Project Mu - Feature Repo - UEFI Variables

29 Aug 2022 5
mu_feature_debugger

Project Mu based UEFI SW/FW debugger

21 Mar 2024 10
mu_feature_mm_supv

Project Mu - Feature Repo - MM Supervisor

02 May 2022 47
mu_oem_sample

Project Mu OEM Sample Code

22 Oct 2018 45
mu_common_intel_min_platform

Project Mu Minimum Platform

31 Jul 2020 17
mapi-rs

Rust bindings for Outlook's MAPI interfaces with microsoft/windows-rs

27 Aug 2024 1
mu_tiano_plus

Project Mu TianoCore Plus

08 Sep 2018 62
mu_silicon_intel_tiano

Project Mu - TianoCore Intel Packages

01 Oct 2018 26
go-rustaudit

Go library for inspecting Rust binaries produced with https://github.com/rust-secure-code/cargo-a...

12 Jul 2022 15
mu_rust_pi

Platform Initialization (PI) Specification Definitions and Support Code

10 Apr 2024 1
apt-transport-blob

apt-transport-blob is a transport for apt that allows users to access an apt repository on Azure ...

04 Mar 2024 6
mu_rust_hid

A Rust crate for parsing HID Report Descriptors.

06 Sep 2023 29
mu_feature_dfci

DFCI - Device Firmware Configuration Interface

21 Nov 2022 16
mu_plus

Project Mu Microsoft Core UEFI Value

08 Sep 2018 212