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