PrmPkg/Samples/Readme.md

   1 # **Platform Runtime Mechanism Sample Modules**
   2
   3 The PRM module samples provided here serve as focused examples of how to perform various tasks in a PRM module. The
   4 samples can also be used to verify the basic infrastructure needed in your firmware implementation is working as
   5 expected by checking that the sample modules are found properly and the handlers perform their tasks as noted.
   6
   7 ## **IMPORTANT NOTE**
   8
   9 > The sample modules have currently only been tested on the Visual Studio compiler tool chain. Sample module
  10 build may fail on other tool chains. A future work item is to enable broader build support.
  11
  12 ## How to Build PRM Sample Modules
  13
  14 The sample modules are built as part of the normal `PrmPkg` build so you can follow the
  15 [package build instructions](../../Readme.md#how-to-build-prmpkg) and then find the PRM sample binaries in your
  16 workspace build output directory. For example, if your build workspace is called "edk2" and you build
  17 64-bit binaries on the Visual Studio 2017 tool chain, your sample module binaries will be in the following
  18 location: \
  19 ``edk2/Build/Prm/DEBUG_VS2017/X64/PrmPkg/Samples``
  20
  21 ### Build an Individual PRM Sample Module
  22
  23 Note that the build command does provide the option to build a specific module in a package which can result in
  24 faster build time. If you would like to just build a single PRM module that can be done by specifying the path to
  25 the module INF file with the "-m" argument to `build`. For example, this command builds 32-bit and 64-bit binaries
  26 with Visual Studio 2019: \
  27 ``build -p PrmPkg/PrmPkg.dsc -m PrmPkg/Samples/PrmSampleContextBufferModule/PrmSampleContextBufferModule.inf -a IA32 -a X64 -t VS2019``
  28
  29 ## PRM Sample Module User's Guide
  30
  31 The following table provides an overview of each sample module provided. By nature, different PRM handlers have
  32 different requirements. The information here is summarized for a user to understand how to use a given sample
  33 PRM handler along with GUID/name information to identify the sample PRM modules and their PRM handlers.
  34
  35 It is recommended that all PRM authors write a similar set of documentation for their users to better understand
  36 and interact with their PRM modules.
  37
  38 ---
  39
  40 ### Module: PRM Sample ACPI Parameter Buffer
  41
  42 >* Name: `PrmSampleAcpiParameterBufferModule`
  43 >* GUID: `dc2a58a6-5927-4776-b995-d118a27335a2`
  44 > * Purpose:
  45 >   * Provides an example of how to configure an ACPI parameter buffer
  46
  47 **Handlers:**
  48
  49 #### Handler: Check Parameter Buffer PRM Handler
  50
  51 * Name: `CheckParamBufferPrmHandler`
  52 * GUID: `2e4f2d13-6240-4ed0-a401-c723fbdc34e8`
  53 * Actions:
  54   * Checks for the data signature ‘T’, ‘E’, ‘S’, ‘T’ (DWORD) at the beginning of the parameter buffer.
  55
  56 * Parameter Buffer Required: Yes
  57 * Parameter Buffer Contents:
  58   * A data signature of ['T', 'E', 'S', 'T'] (DWORD) at the beginning of the buffer.
  59
  60 * Context Buffer Required: No
  61
  62 * Runtime MMIO Range(s) Required: No
  63
  64 ### Module: PRM Sample Context Buffer
  65
  66 >* Name: `PrmSampleContextBufferModule`
  67 >* GUID: `5a6cf42b-8bb4-472c-a233-5c4dc4033dc7`
  68 > * Purpose:
  69 >   * Provides an example of how to configure a static data buffer (which is pointed to in a context buffer) in
  70       firmware and consume the buffer contents at runtime
  71
  72 **Handlers:**
  73
  74 #### Handler: Check Static Data Buffer PRM Handler
  75
  76 * Name: `CheckStaticDataBufferPrmHandler`
  77 * GUID: `e1466081-7562-430f-896b-b0e523dc335a`
  78 * Actions:
  79   * Checks that the context buffer signature and static data buffer signature match in the context buffer provided.
  80
  81 * Parameter Buffer Required: No
  82
  83 * Context Buffer Required: Yes
  84   * Static Data Buffer Contents:
  85
  86   ```c
  87   #define   SOME_VALUE_ARRAY_MAX_VALUES   16
  88
  89   typedef struct {
  90     BOOLEAN       Policy1Enabled;
  91     BOOLEAN       Policy2Enabled;
  92     UINT8         SomeValueArray[SOME_VALUE_ARRAY_MAX_VALUES];
  93   } STATIC_DATA_SAMPLE_CONTEXT_BUFFER_MODULE;
  94   ```
  95
  96 * Runtime MMIO Range(s) Required: No
  97
  98 ### Module: PRM Sample Hardware Access Buffer
  99
 100 >* Name: `PrmSampleHardwareAccessModule`
 101 >* GUID: `0ef93ed7-14ae-425b-928f-b85a6213b57e`
 102 > * Purpose:
 103 >   * Demonstrate access of several types of hardware resources from a PRM module
 104
 105 **Handlers:**
 106
 107 #### Handler: MSR Access Microcode Signature PRM Handler
 108
 109 * Name: `MsrAccessMicrocodeSignaturePrmHandler`
 110 * GUID: `2120cd3c-848b-4d8f-abbb-4b74ce64ac89`
 111 * Actions:
 112   * Access the loaded microcode signature at MSR 0x8B.
 113
 114 * Parameter Buffer Required: No
 115
 116 * Context Buffer Required: No
 117
 118 * Runtime MMIO Range(s) Required: No
 119
 120 #### Handler: MSR Access MTRR Dump PRM Handler
 121
 122 * Name: `MsrAccessMtrrDumpPrmHandler`
 123 * GUID: `ea0935a7-506b-4159-bbbb-48deeecb6f58`
 124 * Actions:
 125   * Access the fixed and variable MTRR values using MSRs.
 126
 127 * Parameter Buffer Required: No
 128
 129 * Context Buffer Required: No
 130
 131 * Runtime MMIO Range(s) Required: No
 132
 133 #### Handler: HPET MMIO Access PRM Handler
 134
 135 * Name: `MmioAccessHpetPrmHandler`
 136 * GUID: `1bd1bda9-909a-4614-9699-25ec0c2783f7`
 137 * Actions:
 138   * Access some HPET registers using MMIO at 0xFED00000.
 139
 140 * Parameter Buffer Required: No
 141
 142 * Context Buffer Required: No
 143
 144 * Runtime MMIO Range(s) Required: Yes
 145   * Physical Base Address: 0xFED00000
 146   * Length: 0x1000