From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from linux.microsoft.com (linux.microsoft.com [13.77.154.182]) by mx.groups.io with SMTP id smtpd.web12.12076.1647966059708761614 for ; Tue, 22 Mar 2022 09:20:59 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@linux.microsoft.com header.s=default header.b=SdrOBYzx; spf=pass (domain: linux.microsoft.com, ip: 13.77.154.182, mailfrom: mikuback@linux.microsoft.com) Received: from localhost.localdomain (unknown [47.202.59.224]) by linux.microsoft.com (Postfix) with ESMTPSA id 41EF520B4783; Tue, 22 Mar 2022 09:20:58 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com 41EF520B4783 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1647966059; bh=J6h2VXVRPv36R7h2CZfTZ4UP1HiKDu0xWbc3IFmkoj0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SdrOBYzxgKKWvajlKSvC2Fb42DGZkLjF6S8wChnTa+E1RgJ5HurPpioSd+FxkTykt AcNyuN2Jrdv5bsGhK5QpJfjdNsWfjIPIN4ve/6lkyYivfGuv8SR/ZYZ0xlVyGmQf5R myRgADiLKU8BHE76R8f6ZeFjBMMsUr3m1bMqiOlk= From: "Michael Kubacki" To: devel@edk2.groups.io Cc: Andrew Fish , Kang Gao , Michael D Kinney , Michael Kubacki , Leif Lindholm , Benjamin You , Liu Yun , Ankit Sinha , Nate DeSimone Subject: [PATCH v1 10/41] Readme.md: Add initial content Date: Tue, 22 Mar 2022 12:19:16 -0400 Message-Id: <20220322161947.9319-11-mikuback@linux.microsoft.com> X-Mailer: git-send-email 2.28.0.windows.1 In-Reply-To: <20220322161947.9319-1-mikuback@linux.microsoft.com> References: <20220322161947.9319-1-mikuback@linux.microsoft.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable From: Michael Kubacki REF:https://bugzilla.tianocore.org/show_bug.cgi?id=3D3812 Adds the following content to Readme.md: 1. A basic explanation of how the package is organized and where to find important items. 2. Adds instructions for building PrmPkg with edk2. 3. Adds a "Build Flags" section to the build instructions to explain any build flags that may be passed to influence the build. The final package will not have any build flags. A reasonable number are temporarily used to test different flows until final decisions are made as to which flow to keep. Most notably, only Visual Studio tool chains are currently supported due to the modifications made to support export tables. Cc: Andrew Fish Cc: Kang Gao Cc: Michael D Kinney Cc: Michael Kubacki Cc: Leif Lindholm Cc: Benjamin You Cc: Liu Yun Cc: Ankit Sinha Cc: Nate DeSimone Signed-off-by: Michael Kubacki --- PrmPkg/Readme.md | 212 ++++++++++++++++++++ 1 file changed, 212 insertions(+) diff --git a/PrmPkg/Readme.md b/PrmPkg/Readme.md new file mode 100644 index 000000000000..b67b3a391e37 --- /dev/null +++ b/PrmPkg/Readme.md @@ -0,0 +1,212 @@ +# **Platform Runtime Mechanism** + +Platform Runtime Mechanism (PRM) introduces the capability of moving pla= tform-specific code out of SMM and into a +code module that executes within the OS context. Moving this firmware to= the OS context provides better transparency +and mitigates the negative system impact currently accompanied with SMM = solutions. Futhermore, the PRM code is +packaged into modules with well-defined entry points, each representing = a specific PRM functionality. + +The `PrmPkg` maintained in this branch provides a single cohesive set of= generic PRM functionality that is intended +to be leveraged by platform firmware with minimal overhead to integrate = PRM functionality in the firmware. + +## **IMPORTANT NOTE** +> The code provided in this package and branch are for proof-of-concept= purposes only. The code does not represent a +formal design and is not validated at product quality. The development o= f this feature is shared in the edk2-staging +branch to simplify collaboration by allowing direct code contributions a= nd early feedback throughout its development. + +## How to Build PrmPkg +As noted earlier, resources in `PrmPkg` are intended to be referenced by= a platform firmware so it can adopt support +for PRM. In that case, the platform firmware should add the `PrmConfigDx= e` and `PrmLoaderDxe` drivers to its DSC and +FDF files so they are built in the platform firmware build and dispatche= d during its runtime. All that is left is to +add individual PRM modules to the DSC and FDF. These can be built from s= ource or included as binaries into the platform +firmware flash map. + +### PrmPkg Standalone Build +**All changes to `PrmPkg` must not regress the standalone package build*= *. Any time a change is made to `PrmPkg`, the +package build must be tested. Since this is a forward looking package, t= o ease potential integration into the edk2 +project in the future, the build is tested against the tip of the master= branch in the [edk2](https://github.com/tianocore/edk2) +repository. + +To build `PrmPkg` as a standalone package: +1. If new to EDK II, follow the directions in [Getting Started with EDK = II](https://github.com/tianocore/tianocore.github.io/wiki/Getting-Started= -with-EDK-II) + +2. Clone the *master* branch on the edk2 repository locally \ + ``git clone https://github.com/tianocore/edk2.git`` + +3. Clone the *PlatformRuntimeMechanism* branch on the edk2-staging repos= itory locally \ + ``git clone -b PlatformRuntimeMechanism --single-branch https://githu= b.com/tianocore/edk2-staging.git`` + > __*Note*__: The *--single-branch* argument is recommended since edk= 2-staging hosts many branches for completely + unrelated features. If you are just interested in PRM, this will avoi= d fetching all of the other branches. + +4. Change to the edk2 workspace directory \ + ``cd edk2`` + +5. Run *edksetup* to set local environment variables needed for build + * Windows: + * ``edksetup.bat`` + * Linux: + * If you have not already built BaseTools: + * ``make -C BaseTools`` + * ``. edksetup.sh`` + +6. Set the PACKAGES_PATH environment variable to include the directory p= ath that contains `PrmPkg` + * Windows example: + * ``set PACKAGES_PATH=3Dc:\src\edk2-staging`` + +7. Change to the edk2-staging workspace directory + * Example: ``cd ../edk2-staging`` + +8. Build PrmPkg \ + ``build -p PrmPkg/PrmPkg.dsc -a IA32 -a X64`` + > __*Note*__: Due to the way PRM modules are compiled with exports, *= *only building on Visual Studio compiler tool + chains is currently supported**. + +### Build Flags +As PRM is a new feature at a proof-of-concept (POC) level of maturity, t= here's some changes to the normal build +available as build flags. By default, if no flags are specified, the bui= ld is done with the currently expected plan of +record (POR) configuration. + +The following list are the currently defined build flags (if any) that m= ay be passed to the `build` command +(e.g. -D FLAG=3DVALUE). + +## Overview +At a high-level, PRM can be viewed from three levels of granularity: + +1. PRM interface - Encompassing the entirety of firmware functionalities= and data provided to OS runtime. Most + information is provided through ACPI tables to be agnostic to a UEFI = implementation. +2. PRM module - An independently updatable package of PRM handlers. The = PRM interface will be composed of multiple + PRM modules. This requirement allows for the separation of OEM and IH= V PRM code, each of which can be serviced + independently. +3. PRM handler - The implementation/callback of a single PRM functionali= ty as identified by a GUID. + +## Firmware Design +The firmware has three key generic drivers to support PRM: + +1. A PRM Loader driver - Functionality is split across three phases: + 1. Discover - Find all PRM modules in the firmware image made availab= le by the platform firmware author. + * This phase includes verifying authenticity/integrity of the imag= e, the image executable type, the export + table is present and the PRM Export Module Descriptor is present= and valid. + 2. Process - Convert PRM handler GUID to name mappings in the PRM Mod= ule Export Descriptor to PRM handler Name + to physical address mappings required to construct the PRM ACPI ta= ble. + 3. Publish - Publish the PRM ACPI table using the information from th= e Process phase. + +2. A PRM Configuration driver - A generic driver responsible for process= ing PRM module configuration information + consumed through a `PRM_CONFIG_PROTOCOL` per PRM module instance. The= refore, the `PRM_CONFIG_PROTOCOL` serves + as the dynamic interface for this driver to process PRM module resour= ces and prepare the module's data to be + configured properly for OS runtime. + +3. A PRM Module - Not a single driver but a user written PE/COFF image t= hat follows the PRM module authoring process. + A PRM module groups together cohesive sets of PRM functionality into = functions referred to as "PRM handlers". + +## PrmPkg Code Organization +The package follows a standard EDK II style package format. The list bel= ow contains some notable areas to +explore in the package: + +* [ACPI Table Definitions](PrmPkg/PrmLoaderDxe/PrmAcpiTable.h) +* [Common Interface Definitions](PrmPkg/Include) +* [PRM Config Driver](PrmPkg/PrmConfigDxe) +* [PRM Loader Driver](PrmPkg/PrmLoaderDxe) +* [Sample PRM Modules](PrmPkg/Samples) + +While the package does provide sample PRM modules to be used as a refere= nce, actual PRM modules should not be +maintained in PrmPkg. It is intended to only contain PRM infrastructure = code and a few samples of how to use +that infrastructure. The PrmPkg is meant to be used as-is by firmware th= at supports PRM. Any shortcomings that +prevent the package from being used as-is should be addressed directly i= n PrmPkg. + +## PRM Module + +By default, the EDK II implementation of UEFI does not allow images with= the subsystem type +IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER to be built with exports.=C2=A0 + +``` +ERROR - Linker #1294 from LINK : fatal exports and import libraries are = not supported with /SUBSYSTEM:EFI_RUNTIME_DRIVER +``` +This can adjusted in the MSVC=C2=A0linker options. + +__For the purposes of this POC__, the subsystem type is changed in the f= irmware build to allow the export table to be +added but the subsystem type=C2=A0in the final image is still 0xC (EFI R= untime Driver). This is important to allow the DXE +dispatcher to use its standard image verification and loading algorithms= to load the image into permanent memory during +the DXE execution phase. + +All firmware-loaded PRM modules are loaded into a memory buffer of type = EfiRuntimeServicesCode. This means the +operating system must preserve all PRM handler code and the buffer will = be reflected in the UEFI memory map. The +execution for invoking PRM handlers is the same as that required for UEF= I Runtime Services, notably 4KiB or more of +available stack space must be provided and the stack must be 16-byte ali= gned.=C2=A0 + +__*Note:*__=C2=A0Long term it is possible to similarly load the modules = into a EfiRuntimeServicesCode buffer and perform +relocation fixups with a new EFI module type for PRM if desired. It was = simply not done since it is not essential +for this POC. + +Where possible, PRM module information is stored and generated using ind= ustry compiler tool chains. This is a key +motivation behind using PE/COFF export tables to expose PRM module infor= mation and using a single PRM module binary +definition consistent between firmware and OS load. + +### PRM Module Exports +A PRM module must contain at least three exports: A PRM Module Export De= scriptor, a PRM Module Update Lock Descriptor, +and at least one PRM handler. Here's an example of an export table from = a PRM module that has a single PRM handler: + +``` + 0000000000005000: 00 00 00 00 FF FF FF FF 00 00 00 00 46 50 00 00 ...= .=C3=BF=C3=BF=C3=BF=C3=BF....FP.. + 0000000000005010: 01 00 00 00 03 00 00 00 03 00 00 00 28 50 00 00 ...= .........(P.. + 0000000000005020: 34 50 00 00 40 50 00 00 78 13 00 00 30 40 00 00 4P.= .@P..x...0@.. + 0000000000005030: 20 40 00 00 67 50 00 00 86 50 00 00 A0 50 00 00 @.= .gP...P...P.. + 0000000000005040: 00 00 01 00 02 00 50 72 6D 53 61 6D 70 6C 65 43 ...= ...PrmSampleC + 0000000000005050: 6F 6E 74 65 78 74 42 75 66 66 65 72 4D 6F 64 75 ont= extBufferModu + 0000000000005060: 6C 65 2E 64 6C 6C 00 44 75 6D 70 53 74 61 74 69 le.= dll.DumpStati + 0000000000005070: 63 44 61 74 61 42 75 66 66 65 72 50 72 6D 48 61 cDa= taBufferPrmHa + 0000000000005080: 6E 64 6C 65 72 00 50 72 6D 4D 6F 64 75 6C 65 45 ndl= er.PrmModuleE + 0000000000005090: 78 70 6F 72 74 44 65 73 63 72 69 70 74 6F 72 00 xpo= rtDescriptor. + 00000000000050A0: 50 72 6D 4D 6F 64 75 6C 65 55 70 64 61 74 65 4C Prm= ModuleUpdateL + 00000000000050B0: 6F 63 6B 00 ock= . + + 00000000 characteristics + FFFFFFFF time date stamp + 0.10 version + 1 ordinal base + 3 number of functions + 3 number of names + + ordinal hint RVA name + 1 0 00001378 DumpStaticDataBufferPrmHandler + 2 1 00004030 PrmModuleExportDescriptor + 3 2 00004020 PrmModuleUpdateLock +``` +### PRM Image Format +PRM modules are ultimately PE/COFF images. However, when packaged in fir= mware the PE/COFF image is placed into a +Firmware File System (FFS) file. This is transparent to the operating sy= stem but done to better align with the typical +packaging of PE32(+) images managed in the firmware binary image. In the= dump of the PRM FV binary image=C2=A0shown earlier, +the=C2=A0FFS sections placed by EDK II build tools=C2=A0("DXE dependency= ", "User interface", "Version") that reside alongside the +PE/COFF binary=C2=A0are shown. A PRM module can be placed into a firmwar= e image as a pre-built PE/COFF binary or built +during the firmware build process. In either case, the PE/COFF section i= s contained in a FFS file as shown in that +image. + +### PRM Module Implementation +To simplify building the PRM Module Export Descriptor, a PRM module impl= ementation can use the following macros to mark +functions as PRM handlers. In this example, a PRM module registers three= functions by name as PRM handlers with the +associated GUIDs. + +``` +// +// Register the PRM export information for this PRM Module +// +PRM_MODULE_EXPORT ( + PRM_HANDLER_EXPORT_ENTRY (PRM_HANDLER_1_GUID, PrmHandler1), + PRM_HANDLER_EXPORT_ENTRY (PRM_HANDLER_2_GUID, PrmHandler2), + PRM_HANDLER_EXPORT_ENTRY (PRM_HANDLER_N_GUID, PrmHandlerN) + ); +``` + +`PRM_MODULE_EXPORT` take a variable-length argument list of `PRM_HANDLER= _EXPORT_ENTRY` entries that each describe an +individual PRM handler being exported for the module. Ultimately, this i= nformation is used to define the structure +necessary to statically allocate the PRM Module Export Descriptor Struct= ure (and its PRM Handler Export Descriptor +substructures) in the image. + +Another required export for PRM modules is automatically provided in `Pr= mModule.h`, a header file that pulls together +all the includes needed to author a PRM module. This export is `PRM_MODU= LE_UPDATE_LOCK_EXPORT`. By including, +`PrmModule.h`, a PRM module has the `PRM_MODULE_UPDATE_LOCK_DESCRIPTOR` = automatically exported. + +## PRM Handler Constraints +At this time, PRM handlers are restricted to a maximum identifier length= of 128 characters. This is checked when using +the `PRM_HANDLER_EXPORT` macro by using a static assert that reports a v= iolation at build-time. + +PRM handlers are **not** allowed to use UEFI Runtime Services and should= not rely upon any UEFI constructs. For the +purposes of this POC, this is currently not explicitly enforced but shou= ld be in the final changes. --=20 2.28.0.windows.1