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.web08.12170.1647966129186084031 for ; Tue, 22 Mar 2022 09:22:09 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@linux.microsoft.com header.s=default header.b=mnHYkAl8; 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 CCD6020B4783; Tue, 22 Mar 2022 09:22:07 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.11.0 linux.microsoft.com CCD6020B4783 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.microsoft.com; s=default; t=1647966128; bh=PrupG1lP95WXUpgHXIva69CTMmZCKEsyMyAfBfujE2E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mnHYkAl80tbCFDZWqcNJAnWdt9tUjzjAuTjne996j4v1N9+Se5+pOdI1kqBSWQ/uL /DAqrG2TKMHdbUcYCh/XLYOQ8b0tP/gT4B6YbqPFg79pef//jPzpX9vibmIiy7RdGH R+gUZAYI/D5a1DFpk4mFbvi8HpcYzIpL3G3p2z30= 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 24/41] PrmPkg/Samples/Readme.md: Add initial file Date: Tue, 22 Mar 2022 12:19:30 -0400 Message-Id: <20220322161947.9319-25-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 Adds a Readme.md file for the Samples to help a user get started building and using the PRM sample modules. Includes a reference to the Samples/Readme.md file in the top-level file to help make the reader aware the file exists. 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 | 5 +- PrmPkg/Samples/Readme.md | 263 ++++++++++++++++++++ 2 files changed, 267 insertions(+), 1 deletion(-) diff --git a/PrmPkg/Readme.md b/PrmPkg/Readme.md index 52b44a95ddbc..b79cb66c4790 100644 --- a/PrmPkg/Readme.md +++ b/PrmPkg/Readme.md @@ -9,7 +9,7 @@ The `PrmPkg` maintained in this branch provides a single = cohesive set of generic to be leveraged by platform firmware with minimal overhead to integrate = PRM functionality in the firmware. =20 ## **IMPORTANT NOTE** -> The code provided in this package and branch are for proof-of-concept= purposes only. The code does not represent a +> 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. =20 @@ -120,6 +120,9 @@ prevent the package from being used as-is should be a= ddressed directly in PrmPkg =20 ## PRM Module =20 +> __*Note*__: You can find simple examples of PRM modules in the Samples= directory of this package. +> [Samples/Readme.md](PrmPkg/Samples/Readme.md) has more information. + 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 =20 diff --git a/PrmPkg/Samples/Readme.md b/PrmPkg/Samples/Readme.md new file mode 100644 index 000000000000..4926be243018 --- /dev/null +++ b/PrmPkg/Samples/Readme.md @@ -0,0 +1,263 @@ +# **Platform Runtime Mechanism Sample Modules** + +The PRM module samples provided here serve as focused examples of how to= perform various tasks in a PRM module. The +samples can also be used to verify the basic infrastructure needed in yo= ur firmware implementation is working as +expected by checking that the sample modules are found properly and the = handlers perform their tasks as noted. + +## **IMPORTANT NOTE** +> The sample modules have currently only been tested on the Visual Studi= o compiler tool chain. Sample module +build may fail on other tool chains. A future work item is to enable bro= ader build support. + +## How to Build PRM Sample Modules +The sample modules are built as part of the normal `PrmPkg` build so you= can follow the +[package build instructions](../../Readme.md#how-to-build-prmpkg) and th= en find the PRM sample binaries in your +workspace build output directory. For example, if your build workspace i= s called "edk2" and you build +64-bit binaries on the Visual Studio 2017 tool chain, your sample module= binaries will be in the following +location: \ +``edk2/Build/Prm/DEBUG_VS2017/X64/PrmPkg/Samples`` + +### Build an Individual PRM Sample Module +Note that the build command does provide the option to build a specific = module in a package which can result in +faster build time. If you would like to just build a single PRM module t= hat can be done by specifying the path to +the module INF file with the "-m" argument to `build`. For example, this= command builds 32-bit and 64-bit binaries +with Visual Studio 2019: \ +``build -p PrmPkg/PrmPkg.dsc -m PrmPkg/Samples/PrmSamplePrintModule/PrmS= amplePrintModule.inf -a IA32 -a X64 -t VS2019`` + +## PRM Sample Module User's Guide + +The following table provides an overview of each sample module provided.= By nature, different PRM handlers have +different requirements. The information here is summarized for a user to= understand how to use a given sample +PRM handler along with GUID/name information to identify the sample PRM = modules and their PRM handlers. + +It is recommended that all PRM authors write a similar set of documentat= ion for their users to better understand +and interact with their PRM modules. + +--- +### Module: PRM Sample Print Module +>* Name: `PrmSamplePrintModule` +>* GUID: `1652b3c2-a7a1-46ac-af93-dd6dee446669` +> * Purpose: +> * Simplest PRM module example +> * Example of a PRM module with multiple PRM handlers + +**Handlers:** +#### Handler: PRM Handler 1 +* Name: `PrmHandler1` +* GUID: `d5f2ad5f-a347-4d3e-87bc-c2ce63029cc8` +* Actions: + * Use an OS-provided function pointer (pointer at the beginning of the= parameter buffer) to write the message + =E2=80=9CPRM1 handler sample message!=E2=80=9D + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: PRM Handler 2 +* Name: `PrmHandler2` +* GUID: `a9e7adc3-8cd0-429a-8915-10946ebde318` +* Actions: + * Use an OS-provided function pointer (pointer at the beginning of the= parameter buffer) to write the message + =E2=80=9CPRM2 handler sample message!=E2=80=9D + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: PRM Handler N +* Name: `PrmHandlerN` +* GUID: `b688c214-4081-4eeb-8d26-1eb5a3bcf11a` +* Actions: + * Use an OS-provided function pointer (pointer at the beginning of the= parameter buffer) to write the message + =E2=80=9CPRMN handler sample message!=E2=80=9D + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +### Module: PRM Sample ACPI Parameter Buffer +>* Name: `PrmSampleAcpiParameterBufferModule` +>* GUID: `dc2a58a6-5927-4776-b995-d118a27335a2` +> * Purpose: +> * Provides an example of how to configure an ACPI parameter buffer + +**Handlers:** +#### Handler: Check Parameter Buffer PRM Handler +* Name: `CheckParamBufferPrmHandler` +* GUID: `2e4f2d13-6240-4ed0-a401-c723fbdc34e8` +* Actions: + * Checks for the data signature =E2=80=98T=E2=80=99, =E2=80=98E=E2=80=99= , =E2=80=98S=E2=80=99, =E2=80=98T=E2=80=99 (DWORD) at the beginning of th= e parameter buffer. + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + * A data signature of ['T', 'E', 'S', 'T'] (DWORD) at the beginning of= the buffer. + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +### Module: PRM Sample Context Buffer +>* Name: `PrmSampleContextBufferModule` +>* GUID: `5a6cf42b-8bb4-472c-a233-5c4dc4033dc7` +> * Purpose: +> * Provides an example of how to configure a static data buffer (whic= h is pointed to in a context buffer) in + firmware and consume the buffer contents at runtime + +**Handlers:** +#### Handler: Check Static Data Buffer PRM Handler +* Name: `CheckStaticDataBufferPrmHandler` +* GUID: `e1466081-7562-430f-896b-b0e523dc335a` +* Actions: + * Checks that the context buffer signature and static data buffer sign= ature match in the context buffer provided. + +* Parameter Buffer Required: No + +* Context Buffer Required: Yes + * Static Data Buffer Contents: + ```c + #define SOME_VALUE_ARRAY_MAX_VALUES 16 + + typedef struct { + BOOLEAN Policy1Enabled; + BOOLEAN Policy2Enabled; + UINT8 SomeValueArray[SOME_VALUE_ARRAY_MAX_VALUES]; + } STATIC_DATA_SAMPLE_CONTEXT_BUFFER_MODULE; + ``` + +* Runtime MMIO Range(s) Required: No + +### Module: PRM Sample Hardware Access Buffer +>* Name: `PrmSampleHardwareAccessModule` +>* GUID: `0ef93ed7-14ae-425b-928f-b85a6213b57e` +> * Purpose: +> * Demonstrate access of several types of hardware resources from a P= RM module + +**Handlers:** +#### Handler: MSR Access Microcode Signature PRM Handler +* Name: `MsrAccessMicrocodeSignaturePrmHandler` +* GUID: `2120cd3c-848b-4d8f-abbb-4b74ce64ac89` +* Actions: + * Access the loaded microcode signature at MSR 0x8B. + +* Parameter Buffer Required: No + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: MSR Access MTRR Dump PRM Handler +* Name: `MsrAccessMtrrDumpPrmHandler` +* GUID: `ea0935a7-506b-4159-bbbb-48deeecb6f58` +* Actions: + * Access the fixed and variable MTRR values using MSRs. + +* Parameter Buffer Required: No + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: HPET MMIO Access PRM Handler +* Name: `MmioAccessHpetPrmHandler` +* GUID: `1bd1bda9-909a-4614-9699-25ec0c2783f7` +* Actions: + * Access some HPET registers using MMIO at 0xFED00000. + +* Parameter Buffer Required: No + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: Yes + * Physical Base Address: 0xFED00000 + * Length: 0x1000 + +#### Handler: MSR Print Microcode Signature PRM Handler +* Name: `MsrPrintMicrocodeSignaturePrmHandler` +* GUID: `5d28b4e7-3867-4aee-aa09-51fc282c3b22` +* Actions: + * Use the provided print function to print the loaded microcode signat= ure at MSR 0x8B. + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: MSR Print MTRR Dump PRM Handler +* Name: `MsrPrintMtrrDumpPrmHandler` +* GUID: `4b64b702-4d2b-4dfe-ac5a-0b4110a2ca47` +* Actions: + * Use the provided print function to print the fixed and variable MTRR= values using MSRs. + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: No + +#### Handler: HPET MMIO Print PRM Handler +* Name: `MmioPrintHpetPrmHandler` +* GUID: `8a0efdde-78d0-45f0-aea0-c28245c7e1db` +* Actions: + * Use the provided print function to print some HPET registers using M= MIO at 0xFED00000. + +* Parameter Buffer Required: Yes +* Parameter Buffer Contents: + ```c + typedef struct { + + PRM_OS_SERVICE_DEBUG_PRINT * + + } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER; + ``` + +* Context Buffer Required: No + +* Runtime MMIO Range(s) Required: Yes + * Physical Base Address: 0xFED00000 + * Length: 0x1000 --=20 2.28.0.windows.1