Skip to content

Releases: microsoft/mu_rust_helpers

v4.0.0

06 Feb 20:04
a94b126

Choose a tag to compare

v4.0.0 Pre-release
Pre-release

What's Changed

  • Bump version to 3.0.2 @Javagedes (#76)
    Change Details
      ## Description

    Updated package version to 3.0.2

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

    How This Was Tested

    N/A

    Integration Instructions

    NA

      </blockquote>
      <hr>
    </details>
    

⚠️ Breaking Changes

  • Bump r\_efi version to 6 @berlin-with0ut-return (#90)
    Change Details
      ## Description

    Due to Patina's usage of efi::Guid while depending on GUIDs defined here in mu_rust_helpers, both must be on the same major version for Patina to compile. As part of OpenDevicePartnership/patina#1278, releasing mu_rust_helpers with r-efi 6.0.0 is necessary.

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

    How This Was Tested

    cargo make build with local path in Patina.

    Integration Instructions

    Patina main branch should not adopt this new release until all transition work on the feature branch https://github.com/OpenDevicePartnership/patina/tree/feature/efiapi-unsafe) is done.




Full Changelog: v3.0.2...v4.0.0

v3.0.2

29 Sep 15:15
291f04f

Choose a tag to compare

What's Changed

  • decompress: properly handle zero-sized decompressed file @Javagedes (#75)
    Change Details
      ## Description

    decompression should succeed even when the decompressed file size is zero. It should return a buffer with zero bytes.

    Specifically, this is for SCT compliance.

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

    How This Was Tested

    CI Tests, SCT tests pass

    Integration Instructions

    N/A

      </blockquote>
      <hr>
    </details>
    
  • Sync Mu DevOps Files, add new cargo checks, and fix resulting errors @magravel (#67)
    Change Details
      ## Description

    This pull request brings rust fmt/clippy/doc/test validation to pull requests. Initial fixes for these are also included in this PR.

    The file sync commit was cherry-picked from this pull request: #66

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

    How This Was Tested

    This was tested by running the PR pipeline ( clippy, fmt, build, test, coverage, doc ).

    Integration Instructions

    N/A

      </blockquote>
      <hr>
    </details>
    
  • Update version to 3.0.1 @makubacki (#55)
    Change Details
      ## Description

    Version update for the upcoming release.

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

    How This Was Tested

    N/A

    Integration Instructions

    N/A




Full Changelog: v3.0.1...v3.0.2

v3.0.1

24 Apr 21:13
e4dffca

Choose a tag to compare

What's Changed

🐛 Bug Fixes

  • Fix build error on aarm64. @magravel (#54)
    Change Details
      ## Description

    There was an error when building on aarm64. A function name has changed but not for arm, so it didn't build.

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

    How This Was Tested

    Building the repo.

    Integration Instructions

    N/A




Full Changelog: v3.0.0...v3.0.1

v3.0.0

26 Mar 22:57
4837cce

Choose a tag to compare

What's Changed

  • Add .git-blame-ignore-revs @makubacki (#48)
    Change Details
      ## Description

    This file should only be used to ignore changes that are completely non-functional.

    In this case, it is ignoring the commit that updated from 2 to 4 spaces.

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

    How This Was Tested

    > git blame --ignore-revs-file .git-blame-ignore-revs boot_services/src/boot_services.rs

    Integration Instructions

    Set up your git config to you the ignore file if it is not already globally set to use files with the .git-blame-ignore-revs naming convention.




⚠️ Breaking Changes

  • Remove Migrated Crates [Rebase \& FF] @makubacki (#50)
    Change Details
      ## Description

    Removes crates that have been migrated to another repo that will be published soon.


    Update version to 3.0.0

    Version update for the upcoming release.


    Remove runtime_services crate

    This crate has been moved to another repo that will be published
    soon.

    To prevent duplicate code and reduce dependencies on the code in
    this repo, the code is removed.


    Remove boot_services and tpl_mutex crates

    These have been moved to another repo that will be published soon.

    To prevent duplicate code and reduce dependencies on the code in
    this repo, the code is removed.


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

    How This Was Tested

    • Build and CI

    Integration Instructions


🐛 Bug Fixes

  • Comprehensive timer fix for QEMU @berlin-with0ut-return (#52)
    Change Details
      ## Description

    Fix divide by zero error in timer for QEMU and improve frequency calculation overall. The new approach attempts to use CPUID leaf 0x16 (for nominal frequency on QEMU), as well as CPUID leaf 0x15 (for TSC frequency on physical platforms), and defaults to the ACPI frequency if both CPUID leaves fail (same behavior as mu_basecore).

    I also added an ability to cache the frequency value since it should not change during runtime for more consistent perf results.

    Leaving as draft for now because I'm unsure if this is the best strategy for timing.

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

    How This Was Tested

    I tested all 3 cases (Skylake QEMU, physical platform, qemu64) and all give reasonable results without crashing.

    Integration Instructions

    N/A. Although it should be noted for perf, we would generally prefer using a realistic cpu model or a physical platform over qemu64.




Full Changelog: v2.0.0...v3.0.0

v2.0.0

15 Jan 02:12

Choose a tag to compare

What's Changed

This is the first release published to crates.io.


  • global\_allocator: Fix build failure due to incorrect MemoryType reference @zurcher (#32)
    Change Details
      ## Description

    global_allocator.rs had references to MemoryType::BootServicesData instead of MemoryType::BOOT_SERVICES_DATA. This was causing failures when using cargo make.

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

    How This Was Tested

    cargo make build boot_services no longer fails to build.

    Integration Instructions

    N/A




  • remove Sized from BootServices trait @joschock (#40)
    Change Details
      ## Description

    Relax the trait bounds on various consumers of BootServices to allow BootServices to be unsized. This will permit usage of BootServices trait objects.

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

    How This Was Tested

    Verified that unit tests still pass.

    Integration Instructions

    N/A




⚠️ Breaking Changes

  • Add workspace publishing [Rebase \& FF] @makubacki (#43)
    Change Details
      ## Description

    Changes to support publishing crates from this repo.


    Add crate publishing support

    • Crates are currently being published from Mu repositories. The
      expectation is that the code will be moved to another repo after a
      period of time outside of Project Mu. To differentiate these early
      versions of the crates, the package names are prefixed with
      "mu_uefi".
    • Keep library names consistent with current code.
    • Add additional info to crates common to the workspace.
    • Add GitHub publishing workflow to the repo.
    • Add readme to Cargo.toml.
    • Sort some sections in the workspace Cargo.toml for ease of reading
      information.

    Update version to 2.0.0

    Version update for the upcoming release.


    Cargo.toml: Consolidate workspace dependency versions

    Use the workspace.dependencies versions to reduce maintenance
    overhead.


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

    How This Was Tested

    • Dry run of release to crates.io
    • Publish of crates to a test registry
    • GitHub workflow test on fork

    Integration Instructions

    • Use the published crates after this change is merged and the crates are published. Use the new crate names when updating.


  • Improvement of BootServices @magravel (#38)
    Change Details
      ## Description
    • Add new version for install / uninstall / locate protocol (Breaking changes)

    • Increment version of Boot Services because of breaking changes.

    • Add test for Protocol Handler Service

    • Better function not initialized panic message

    • Impacts functionality?
      Yes, some functions working with protocol interface has been changed to have a version with a protocol and a version with a marker protocol (a null interface).

    • Impacts security?

    • Breaking change?

    • Includes tests?

    • Includes documentation?

    How This Was Tested

    this was tested with running the unit tests.

    Integration Instructions

    N/A




📖 Documentation Updates

  • Improvement of BootServices @magravel (#38)
    Change Details
      ## Description
    • Add new version for install / uninstall / locate protocol (Breaking changes)

    • Increment version of Boot Services because of breaking changes.

    • Add test for Protocol Handler Service

    • Better function not initialized panic message

    • Impacts functionality?
      Yes, some functions working with protocol interface has been changed to have a version with a protocol and a version with a marker protocol (a null interface).

    • Impacts security?

    • Breaking change?

    • Includes tests?

    • Includes documentation?

    How This Was Tested

    this was tested with running the unit tests.

    Integration Instructions

    N/A




  • Add Images Services @magravel (#39)
    Change Details
      ## Description

    Add Images Services with their respective documentation and test.

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

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

    How This Was Tested

    This was tested with unit tests only.

    Integration Instructions

    N/A




  • Add Misc Services @magravel (#33)
    Change Details
      ## Description

    Add misc services to BootServices.

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

    How This Was Tested

    This was tested by adding unit test to verify the efi functions are callded with the right arguments.

    Integration Instructions

    N/A




Full Changelog: v1.2.1...v2.0.0

v1.2.1

04 Nov 23:05
d44a8b9

Choose a tag to compare

What's Changed

  • guid: guid! macro ergonomics improvement @Javagedes (#37)
    Change Details
      ## Description

    With the current structure of the guid! macro, the uuid crate must be added to the dependencies of any crate that uses the macro and the macro itself must be in scope. This provides poor ergonomics for anyone using the macro and the error for not having the uuid crate in scope is not the most clear.

    error: cannot find macro `uuid` in this scope
       --> my_component\src\component.rs:170:9
        |
    170 |         mu_rust_helpers::guid::guid!("4297bd81-1d1d-49aa-b138-7b54e5807264")
        |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        |
        = note: `uuid` is in scope, but it is a crate, not a macro
        = note: this error originates in the macro `mu_rust_helpers::guid::guid` (in Nightly builds, run with -Z macro-backtrace for more info)
    

    This commit updates the usage of the uuid macro, so that the macro does not require the uuid macro to be in scope (or the uuid crate to be a dependency at all). This is done by specifying that the uuid macro comes from the interior crate (using $crate). This does, however, re-export the uuid! macro, as it must be public for it to be used in other crates.

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

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

    How This Was Tested

    Verified the macro can now be used without the need of having the uuid crate as a dependency, or the uuid::uuid! macro in scope in the file.

    Integration Instructions

    Consumers can remove the uuid crate if not used for any other purposes.

      </blockquote>
      <hr>
    </details>
    

Full Changelog: v1.2.0...v1.2.1

v1.2.0

04 Oct 23:05

Choose a tag to compare

What's Changed

  • [REBASE\&FF] Add perf\_timer and uefi\_decompress functionality @Javagedes (#31)
    Change Details
      ## Description Add two new crates to mu_rust_helpers, `perf_timer`, which adds a uefi equivalent to `std::time::Instant` and `uefi_decompress` which provides functionality to do both uefi and tiano decompression
    • Impacts functionality?
    • Impacts security?
    • Breaking change?
    • Includes tests?
    • Includes documentation?

    How This Was Tested

    Tests written with these two crates pass the pipelines successfully.

    Integration Instructions

    Upgrade your ref to 1.2.0

      </blockquote>
      <hr>
    </details>
    

Full Changelog: v1.1.0...v1.1.1

v1.1.0

01 Oct 14:34
3438038

Choose a tag to compare

What's Changed

  • Cargo.toml: Update version to 1.1.0 @makubacki (#30)
    Change Details
      ## Description

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

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

    How This Was Tested

    • N/A

    Integration Instructions

    • N/A


  • [Rebase \& FF] Add a test for get memory map wrapper @dachihy (#24)
    Change Details
      ## Description

    Add a test for get memory map wrapper

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

    How This Was Tested

    Run test

    Integration Instructions

    N/A




🚀 Features & ✨ Enhancements

  • macros: Add new module for helper macros @makubacki (#29)
    Change Details
      ## Description

    The first macro here is function!() which prints the name of the containing function. Originally implemented in the advanced logger crate and transferred here for broader accessibility.

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

    How This Was Tested

    • Cargo doc, tests, build, and usage in a consuming crate

    Integration Instructions

    Use the mu_rust_helpers::function macro if it is useful for you.




📖 Documentation Updates

  • macros: Add new module for helper macros @makubacki (#29)
    Change Details
      ## Description

    The first macro here is function!() which prints the name of the containing function. Originally implemented in the advanced logger crate and transferred here for broader accessibility.

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

    How This Was Tested

    • Cargo doc, tests, build, and usage in a consuming crate

    Integration Instructions

    Use the mu_rust_helpers::function macro if it is useful for you.




Full Changelog: v1.0.1...v1.1.0

v1.0.1

24 Sep 21:52
1dfb941

Choose a tag to compare

What's Changed

  • Cargo.toml: Update version to 1.0.1 @makubacki (#28)
    Change Details
      ## Description

    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: v1.0.0...v1.0.1

v1.0.0

23 Sep 23:44
77cff30

Choose a tag to compare

What's Changed

  • Add a test for free pool @dachihy (#18)
    Change Details
      ## Description

    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




  • boot\_services.rs: Add a test for allocate pool @dachihy (#17)
    Change Details
      ## Description

    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() @joschock (#16)
    Change Details
      ## Description

    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

  • Bugfix: locate\_protocol on Indicator protocol @bkarstens (#26)
    Change Details
      ## Description

    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.




  • Add GUID helpers @zurcher (#13)
    Change Details
      ## Description

    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

  • Bugfix: locate\_protocol on Indicator protocol @bkarstens (#26)
    Change Details
      ## Description

    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 Variable Serivce Wrappers for Runtime Services @kouchekiniad (#22)
    Change Details
      ## Description

    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 Variable Serivce Wrappers for Runtime Services @kouchekiniad (#22)
    Change Details
      ## Description

    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 improvements for boot\_services @lavinders (#19)
    ...
Read more