From dbe13303112d616fa79042d45ebcad6b37af8068 Mon Sep 17 00:00:00 2001 From: Chris Fernald Date: Tue, 14 Oct 2025 14:21:40 -0700 Subject: [PATCH] RFC: Runtime Service Module Support This RFC proposes a roadmap for support of runtime service modules in Patina. --- .../rfc/text/0000-runtime-services-support.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/src/rfc/text/0000-runtime-services-support.md diff --git a/docs/src/rfc/text/0000-runtime-services-support.md b/docs/src/rfc/text/0000-runtime-services-support.md new file mode 100644 index 000000000..f78935359 --- /dev/null +++ b/docs/src/rfc/text/0000-runtime-services-support.md @@ -0,0 +1,161 @@ +# RFC: Runtime Services Support + +This RFC proposes a roadmap for Runtime Services and runtime module support for the +Patina project. Runtime modules and services must exist in separate memory regions +from the monolithic Patina core and so present problems for using the existing core +and infrastructure to support. This RFC proposes that a new runtime module be spun +up from the existing Rust code and to defer other future support. This RFC leaves open +the possibility that this module be extended in the future. + +## Change Log + +- 10-14-25: Initial RFC created. + +## Motivation + +Runtime services present a unique challenge for the monolithic binary model that +Patina uses. Runtime services must exist after boot services have been unloaded, +and so it is not possible for the runtime services to exist as part of the +monolithic binary, at least without very specialized handling. Runtime services +must have a focused roadmap to align with the goals and development models of +Patina to be clear about expected investments. + +## Technology Background + +Currently the EDKII implementation dispatches runtime modules as part of DXE phase, +most notably RuntimeDxe which provides core services such as `SetVirtualAddressMap` +and other modules to implement more platform specific runtime services. The original +implementation on Patina provided an implementation of `SetVirtualAddressMap` within +the monolithic core, but this results in some problems on Windows boot as we will +leverage boot services memory in `SetVirtualAddressMap` which is a runtime service +and executes after ExitBootServices. Generally, this makes assumptions about OS +behavior which may not be sustainable. These were resolved in the following PRs. + +- [dxe_core: Move runtime event handling into runtime module](https://github.com/OpenDevicePartnership/patina/pull/738) +- [patina_dxe_core: Switch to use external RuntimeDxe implementation](https://github.com/OpenDevicePartnership/patina/pull/769) + +The approach that has been taken in the interim is to remove the Patina +implementation for now and to ask platforms to go back to the EDKII RuntimeDxe. + +## Goals + +1. Set short term support plan for runtime services/modules. +2. Enumerate expansion plans for runtime services in the future. + +## Requirements + +1. Runtime services must continue to operate as expected for short term. +2. Runtime modules must exist purely in runtime service memory. +3. Long term goals should remove dependence on EDKII runtime code. + +## Unresolved Questions + +- Is there a suitable type of dynamic linking that may make other options suitable + without excessive one-off infrastructure? + +## Prior Art (Existing PI C Implementation) + +The current C implementation consists of one primary runtime module, usually +RuntimeDxe and a variable amount of additional runtime modules. These modules are +dispatched by DXE, but will be loaded in runtime memory. The primary runtime module +should produce the runtime architecture protocol, defined in the PI spec section +12.8. This protocol allows for the core to fill in critical information for the +runtime module to implement SetVirtualAddressMap. This includes the image list of +runtime modules, events registered for virtualizing memory, and memory map +information that is not currently used. When `SetVirtualAddressMap` is called, the +runtime DXE module will use the information from the protocol it published and the +core filled to re-relocate the images, virtualizing their execution, and call all +events registered to allow drivers/libraries to virtualize any stored pointers. + +## Alternatives + +### Create new interface for runtime architectural information + +Instead of using runtime architectural protocol for the chosen driver model, a new +protocol or interface could be invented that would allow safer parsing. For example, +for the event and image lists, these could be instead maintained in a vector and +the slices provided through a protocol. This would prevent the need for unsafe logic +in walking a raw pointer based linked list. However, this would be creating a new +set of rust-to-rust interfaces that do not exist within the monolithically compiled +binaries. This both complicates the interoperability story with existing code, and +will only be applicable to this one off scenario for the time being. + +### Dynamic Module Linking + +An alternative to leveraging the protocol communication would be to allow dynamic +linking and direct invocation of the runtime module. This would prevent the need +for secondary structures and callbacks. However, this raises many questions and +potential toolchain problems such as support between GCC and MSVC tool chains for +dynamic linking. This would also invent additional infrastructure needed only for +runtime services. + +### Runtime Service Removal + +The long term goal of runtime services, instead of replacing them, should be to +remove them. Most runtime services are superfluous on modern machines. The only +runtime service that is typically invoked at runtime that cannot be replaced with +other existing mechanisms is variable services. Even so, variable services are nearly +always a simple wrapper around calls to the implementation executing in either SMM +or TrustZone. An alternative to re-implementing runtime services for Patina, would +be to simply not support runtime services at runtime, but instead provide a +specification defined interface to access variable services directly through SMM +and TrustZone. + +However, this is not feasible in the short term. Any solution here would require +updates both to the UEFI specifications to support them as well as specification +of the new SMM/TrustZone interfaces, not to mention OS support. While removal of +runtime services is a desirable long term goal it does not satisfy the immediate +goals of this RFC. + +### Defer Runtime Module Support + +Another solution is to defer implementation of any Rust runtime module until DXE +and MM are solved and a more clear interfacing model appears, and continue to use +the EDKII implementation of RuntimeDxe in the interim. The EDKII implementation +would either be replaced by a more robust implementation of a Patina runtime or +removed in the future if runtime services are no longer required in the future. +However, as explained above a more robust solution in this space is filled with +complications and is unlikely to occur in the near future. Additionally, runtime +service removal will be a long process of standardization and OS support. Deferring +until a more complete solution may not be feasible. + +## Rust Code Design + +Patina should continue to use separate runtime modules which interface using the +UEFI and PI defined interfaces. This includes the system architectural protocol for +resources from the core as well as boot services for allocations and other DXE +phase calls. + +However, as a stepping stone to replacement RuntimeDxe should be implementation of a +Rust driver leveraging the original code removed in the above PRs. This driver would +be implemented in the Rust driver infrastructure developed for EDKII and located in +the PatinaPkg. This module would use all existing UEFI/PI interfaces to access boot +services and communicate runtime image and event data. The responsibilities of each +module in this model are detailed below. + +### Patina DXE Core + +The Patina DXE core will continue to listen for the registration of the runtime +architectural protocol, and register event and image data to the protocol. This +will be updated whenever a new runtime image is loaded or a new `SetVirtualAddressMap` +callback is registered. + +### Patina Runtime (new) + +A new module compiled as a Rust driver in an EDKII environment, provides a +compatible implementation as RuntimeDxe to implement core functions, i.e. +`SetVirtualAddressMap` & `ConvertPointer`. This driver will install the runtime +architectural protocol. On `SetVirtualAddressMap` the module will be responsible for +re-relocating images and invoking all appropriate events filled in the +architectural protocol. + +### Refactoring Relocation Logic (optional) + +The logic necessary to relocate the PE is currently split across multiple modules +in patina_dxe_core. To reduce code duplication, it may be desirable to refactor the +PE loader logic into a standalone crate, e.g. `patina_loader`. Without this, +relocation and PE parsing logic may need to be duplicated. + +## Guide-Level Explanation + +Does not change any consumable rust APIs.