What's Changed

Update versions to 1.0.1 @joschock (#142)
Change Details
## Description
Updates the versions to 1.0.1 for next release.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A - version update.

Integration Instructions

N/A

Add get\_memory\_descriptor\_for\_address(), preserve existing attributes when configuring access attributes on a block. @joschock (#141)
Change Details
## Description
- Adds get_memory_descriptor_for_address() function to GCD
- Updates memory protections code to preserve existing attributes when configuring access attributes on a memory block.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Booted to windows on hardware platform, confirmed issues around caching attributes no longer observed.

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

dxe\_core: Define Architecture specific type aliases for `Core` @Javagedes (#133)
Change Details
## Description
Adds two type aliases of Core (X64Core and Aarch64Core) which pre-selects the required trait implementations for architecture specific traits such as the interrupt manager or the cpu initializer.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A

Integration Instructions

Platforms can switch from Core::default() to X64Core::default() or Aarch64Core::default() and no longer need to call .with_cpu_initializer(...) or with_interrupt_manager(...) unless they wish to override the default configuration for those trait implementations.

Platforms can continue to use Core if they wish to override specifics.

allocator: Update ensure\_capacity to call alloc/dealloc @os-d (#132)
Change Details
## Description
There was a PR comment to use alloc/dealloc in the implementation of ensure_capacity, which was implemented and tested, but not pushed before the PR was merged.

This is the change that was requested in addition to the other PR feedback of adding an extra comment empty line before the function name.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Tested on Q35, allocating a small amount and a large amount and confirming expand didn't/did happen.

Integration Instructions

N/A.
```
  </blockquote>
  <hr>
</details>
```

Clean up unwraps to expect/error handling @berlin-with0ut-return (#123)
Change Details
## Description This PR examines all usage of unwrap. The usages that are guaranteed safe by current code are converted to expect for more informative error messages, while the usages that could possibly error are converted to error handling and logging.
- Impacts functionality? (No major functional changes. The only observed differences will be returning or logging an error instead of panicking.)
- Impacts security?
- Breaking change?
- Includes tests? (Existing test should be sufficient to cover these changes, as they do not result in any functional changes.)
- Includes documentation? (None needed.)
How This Was Tested

All integration and unit tests are still passing after the error handling changes.

Integration Instructions

N/A. No functional changes.
```
  </blockquote>
  <hr>
</details>
```

[REBASE \& FF] allocator: Add ensure\_capacity API @os-d (#122)
Change Details
## Description
This PR contains two commits:

Use Correct Target Triple in README

The README was incorrectly specifying that the aarch64 build commands would build the i686-unknown-uefi target triple, so this was updated to aarch64-unknown-uefi.

Add ensure_capacity API

This commit adds a new ensure_capacity API to the allocator
that checks if a given size and alignment are free in the
given allocator. If not, it calls expand to allocate more
pages in the pool.
```
This API is intended for dxe_core only when it needs to
pre-allocate memory in memory sensitive operations, such as
constructing the EFI_MEMORY_MAP or allocating page table
memory.

By ensuring the pool allocator has enough memory for its
allocations, it can ensure that recursive calls to the GCD
will not be made.

The get_memory_map code is updated here also, not to use
the new API as was the original design point, but to
pre-allocate the merged descriptor vector. Same goal,
but different implementation.

This API will be consumed when mu-paging is integrated
into dxe_core.
```
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Tested by booting to Windows in Q35 and adding some debug prints to witness the ensure_capacity() succeeding. Then I tested an artificial allocate_pool() allocating the available memory and witnessing Windows booting after ensure_capacity() called expand().

Integration Instructions

N/A.
```
  </blockquote>
  <hr>
</details>
```

Add label syncer workflow @makubacki (#125)
Change Details
## Description
Workflow is used to ensure any labels defined for the project are available.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- Run workflow on fork and verify labels are synced as expected
Integration Instructions

Reuse the LabelSyncer.yml workflow in another project GitHub repo if labels should
be synced there.

workspace: Update goblin to crates.io version @Javagedes (#119)
Change Details
## Description
Goblin recently performed a release (0.9.0) that includes changes from @joschock and @Javagedes, allowing us to switch back to using the typical semantic versioning from crates.io for this repository.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

⚠️ Breaking Changes

Add use of interrupt manage in DXE core @cfernald (#129)
Change Details
## Description
Adds use of the InterruptManager trait from the uefi_interrupt create for initializing the interrupt and exception handlers.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Tested on Q35

Integration Instructions

Platforms must use an implementation of Interrupt Manager appropriate to their architecture when creating the core.
```
  </blockquote>
  <hr>
</details>
```

🔐 Security Impacting

image loader: Add Stack Guard for Loaded Images @os-d (#136)
Change Details
## Description
Each image loaded in DxeRust gets a separate stack created for it and it is executed using that stack with corosensei.

We implement our stack functionality that we pass to corosensei, so no guard page is added by default to the stack. This commit adds a guard page at the bottom of the stack to catch stack overflows in drivers/applications.

This does not cover DXE core itself, that is a change that will come later, today DXE core has its stack and stack guard set up by DxeIpl. In the future, DXE Core will create its own stack.

Note: Until mu-paging is integrated, this won't protect images launched before the CPU arch protocol is available.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Tested booting Q35 to Windows.

Integration Instructions

N/A.
```
  </blockquote>
  <hr>
</details>
```

📖 Documentation Updates

docs: Add mocking and testing documentation @Javagedes (#134)
Change Details
## Description
Add documentation on Mocking and on generic testing for the DXE Core.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Documentation compiles and passes CI checks.

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

[REBASE\&FF] Add uefi\_test crate @Javagedes (#120)
Change Details
## Description
Adds a new crate uefi_test This crate utilizes the linkme crate to do some linker magic similar to google tests that places all tests into a link_section, and is collated at runtime. This crate comes with a single feature flag, off, which updates internal the logic to no longer generate the static test cases or the link sections themselves. This is different than other skipping functionality, which is described below, which simply skips the test at runtime.

note: The second commit is necessary due to this raised issue: xd009642/tarpaulin#1642. test executables generated for proc-macro crates are exiting before any tests run on windows-latest runners of github actions. I confirmed through outside testing that this is not something specific to our repo. Due to this, I've update cargo make to skip testing the uefi_test_macro crate when on windows and for a CI system. We will still hit coverage targets as the crate will be tested on the linux runner, and it is not skipped locally.

uefi_test crate
1. Macro for globally registering tests with the uefi_test attribute
2. assert macros that return an error instead of panic because we cannot unwind a panic in no_std
3. A TestRunnerComponent that runs all collected tests.
uefi_test macro

uefi_test is an attribute macro, e.g. #[uefi_test] that works exactly like the test attribute, except with the expected function fn(&dyn DxeComponentInterface)->core::result::Result<(), 'static str> interface. The uefi_test attribute includes two additional attributes for configuration.

The first is should_fail which matches the same logic as should_panic, which comes in two flavors:
#[should_fail] and #[should_fail = "msg"] where msg is the expected error string. The second attribute is #[skip], which is functionaly the same as the skip attribute for std tests. This is expected to be used in conjunction with cfg_attr for tests that may only run under certain circumstances (such as x64 targets, etc). It should be noted that the skip attribute skips at runtime, and the test is still compiled in.

TestRunnerComponent

The TestRunnerComponent is a component that can be registered with the pure rust dxe core and once the core executes it, will execute all tests. As mentioned previously, all tests are automatically registered, so there is configuration available to skip tests. The current available configuration is as follows:
- with_filter(&str) which will run any test that matches this filter (instead of running all by default)
- debug_mode(bool) which will turn on logging for tests (by default we disable logging for each test)
- fail_fast(bool) which will end the test immediately if a test fails.
Examples
```
use uefi_test::{uefi_test, TestRunnerComponent, Result};
use uefi_component_interface::DxeComponentInterface;

let component = TestRunnerComponent::default()
  .with_filter("aarch64")
  .debug_mode(true)
  .fail_fast(true);

#[cfg_attr(target_arch = "aarch64", uefi_test)]
fn test_case(_interface: &dyn DxeComponentInterface) -> Result {
  uefi_test::assert_eq!(1, 1);
  Ok(())
}

#[uefi_test]
fn test_case2(_interface: &dyn DxeComponentInterface) -> Result {
  uefi_test::assert_eq!(1, 1);
  Ok(())
}

#[uefi_test]
#[should_fail]
fn failing_test_case(_interface: &dyn DxeComponentInterface) -> Result {
   uefi_test::assert_eq!(1, 2);
   Ok(())
}

#[uefi_test]
#[should_fail = "This test failed"]
fn failing_test_case_with_msg(_interface: &dyn DxeComponentInterface) -> Result {
  uefi_test::assert_eq!(1, 2, "This test failed");
  Ok(())
}

#[uefi_test]
#[skip]
fn skipped_test_case(_interface: &dyn DxeComponentInterface) -> Result {
   todo!()
}

#[uefi_test]
#[cfg_attr(not(target_arch = "x86_64"), skip)]
fn x86_64_only_test_case(_interface: &dyn DxeComponentInterface) -> Result {
  todo!()
}
```
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Validated that all scenarios work as expected.

Integration Instructions

Take a dependency on uefi_test for any crate that wants to have runtime tests applied. In these scenarios, write the test and annotate it with #[uefi_test]
```
  </blockquote>
  <hr>
</details>
```

Add Theory of Operations Documentation for Image module @joschock (#131)
Change Details
## Description
Add Theory of Operations Documentation for Image module.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Mdbook properly renders.

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

Add Theory of Operations Documentation for UEFI Driver Model module. @joschock (#130)
Change Details
## Description
Add Theory of Operations Documentation for UEFI Driver Model module.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

MdBook renders as expected.

Integration Instructions

N/A

Add Theory of Operations Documentation for Synchronization and TplMutex. @joschock (#121)
Change Details
## Description
Add Theory of Operations Documentation for Synchronization and TplMutex.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Mdbook renders appropriately.

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

[REBASE\&FF] Update documentation @Javagedes (#118)
Change Details
## Description
Updates documentation bumps the version of all crates to match the current release on github.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
Closes #75
Closes #76

How This Was Tested

CI verifies documentation still builds.

Integration Instructions

N/A
```
  </blockquote>
  <hr>
</details>
```

Full Changelog: v0.1.9...v1.0.0

v1.0.1

What's Changed

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

Use Correct Target Triple in README

Add ensure_capacity API

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

⚠️ Breaking Changes

How This Was Tested

Integration Instructions

🔐 Security Impacting

How This Was Tested

Integration Instructions

📖 Documentation Updates

How This Was Tested

Integration Instructions

uefi_test crate

uefi_test macro

TestRunnerComponent

Examples

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

Contributors

Uh oh!

`uefi_test` crate

`uefi_test` macro

`TestRunnerComponent`