Releases: microsoft/mu_rust_helpers
v4.0.0
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::Guidwhile 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 buildwith 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
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
What's Changed
-
Repo File Sync: Update to Mu DevOps v14.0.0 @makubacki (#57)
Change Details
synced local file(s) with [microsoft/mu_devops](https://github.com/microsoft/mu_devops).
🤖: View the Repo File Sync Configuration File to see how files are synced.
This PR was created automatically by the repo-file-sync-action workflow run #14543724197
PR recreated under my GitHub account to pass CLA until microsoft/cla-approved-bots#12 is completed.
🐛 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
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.rsIntegration 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-revsnaming 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_servicescrateThis 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_servicesandtpl_mutexcratesThese 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
-
These crates are no longer available. Due to the limited number of crate users, these are removed now to prevent dependencies from forming on the crates in this repo. Additional details will be made available about the new repo the functionality has moved to. Reach out in issues or discussions on this repo if that is of interest.
-
Existing code can continue using these crates by remaining on these versions published to crates.io:
- "mu_uefi_boot_services" - "2.0.0" - https://crates.io/crates/mu_uefi_boot_services
- "mu_uefi_runtime_services" - "2.0.0" - https://crates.io/crates/mu_uefi_runtime_services
- "mu_uefi_tpl_mutex" - "2.0.0" - https://crates.io/crates/mu_uefi_tpl_mutex
🐛 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
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::BootServicesDatainstead ofMemoryType::BOOT_SERVICES_DATA. This was causing failures when usingcargo make.- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
cargo make build boot_servicesno 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
BootServicesto allowBootServicesto be unsized. This will permit usage ofBootServicestrait 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.
- Crates are currently being published from Mu repositories. The
-
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
What's Changed
-
guid: guid! macro ergonomics improvement @Javagedes (#37)
Change Details
## Description
With the current structure of the guid! macro, the
uuidcrate 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 theuuidcrate 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
uuidmacro 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
uuidcrate as a dependency, or theuuid::uuid!macro in scope in the file.Integration Instructions
Consumers can remove the
uuidcrate if not used for any other purposes.</blockquote> <hr> </details>
Full Changelog: v1.2.0...v1.2.1
v1.2.0
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
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::functionmacro 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::functionmacro if it is useful for you.
Full Changelog: v1.0.1...v1.1.0
v1.0.1
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
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_poolunit 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_pagesunit 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_protocolto return anOption<&'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
BootServicesstruct - Impacts security?
- Breaking change? The return of
locate_protocolnow has an extraOptionlayer that will need to be handled. - Includes tests?
- Includes documentation?
How This Was Tested
Added and ran tests for
locate_protocolIntegration Instructions
Update existing
locate_protocolusage to handleOption.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.
- Impacts functionality?: Now allows indicator protocols to be located using the
-
Add GUID helpers @zurcher (#13)
Change Details
## Description
Adding various GUID helpers:
guid!macro to createconst efi::Guidfrom a GUID string.
guid_fmt!macro to format anefi::Guidfor printing.
guid_to_uuid!macro to use anefi::Guidas auuid::Uuid.
guid::CALLER_IDto replicate gEfiCallerIdGuid from AutoGen.c.
guid::ZEROfor 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
uuidcrate andmu_rust_helpers::guidas dependencies.
See tests module for code samples.
guid_fmt!returns acore::fmt::Argumentswhich can be passed todebugln!
🐛 Bug Fixes
-
Bugfix: locate\_protocol on Indicator protocol @bkarstens (#26)
Change Details
## Description
Modified
locate_protocolto return anOption<&'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
BootServicesstruct - Impacts security?
- Breaking change? The return of
locate_protocolnow has an extraOptionlayer that will need to be handled. - Includes tests?
- Includes documentation?
How This Was Tested
Added and ran tests for
locate_protocolIntegration Instructions
Update existing
locate_protocolusage to handleOption.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.
- Impacts functionality?: Now allows indicator protocols to be located using the
🔐 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)
...