--- /dev/null
+# **Platform Runtime Mechanism Sample Modules**\r
+\r
+The PRM module samples provided here serve as focused examples of how to perform various tasks in a PRM module. The\r
+samples can also be used to verify the basic infrastructure needed in your firmware implementation is working as\r
+expected by checking that the sample modules are found properly and the handlers perform their tasks as noted.\r
+\r
+## **IMPORTANT NOTE**\r
+> The sample modules have currently only been tested on the Visual Studio compiler tool chain. Sample module\r
+build may fail on other tool chains. A future work item is to enable broader build support.\r
+\r
+## How to Build PRM Sample Modules\r
+The sample modules are built as part of the normal `PrmPkg` build so you can follow the\r
+[package build instructions](../../Readme.md#how-to-build-prmpkg) and then find the PRM sample binaries in your\r
+workspace build output directory. For example, if your build workspace is called "edk2" and you build\r
+64-bit binaries on the Visual Studio 2017 tool chain, your sample module binaries will be in the following\r
+location: \\r
+``edk2/Build/Prm/DEBUG_VS2017/X64/PrmPkg/Samples``\r
+\r
+### Build an Individual PRM Sample Module\r
+Note that the build command does provide the option to build a specific module in a package which can result in\r
+faster build time. If you would like to just build a single PRM module that can be done by specifying the path to\r
+the module INF file with the "-m" argument to `build`. For example, this command builds 32-bit and 64-bit binaries\r
+with Visual Studio 2019: \\r
+``build -p PrmPkg/PrmPkg.dsc -m PrmPkg/Samples/PrmSamplePrintModule/PrmSamplePrintModule.inf -a IA32 -a X64 -t VS2019``\r
+\r
+## PRM Sample Module User's Guide\r
+\r
+The following table provides an overview of each sample module provided. By nature, different PRM handlers have\r
+different requirements. The information here is summarized for a user to understand how to use a given sample\r
+PRM handler along with GUID/name information to identify the sample PRM modules and their PRM handlers.\r
+\r
+It is recommended that all PRM authors write a similar set of documentation for their users to better understand\r
+and interact with their PRM modules.\r
+\r
+---\r
+### Module: PRM Sample Print Module\r
+>* Name: `PrmSamplePrintModule`\r
+>* GUID: `1652b3c2-a7a1-46ac-af93-dd6dee446669`\r
+> * Purpose:\r
+> * Simplest PRM module example\r
+> * Example of a PRM module with multiple PRM handlers\r
+\r
+**Handlers:**\r
+#### Handler: PRM Handler 1\r
+* Name: `PrmHandler1`\r
+* GUID: `d5f2ad5f-a347-4d3e-87bc-c2ce63029cc8`\r
+* Actions:\r
+ * Use an OS-provided function pointer (pointer at the beginning of the parameter buffer) to write the message\r
+ “PRM1 handler sample message!”\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: PRM Handler 2\r
+* Name: `PrmHandler2`\r
+* GUID: `a9e7adc3-8cd0-429a-8915-10946ebde318`\r
+* Actions:\r
+ * Use an OS-provided function pointer (pointer at the beginning of the parameter buffer) to write the message\r
+ “PRM2 handler sample message!”\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: PRM Handler N\r
+* Name: `PrmHandlerN`\r
+* GUID: `b688c214-4081-4eeb-8d26-1eb5a3bcf11a`\r
+* Actions:\r
+ * Use an OS-provided function pointer (pointer at the beginning of the parameter buffer) to write the message\r
+ “PRMN handler sample message!”\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+### Module: PRM Sample ACPI Parameter Buffer\r
+>* Name: `PrmSampleAcpiParameterBufferModule`\r
+>* GUID: `dc2a58a6-5927-4776-b995-d118a27335a2`\r
+> * Purpose:\r
+> * Provides an example of how to configure an ACPI parameter buffer\r
+\r
+**Handlers:**\r
+#### Handler: Check Parameter Buffer PRM Handler\r
+* Name: `CheckParamBufferPrmHandler`\r
+* GUID: `2e4f2d13-6240-4ed0-a401-c723fbdc34e8`\r
+* Actions:\r
+ * Checks for the data signature ‘T’, ‘E’, ‘S’, ‘T’ (DWORD) at the beginning of the parameter buffer.\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ * A data signature of ['T', 'E', 'S', 'T'] (DWORD) at the beginning of the buffer.\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+### Module: PRM Sample Context Buffer\r
+>* Name: `PrmSampleContextBufferModule`\r
+>* GUID: `5a6cf42b-8bb4-472c-a233-5c4dc4033dc7`\r
+> * Purpose:\r
+> * Provides an example of how to configure a static data buffer (which is pointed to in a context buffer) in\r
+ firmware and consume the buffer contents at runtime\r
+\r
+**Handlers:**\r
+#### Handler: Check Static Data Buffer PRM Handler\r
+* Name: `CheckStaticDataBufferPrmHandler`\r
+* GUID: `e1466081-7562-430f-896b-b0e523dc335a`\r
+* Actions:\r
+ * Checks that the context buffer signature and static data buffer signature match in the context buffer provided.\r
+\r
+* Parameter Buffer Required: No\r
+\r
+* Context Buffer Required: Yes\r
+ * Static Data Buffer Contents:\r
+ ```c\r
+ #define SOME_VALUE_ARRAY_MAX_VALUES 16\r
+\r
+ typedef struct {\r
+ BOOLEAN Policy1Enabled;\r
+ BOOLEAN Policy2Enabled;\r
+ UINT8 SomeValueArray[SOME_VALUE_ARRAY_MAX_VALUES];\r
+ } STATIC_DATA_SAMPLE_CONTEXT_BUFFER_MODULE;\r
+ ```\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+### Module: PRM Sample Hardware Access Buffer\r
+>* Name: `PrmSampleHardwareAccessModule`\r
+>* GUID: `0ef93ed7-14ae-425b-928f-b85a6213b57e`\r
+> * Purpose:\r
+> * Demonstrate access of several types of hardware resources from a PRM module\r
+\r
+**Handlers:**\r
+#### Handler: MSR Access Microcode Signature PRM Handler\r
+* Name: `MsrAccessMicrocodeSignaturePrmHandler`\r
+* GUID: `2120cd3c-848b-4d8f-abbb-4b74ce64ac89`\r
+* Actions:\r
+ * Access the loaded microcode signature at MSR 0x8B.\r
+\r
+* Parameter Buffer Required: No\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: MSR Access MTRR Dump PRM Handler\r
+* Name: `MsrAccessMtrrDumpPrmHandler`\r
+* GUID: `ea0935a7-506b-4159-bbbb-48deeecb6f58`\r
+* Actions:\r
+ * Access the fixed and variable MTRR values using MSRs.\r
+\r
+* Parameter Buffer Required: No\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: HPET MMIO Access PRM Handler\r
+* Name: `MmioAccessHpetPrmHandler`\r
+* GUID: `1bd1bda9-909a-4614-9699-25ec0c2783f7`\r
+* Actions:\r
+ * Access some HPET registers using MMIO at 0xFED00000.\r
+\r
+* Parameter Buffer Required: No\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: Yes\r
+ * Physical Base Address: 0xFED00000\r
+ * Length: 0x1000\r
+\r
+#### Handler: MSR Print Microcode Signature PRM Handler\r
+* Name: `MsrPrintMicrocodeSignaturePrmHandler`\r
+* GUID: `5d28b4e7-3867-4aee-aa09-51fc282c3b22`\r
+* Actions:\r
+ * Use the provided print function to print the loaded microcode signature at MSR 0x8B.\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: MSR Print MTRR Dump PRM Handler\r
+* Name: `MsrPrintMtrrDumpPrmHandler`\r
+* GUID: `4b64b702-4d2b-4dfe-ac5a-0b4110a2ca47`\r
+* Actions:\r
+ * Use the provided print function to print the fixed and variable MTRR values using MSRs.\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: No\r
+\r
+#### Handler: HPET MMIO Print PRM Handler\r
+* Name: `MmioPrintHpetPrmHandler`\r
+* GUID: `8a0efdde-78d0-45f0-aea0-c28245c7e1db`\r
+* Actions:\r
+ * Use the provided print function to print some HPET registers using MMIO at 0xFED00000.\r
+\r
+* Parameter Buffer Required: Yes\r
+* Parameter Buffer Contents:\r
+ ```c\r
+ typedef struct {\r
+\r
+ PRM_OS_SERVICE_DEBUG_PRINT *\r
+\r
+ } SAMPLE_OSDEBUGPRINT_PARAMETER_BUFFER;\r
+ ```\r
+\r
+* Context Buffer Required: No\r
+\r
+* Runtime MMIO Range(s) Required: Yes\r
+ * Physical Base Address: 0xFED00000\r
+ * Length: 0x1000\r