What's Changed

Update events::wait\_for\_event() semantics @joschock (#1140)
Change Details
## Description
Adjusts wait_for_event semantics to better match historical behavior of core:
- make out_index parameter optional
- invoke CPU sleep function during idle loop.
Closes #791
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Boot to OS on AARCH64 hardware.

Integration Instructions

N/A

Make `create_performance_measurement` safer for internal (Rust) usage @berlin-with0ut-return (#1008)
Change Details
## Description Removes raw pointers from `create_performance_measurement` and adds a `CallerIdentifier` enum to distinguish different perf id `caller_identifier` interpretations.
The main goal of this PR is to make internal performance logging (ie through log_performance_measuresurement) use Rust-compliant interfaces like Option or enums instead of raw pointers, since raw pointers aren't necessary for the operation of internal performance instrumentation. The edk2 protocol interface remains unchanged.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
- Creates a new crate?
How This Was Tested

Boot and gather perf records on QEMU.

Integration Instructions

N/A.

Makefile.toml: Add doc test task to `all` [Rebase \& FF] @makubacki (#1141)
Change Details
## Description
Resolves #1125

Add a new test-doc task that runs cargo test --doc and include it in the all task dependencies to ensure documentation tests are validated as part of the "all" flow.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make test-doc
- cargo make all
Integration Instructions
- N/A

patina\_debugger: Implement initial breakpoint timeout @cfernald (#1135)
Change Details
## Description
Implements a timeout for the initial breakpoint using a timer provided by the core. This allows for the platform to configure a timeout for the debugger to wait for a connection before proceeding with normal execution.

This change also drops the notion that force_enable may not be used with a timeout. This may change when a runtime enablement story is further developed.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Manual tests on Q35

Integration Instructions

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

[patina\_dxe\_core] Safety comments for lib.rs @Raymond-MS (#1104)
Change Details
## Description
Updated lib.rs to include safety comments around unsafe blocks and added checks where necessary. Added test code for the updated function.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Built and ran with QEMU SBSA platform. Booted to UEFI shell successfully.

Integration Instructions

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

patina\_dxe\_core/fv: Fix `test_fv_functionality()` panic [Rebase \& FF] @makubacki (#1134)
Change Details
## Description
Fixes #1127

Code is currently commented out in test_fv_functionality() that calls fv_read_file() with a non-null buffer and buffer size of zero.

This change updates fv_read_file() to follow the same behavior as the C DXE Core FvReadFile() function in FwVolRead.c that will return BUFFER_TOO_SMALL in this scenario.

Another difference in behavior is that if the caller provides a non-null buffer but a buffer size less than the file content size, the C implementation will truncate the copy size to the size provided and perform the copy with that size. To prevent further discrepancies between caller expectations, that change is made in a second commit.

patina_dxe_core: Truncate copies in fv_read_file()

Matches the C implementation more closely by performing truncated copies
when the provided buffer is too small.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
Integration Instructions
- N/A

Remove debug asserts in tests [Rebase \& FF[ @makubacki (#1123)
Change Details
## Description

Note: The debug asserts in the component parameter validation code in the first phase of enforcing strong parameter validation as described in #1122.

patina_dxe_core/image: Remove debug asserts from unit tests

Closes #1108
- Return EfiError::LoadError for an invalid HII resource section.
- Remove complex logic in some unit tests for testing different
  conditions with debug asserts enabled or disabled.
Remove debug_assert!() expectations in unit tests

Debug assertions will no longer be enabled when running unit tests.

While the assertions can still be used in the code, they are removed
from unit test expectations.

Disable debug assertions in the test profile

Closes #1054

To have unit tests stay focused on production expectations and
reduce complexity in tests for managing debug assertions, debug
assertions are disabled in the test profile.
- Debug asserts may still be used but we're avoiding writing tests
  around them
- Non-debug asserts may be used and tested in unit tests
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
Integration Instructions
- N/A

patina\_dxe\_core: Clean up HOB init flow @makubacki (#1120)
Change Details
## Description
The HOB list is relocated to DXE allocated memory shortly into DXE core entry. The Rust allocated HOB list is not binary compatible with the C HOB list. The Rust HOB list is a vector of references to HOB structures while the C hob list is a compact series of binary HOB structures.

While the Rust HOB list is sufficient for most use cases that simply need information from the HOBs in a more type safe and ergonomic interface, there are still use cases that require binary compatibility of the HOB list such as placement of the HOB into the system table where it is discovered by other modules, including C modules.

Today, this works because the HOB list pointer is directly passed to the system table initialization function where it is placed into the HOB list system table. This change relocates both HOB lists in the same place in the init_memory() function. Later DXE functionality consistently works on a relocated HOB list after init_memory() returns.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
- QEMU SBSA and Q35 EFI shell boot
Integration Instructions
- N/A

Move `serializable_fv` from readiness tool to `patina` @berlin-with0ut-return (#1116)
Change Details
## Description As per https://github.com/OpenDevicePartnership/patina-readiness-tool/issues/26, move the `common` crate serializable structs to patina for consistency with `serializable_hob`.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Build and run readiness tool on Q35.

Integration Instructions

Depends on OpenDevicePartnership/patina-readiness-tool#32.

patina\_dxe\_core: Create `cpu` module @Javagedes (#1115)
Change Details
Description

This commit creates a cpu module and moves all cpu related functionality into it, for better organization of the core.

Closes #1096
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

CI

Integration Instructions

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

⚠️ Breaking Changes

Add compile-time component parameter validation @makubacki (#1124)
Change Details
## Description
Today, component parameters are validated as follows:
- In debug build with debug asserts
- In test builds with debug asserts
- Not in release builds
This change both simplifies overall component definition to make their construction more consistent and easier to follow in the codebase while also introducing compile-time parameter validation for Patina-defined parameter types.

Patina-defined parameter (Param) types include types like:
- Config<T>
- ConfigMut<T>
- Hob<T>
- Service<T>
- etc.
This allows the most common errors made using the pre-defined parameter types to be detected very quickly during build. Custom parameter types will be validated at runtime. A follow up change will prevent execution of components with invalid custom parameter combinations and log an error message alongside the table of components not dispatched.

The trybuild crate is used in dev-dependencies. It provides a clean way to test that invalid parameter combinations have the expected compilation error messages. The tests are placed in a ui directory following convention described in the trybuild docs that these tests are focused on a user's interaction with the code.

The main changes are:
- Entry points are now always called entry_point and do not require any special annotation
- "Standalone" (free standing) function entry points are no longer allowed and entry points must always be an entry_point method in an impl block for the type
- Only a single #[component] attribute is needed on an impl block for a component.
The is intended to make components easier to understand and review while taking advantage of the changes to provide quick compile-time feedback on component construction.

The #[component] attribute is applied onto the impl block specifically because this allows visibility into the impl block to check if an entry_point method is present which is a requirement. Similarly, it provides visibility for any potential future component special methods to be validated.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
- QEMU Q35 & SBSA boot to EFI shell
Integration Instructions
- See the component documentation updates in the change
  </blockquote> <hr>

🚀 Features & ✨ Enhancements

Add compile-time component parameter validation @makubacki (#1124)
Change Details
## Description
Today, component parameters are validated as follows:
- In debug build with debug asserts
- In test builds with debug asserts
- Not in release builds
This change both simplifies overall component definition to make their construction more consistent and easier to follow in the codebase while also introducing compile-time parameter validation for Patina-defined parameter types.

Patina-defined parameter (Param) types include types like:
- Config<T>
- ConfigMut<T>
- Hob<T>
- Service<T>
- etc.
This allows the most common errors made using the pre-defined parameter types to be detected very quickly during build. Custom parameter types will be validated at runtime. A follow up change will prevent execution of components with invalid custom parameter combinations and log an error message alongside the table of components not dispatched.

The trybuild crate is used in dev-dependencies. It provides a clean way to test that invalid parameter combinations have the expected compilation error messages. The tests are placed in a ui directory following convention described in the trybuild docs that these tests are focused on a user's interaction with the code.

The main changes are:
- Entry points are now always called entry_point and do not require any special annotation
- "Standalone" (free standing) function entry points are no longer allowed and entry points must always be an entry_point method in an impl block for the type
- Only a single #[component] attribute is needed on an impl block for a component.
The is intended to make components easier to understand and review while taking advantage of the changes to provide quick compile-time feedback on component construction.

The #[component] attribute is applied onto the impl block specifically because this allows visibility into the impl block to check if an entry_point method is present which is a requirement. Similarly, it provides visibility for any potential future component special methods to be validated.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
- QEMU Q35 & SBSA boot to EFI shell
Integration Instructions
- See the component documentation updates in the change
  </blockquote> <hr>

Signal memory map change on set memory capabilities @joschock (#1142)
Change Details
## Description
Signal EVENT_GROUP_MEMORY_MAP_CHANGE on SetMemoryCapabilities operations.

Closes #1113
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Booted to OS on AARCH64 hardware.

Integration Instructions

N/A

Fix a potential race condition in EventDb/Allocator. @joschock (#1065)
Change Details
EventDb/Allocator: fix a circular lock dependency where gcd_map_change() callback could signal an event while downstream of an event lock.
This PR also removes the EVENT_DB_INITIALIZED static which should not be required and masks this issue in test.

Description

In some scenarios, an gcd_map_change() could occur as a result of an allocation expansion while the event lock was held. Since signalling an event required holding the event lock, this would cause re-entrancy and deadlock.

An example of such a deadlock is when a runtime event (such as virtual address change) is created, it goes into runtime::add_runtime_event() which then allocates the event structure in the runtime allocator and pushes it on a linked list. This is a pool allocation; but if that pool allocation causes an expand in the runtime allocator, this will then trigger a GCD change which will then signal an event for memory map change resulting in a re-entrant deadlock of this nature. This can be seen in unit testing if only the first commit of this PR is taken.

This change adds a mitigation for this by allowing events to be signaled even if the event lock is held - if a signal is attempted while the event lock is held, it is instead placed in a pending event queue; once the event lock is released, then any pending events signaled while the lock was held are drained (in signal order) into the event database.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Booted with aarch64 platform hardware with these changes.

Integration Instructions

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

🐛 Bug Fixes

Enable unaligned section address test in release builds @garybeihl (#1136)
Change Details
## Summary
Remove the cfg(debug_assertions) conditional from the load_image_should_fail_with_unaligned_section_address test, allowing it to run in both debug and release builds.

Background

This is possible because PR #1085 fixed set_memory_space_attributes() to properly propagate errors in release builds. Previously, errors were logged but not returned in release mode (only in debug mode via debug_assert! panic).

Dependencies

This PR depends on #1085 being merged first. The base branch for this PR is the branch from #1085, so it will only be able to be merged after #1085 is merged.

Changes
- Remove #[cfg(debug_assertions)] from test function
- Remove outdated comment about debug-only behavior
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

cargo test --package patina_dxe_core load_image_should_fail_with_unaligned_section_address -- --nocapture passes in both debug and release builds.

Integration Instructions

N/A

patina\_dxe\_core: Reset protocol database between lib.rs tests @Raymond-MS (#1138)
Change Details
## Description
Fix lib.rs tests to include resetting the protocol database.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Ran tests locally. Ran QEMU SBSA build to UEFI shell.

Integration Instructions

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

Fix a potential race condition in EventDb/Allocator. @joschock (#1065)
Change Details
EventDb/Allocator: fix a circular lock dependency where gcd_map_change() callback could signal an event while downstream of an event lock.
This PR also removes the EVENT_DB_INITIALIZED static which should not be required and masks this issue in test.

Description

In some scenarios, an gcd_map_change() could occur as a result of an allocation expansion while the event lock was held. Since signalling an event required holding the event lock, this would cause re-entrancy and deadlock.

An example of such a deadlock is when a runtime event (such as virtual address change) is created, it goes into runtime::add_runtime_event() which then allocates the event structure in the runtime allocator and pushes it on a linked list. This is a pool allocation; but if that pool allocation causes an expand in the runtime allocator, this will then trigger a GCD change which will then signal an event for memory map change resulting in a re-entrant deadlock of this nature. This can be seen in unit testing if only the first commit of this PR is taken.

This change adds a mitigation for this by allowing events to be signaled even if the event lock is held - if a signal is attempted while the event lock is held, it is instead placed in a pending event queue; once the event lock is released, then any pending events signaled while the lock was held are drained (in signal order) into the event database.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

Booted with aarch64 platform hardware with these changes.

Integration Instructions

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

patina\_dxe\_core: Prevent installing duplicate child FVs @makubacki (#1119)
Change Details
## Description
Closes #1097

Add logic to check if a firmware volume is already installed before
processing FV image files during DXE dispatch. This prevents
duplicate installation when both an FV HOB (describing a child FV
extracted earlier) and the parent FV containing that compressed child
are processed.

The check queries installed FVB (Firmware Volume Block) protocols to
determine if a firmware volume with matching name GUID already
exists.

parse_hob_fvs() installs FVB protocols for FV HOBs, so any child
FVs already described in FV HOBs should have FVB protocols installed.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
- QEMU Q35 boot to a minimal Windows image
- Physical Intel platform boot to Windows
Integration Instructions
- N/A - This changes behavior but should only prevent duplicate FVs from being processed.

x64 interrupt\_manager: Fix #PF and #GP Exception Data Prints @os-d (#1114)
Change Details
## Description
There are currently a few errors in the interpreting of exception data in the #PF and #GP exception handlers:
- When exception_data bit 3 is 1 there was a reserved bit violation, not when it is 0.
- When exception_data bit 4 is 1 this was caused by an instruction fetch, not when it is 0.
- The error code for #GP is either:
  - If the error was detected while loading a segment descriptor, the error code contains a segment selector or IDT vector number for the descriptor.
  - 0 otherwise
This also:
- Updates these functions to use the patina::bit!() macro for clarity.
- Removes the user vs supv print because we will always be supv
Relevant SDM sections:
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A.

Integration Instructions

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

📖 Documentation Updates

Minor documentation update on current perf delta @berlin-with0ut-return (#1103)
Change Details
## Description
As per #996 (comment) add a note on current Patina performance on physical (Intel) platform.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A.

Integration Instructions

N/A.

Add compile-time component parameter validation @makubacki (#1124)
Change Details
## Description
Today, component parameters are validated as follows:
- In debug build with debug asserts
- In test builds with debug asserts
- Not in release builds
This change both simplifies overall component definition to make their construction more consistent and easier to follow in the codebase while also introducing compile-time parameter validation for Patina-defined parameter types.

Patina-defined parameter (Param) types include types like:
- Config<T>
- ConfigMut<T>
- Hob<T>
- Service<T>
- etc.
This allows the most common errors made using the pre-defined parameter types to be detected very quickly during build. Custom parameter types will be validated at runtime. A follow up change will prevent execution of components with invalid custom parameter combinations and log an error message alongside the table of components not dispatched.

The trybuild crate is used in dev-dependencies. It provides a clean way to test that invalid parameter combinations have the expected compilation error messages. The tests are placed in a ui directory following convention described in the trybuild docs that these tests are focused on a user's interaction with the code.

The main changes are:
- Entry points are now always called entry_point and do not require any special annotation
- "Standalone" (free standing) function entry points are no longer allowed and entry points must always be an entry_point method in an impl block for the type
- Only a single #[component] attribute is needed on an impl block for a component.
The is intended to make components easier to understand and review while taking advantage of the changes to provide quick compile-time feedback on component construction.

The #[component] attribute is applied onto the impl block specifically because this allows visibility into the impl block to check if an entry_point method is present which is a requirement. Similarly, it provides visibility for any potential future component special methods to be validated.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested
- cargo make all
- QEMU Q35 & SBSA boot to EFI shell
Integration Instructions
- See the component documentation updates in the change
  </blockquote> <hr>

patia\_adv\_logger: Include readme in module docs @Javagedes (#1137)
Change Details
## Description
This commit does three things:
1. It completely reworks the README to make it more friendly to new users who will know nothing about the advanced logger. It includes full setup instructions and guidance on usage.
2. It replaces the top level module documentation for the crate with this readme. This has two effects. The first is that the example provided in the readme is now tested and it has the readme and module documentation always match.
3. It makes the parser module available during doc builds so that the crate documentation on crates.io shows the the parser module.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

CI

Integration Instructions

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

RFC: ESRT @kat-perez (#878)
Change Details
## Description
Status: Rejected

Proposes a new EsrtRecords service for managing the EFI System Resource Table (ESRT) with Rust-native types and memory safety guarantees.
- Impacts functionality?
- Impacts security?
- Breaking change?
- Includes tests?
- Includes documentation?
How This Was Tested

N/A

Integration Instructions

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

Full Changelog: patina-v16.0.1...v17.0.0

patina-v17.0.0

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

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

Description

How This Was Tested

Integration Instructions

⚠️ Breaking Changes

How This Was Tested

Integration Instructions

🚀 Features & ✨ Enhancements

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

Description

How This Was Tested

Integration Instructions

🐛 Bug Fixes

Background

Dependencies

Changes

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

Description

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

How This Was Tested

Integration Instructions

📖 Documentation Updates

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!