patina-v23.0.0

What's Changed

This release has several breaking changes. See the Breaking Changes section for details.

⚠️ Breaking Changes

• Integrate major branch changes into main [REBASE \& FF] @cfernald (#1671)
  
  Change Details

    ## Description

  Merged the following changes from the major branch

  PR #1628 — [major] Refactor performance into core service

  Description

  This PR addresses multiple issues with the current performance structure:

  1. Performance data is not available until the component is dispatched. This can cause significant
     misrepresentation of the DXE execution time and cause events from images to be lost if not
     dispatched in the first loop.
  2. Performance implementations in the SDK require SDK statics, which is generally an SDK antipattern.

  This PR does the following:

  1. Moves the core performance implementation into the core, into a new struct named CorePerformance,
     following the pattern established by the timer and memory management.
  2. Creates a new service trait PerformanceMeasurement that exposes this core support.
  3. Updates the component to now use this core service to produce the protocol & publish tables.
  4. Change initialization and configuration of performance measurements to be done by the core.
  5. Updates all documentation according to these changes.
  6. Some smaller rework and restructuring.

  Resolves: #1483

  Reviewing this PR

  This PR is intended to be merged as a single commit. The individual commits do attempt to follow a
  basic progression of the code rework but may be incomplete at the partial steps. Recommended review flow:

  1. Start with the new theory of operation md (performance_measurement.md) to understand the intended structure.
  2. Review the new service interface (PerformanceMeasurement).
  3. Review the new core implementation.
  4. Review the changes to the component to consume the new service.

  ---

  PR #1630 — [major] Remove SerialIO interior mutability and cleanup serial implementations [REBASE & FF]

  Description

  Change SerialIO trait to be mutable

  The current SerialIO implementation takes &self instead of &mut self for its methods, forcing
  all serial implementations to implement interior mutability. However, because of the nature of the
  serial port use cases, the typical locking mechanisms that avoid deadlocks, such as the TplMutex,
  are not readily accessible. Because of this, internal implementations have one-off, and at times
  questionable, interior mutability implementations.

  This commit removes the expectation on the serial port to ensure this, and instead provides a
  re-usable SharedSerial wrapper that implements interior mutability in a suitable way for serial
  port use cases.

  patina: Simplify serial implementations

  This commit takes advantage of the new mutable references to cleanup the serial port implementations.
  Namely by dropping re-initialization of interior references used as a workaround for the lack of
  mutability in the SerialIO trait.

  patina: split uart module submodules

  This commit splits the null, 16550, and pl011 UART implementations into their own submodules under
  the uart module. This better aligns to general code organization practices. This additionally
  removes some unnecessary conditional complication.

  ---

  PR #1643 — [major] patina_debugger: remove deprecated without_transport_init function

  Description

  This PR removes the deprecated without_transport_init function for the next major release. This
  function is now a no-op and the inverse function with_transport_init is now the control for this behavior.

  ---

  PR #1646 — [major] Refactor Patina SDK for stronger code organization [REBASE & FF]

  Description

  This PR organizes the SDK into well-defined modules, and moves code and modules into their appropriate location.

  The main goals of this refactor are to:

  1. Introduce better hierarchy for modules for definitions based on their use.
  2. Normalize paths between modules for consistency.
  3. Standardize naming conventions.
  4. Document these decisions for future consistency.

  Reviewing this PR

  The commits have been organized into a basic pattern for the sake of review. All the Patina SDK
  changes are kept in their own commits and all the mass-edits for consumers are kept in separate
  squash: ... commits. This is to keep the core changes clear and reviewable; these are squashed
  into their respective change before merging.

  There are three significant steps in this PR:

  1. Republish r_efi
  2. Move files to individual modules
  3. Refactor code and names in modules for consistency

  Top level modules

  Module	Description
  arch	Abstractions for architecture specific functionality (e.g. caching) and architecture specific functions.
  component	Component and service definitions for the dependency-injected component model.
  debug	Macros and definitions for logging and diagnostics.
  management_mode	Definitions for Management Mode (MM/SMM) interactions.
  mmio	Re-export of the safe-mmio crate for memory-mapped I/O access.
  performance	Performance measurement types, records, and related GUIDs.
  peripheral	Abstractions and implementations for core device operations.
  pi	Platform Initialization (PI) specification definitions and wrappers.
  uefi	UEFI specification definitions and wrappers.

  A detailed before/after view of the "New Patina Structure" is included in the original PR, showing the
  reorganization of files (e.g. serial.rs → standard.rs, uefi_protocol → protocol,
  protocols → protocol, new peripheral and debug modules, r_efi re-export via standard, etc.).

  ---

  PR #1660 — [major] Remove unnecessary protocol definitions from SDK

  Description

  Moves several protocol definitions from the uefi module in the SDK to their appropriate location:

  • DecompressProtocol: A duplicate definition with r_efi that carried implementation details that were not needed in the SDK.
    • Switched to use the r_efi version directly.
    • Moved implementation to dxe_core.
  • EdkiiPerformanceMeasurementProtocol: An EDKII protocol, that should only be produced and not consumed by Patina code.
    • Moved the definition to patina_performance that produces the protocol.
  • StatusCodeRuntimeProtocol: A wrapper around the PI definition providing a convenience function.
    • Moved the convenience function directly onto the pi module definition.

  ---

  PR #1666 — [major] SDK Refactor: Republish base, update consumers, and cleanup [REBASE & FF]

  Description

  Second phase of large Patina SDK refactor, including:

  Add CorePerformance to services

  The performance refactor left out declaring the CorePerformance service in the derive service macro
  for CorePerformance. This commit simply adds the missing service declaration.

  SDK Refactor: Consume r_efi republish from patina crate

  This commit changes all uses of r_efi in the patina repo to instead use the r_efi republished from
  the patina crate, and removes r_efi from individual cargo dependencies.

  SDK Refactor: Publish all of base from Patina root

  This commit republishes all of Patina::base::* from the Patina root. This flattens callers' imports
  and makes accessing common base types easier.

  patina: Scope allow(static_mut_refs) only to necessary tests

  Moves the global #![allow(static_mut_refs)] attributes to the test modules that require it, rather
  than having it at the crate level. This change improves code safety and clarity by limiting the scope
  of this allowance to only where it's needed.

  ---

  PR #1669 — [major] Breaking changes for Patina SDK UEFI Strings [Rebase & FF]

  Description

  Breaking changes to use the new UEFI string
  types that have been deferred until this PR to the major branch.

  sdk: Use Patina SDK UEFI string types in public APIs

  This is a breaking change to public APIs in the SDK to use the new UEFI string types where appropriate.

  patina_dxe_core: Use Char16Str in filesystems::SimpleFile::open

  This is a breaking change to use &Char16Str as the filename. Some other minor integrating changes in
  patina_dxe_core for the new Patina SDK UEFI string types are included.

  components: Integrate Patina SDK UEFI string changes

  Updates the code to use the new string types modified in public APIs used by components that were made
  as breaking changes.

  ---

  PR #1674 — [major] Update the MSRV to 1.90.0

  Description

  Closes #1673

  Updates the Minimum Supported Rust Version (MSRV) to 1.90.0. This update is being made at this time to
  allow dependencies with an MSRV of 1.90.0 that have security advisories to be updated.

  ---

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

  How This Was Tested

  • Unit tests
  • Patina tests on Q35
  • Patina tests on ArmVirt
  • Boot to OS on Q35
  • Boot to OS on ArmVirt

  Integration Instructions

  Performance Refactor

  Platforms must change use of with_measurements from the patina_performance to instead override PlatformInfo::default_performance_config()

  SerialIO Trait Changes

  1. All custom SerialIO implementations should drop any interior mutalability and adopt the &mut self references.
  2. Users of Uart16550 must swap to the new new_io and new_mmio instantiations.

  Debugger Changes

  Callers should remove use of without_transport_init which is already deprecated

  Patina SDK Refactor

  This change consists of major refactoring to the SDK. Consumers should ensure the following

  Consume standard::efi instead of using r_efi to ensure consistent compilation.

  1. Update all references to modules moved to their new location. See the "New Patina Structure" above for reference.
  2. Update all renamed structures to conform to their new convention-based name

  It is not practical to enumerate all possible changes here, but if there is any ambiguity, reach out to the core Patina team.

  String Based Interface Changes

  Review the public API changes and adjust consuming code accordingly. Any callers in the patina repo are updated in this PR.

  Rust Version

  MSRV Updated to 1.9. Consumers must update as well.
  

  
  

  ---

  
  

📖 Documentation Updates

• Integrate major branch changes into main [REBASE \& FF] @cfernald (#1671)
  
  Change Details

    ## Description

  Merged the following changes from the major branch

  PR #1628 — [major] Refactor performance into core service

  Description

  This PR addresses multiple issues with the current performance structure:

  1. Performance data is not available until the component is dispatched. This can cause significant
     misrepresentation of the DXE execution time and cause events from images to be lost if not
     dispatched in the first loop.
  2. Performance implementations in the SDK require SDK statics, which is generally an SDK antipattern.

  This PR does the following:

  1. Moves the core performance implementation into the core, into a new struct named CorePerformance,
     following the pattern established by the timer and memory management.
  2. Creates a new service trait PerformanceMeasurement that exposes this core support.
  3. Updates the component to now use this core service to produce the protocol & publish tables.
  4. Change initialization and configuration of performance measurements to be done by the core.
  5. Updates all documentation according to these changes.
  6. Some smaller rework and restructuring.

  Resolves: #1483

  Reviewing this PR

  This PR is intended to be merged as a single commit. The individual commits do attempt to follow a
  basic progression of the code rework but may be incomplete at the partial steps. Recommended review flow:

  1. Start with the new theory of operation md (performance_measurement.md) to understand the intended structure.
  2. Review the new service interface (PerformanceMeasurement).
  3. Review the new core implementation.
  4. Review the changes to the component to consume the new service.

  ---

  PR #1630 — [major] Remove SerialIO interior mutability and cleanup serial implementations [REBASE & FF]

  Description

  Change SerialIO trait to be mutable

  The current SerialIO implementation takes &self instead of &mut self for its methods, forcing
  all serial implementations to implement interior mutability. However, because of the nature of the
  serial port use cases, the typical locking mechanisms that avoid deadlocks, such as the TplMutex,
  are not readily accessible. Because of this, internal implementations have one-off, and at times
  questionable, interior mutability implementations.

  This commit removes the expectation on the serial port to ensure this, and instead provides a
  re-usable SharedSerial wrapper that implements interior mutability in a suitable way for serial
  port use cases.

  patina: Simplify serial implementations

  This commit takes advantage of the new mutable references to cleanup the serial port implementations.
  Namely by dropping re-initialization of interior references used as a workaround for the lack of
  mutability in the SerialIO trait.

  patina: split uart module submodules

  This commit splits the null, 16550, and pl011 UART implementations into their own submodules under
  the uart module. This better aligns to general code organization practices. This additionally
  removes some unnecessary conditional complication.

  ---

  PR #1643 — [major] patina_debugger: remove deprecated without_transport_init function

  Description

  This PR removes the deprecated without_transport_init function for the next major release. This
  function is now a no-op and the inverse function with_transport_init is now the control for this behavior.

  ---

  PR #1646 — [major] Refactor Patina SDK for stronger code organization [REBASE & FF]

  Description

  This PR organizes the SDK into well-defined modules, and moves code and modules into their appropriate location.

  The main goals of this refactor are to:

  1. Introduce better hierarchy for modules for definitions based on their use.
  2. Normalize paths between modules for consistency.
  3. Standardize naming conventions.
  4. Document these decisions for future consistency.

  Reviewing this PR

  The commits have been organized into a basic pattern for the sake of review. All the Patina SDK
  changes are kept in their own commits and all the mass-edits for consumers are kept in separate
  squash: ... commits. This is to keep the core changes clear and reviewable; these are squashed
  into their respective change before merging.

  There are three significant steps in this PR:

  1. Republish r_efi
  2. Move files to individual modules
  3. Refactor code and names in modules for consistency

  Top level modules

  Module	Description
  arch	Abstractions for architecture specific functionality (e.g. caching) and architecture specific functions.
  component	Component and service definitions for the dependency-injected component model.
  debug	Macros and definitions for logging and diagnostics.
  management_mode	Definitions for Management Mode (MM/SMM) interactions.
  mmio	Re-export of the safe-mmio crate for memory-mapped I/O access.
  performance	Performance measurement types, records, and related GUIDs.
  peripheral	Abstractions and implementations for core device operations.
  pi	Platform Initialization (PI) specification definitions and wrappers.
  uefi	UEFI specification definitions and wrappers.

  A detailed before/after view of the "New Patina Structure" is included in the original PR, showing the
  reorganization of files (e.g. serial.rs → standard.rs, uefi_protocol → protocol,
  protocols → protocol, new peripheral and debug modules, r_efi re-export via standard, etc.).

  ---

  PR #1660 — [major] Remove unnecessary protocol definitions from SDK

  Description

  Moves several protocol definitions from the uefi module in the SDK to their appropriate location:

  • DecompressProtocol: A duplicate definition with r_efi that carried implementation details that were not needed in the SDK.
    • Switched to use the r_efi version directly.
    • Moved implementation to dxe_core.
  • EdkiiPerformanceMeasurementProtocol: An EDKII protocol, that should only be produced and not consumed by Patina code.
    • Moved the definition to patina_performance that produces the protocol.
  • StatusCodeRuntimeProtocol: A wrapper around the PI definition providing a convenience function.
    • Moved the convenience function directly onto the pi module definition.

  ---

  PR #1666 — [major] SDK Refactor: Republish base, update consumers, and cleanup [REBASE & FF]

  Description

  Second phase of large Patina SDK refactor, including:

  Add CorePerformance to services

  The performance refactor left out declaring the CorePerformance service in the derive service macro
  for CorePerformance. This commit simply adds the missing service declaration.

  SDK Refactor: Consume r_efi republish from patina crate

  This commit changes all uses of r_efi in the patina repo to instead use the r_efi republished from
  the patina crate, and removes r_efi from individual cargo dependencies.

  SDK Refactor: Publish all of base from Patina root

  This commit republishes all of Patina::base::* from the Patina root. This flattens callers' imports
  and makes accessing common base types easier.

  patina: Scope allow(static_mut_refs) only to necessary tests

  Moves the global #![allow(static_mut_refs)] attributes to the test modules that require it, rather
  than having it at the crate level. This change improves code safety and clarity by limiting the scope
  of this allowance to only where it's needed.

  ---

  PR #1669 — [major] Breaking changes for Patina SDK UEFI Strings [Rebase & FF]

  Description

  Breaking changes to use the new UEFI string
  types that have been deferred until this PR to the major branch.

  sdk: Use Patina SDK UEFI string types in public APIs

  This is a breaking change to public APIs in the SDK to use the new UEFI string types where appropriate.

  patina_dxe_core: Use Char16Str in filesystems::SimpleFile::open

  This is a breaking change to use &Char16Str as the filename. Some other minor integrating changes in
  patina_dxe_core for the new Patina SDK UEFI string types are included.

  components: Integrate Patina SDK UEFI string changes

  Updates the code to use the new string types modified in public APIs used by components that were made
  as breaking changes.

  ---

  PR #1674 — [major] Update the MSRV to 1.90.0

  Description

  Closes #1673

  Updates the Minimum Supported Rust Version (MSRV) to 1.90.0. This update is being made at this time to
  allow dependencies with an MSRV of 1.90.0 that have security advisories to be updated.

  ---

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

  How This Was Tested

  • Unit tests
  • Patina tests on Q35
  • Patina tests on ArmVirt
  • Boot to OS on Q35
  • Boot to OS on ArmVirt

  Integration Instructions

  Performance Refactor

  Platforms must change use of with_measurements from the patina_performance to instead override PlatformInfo::default_performance_config()

  SerialIO Trait Changes

  1. All custom SerialIO implementations should drop any interior mutalability and adopt the &mut self references.
  2. Users of Uart16550 must swap to the new new_io and new_mmio instantiations.

  Debugger Changes

  Callers should remove use of without_transport_init which is already deprecated

  Patina SDK Refactor

  This change consists of major refactoring to the SDK. Consumers should ensure the following

  Consume standard::efi instead of using r_efi to ensure consistent compilation.

  1. Update all references to modules moved to their new location. See the "New Patina Structure" above for reference.
  2. Update all renamed structures to conform to their new convention-based name

  It is not practical to enumerate all possible changes here, but if there is any ambiguity, reach out to the core Patina team.

  String Based Interface Changes

  Review the public API changes and adjust consuming code accordingly. Any callers in the patina repo are updated in this PR.

  Rust Version

  MSRV Updated to 1.9. Consumers must update as well.
  

  
  

  ---

  
  

Full Changelog: patina-v22.2.4...v23.0.0