mirror of https://github.com/acidanthera/audk.git
PrmPkg: Changes for edk2 repo transition
Updates the Readme.md files to remove information that was specific to the package in edk2-staging and adds key definitions being added for PRM support in the ACPI Specification. Adds PrmPkg/PrmPkg.ci.yaml to support CI. Adds PrmPkg to .pytool/CISettings.py. Adds PrmPkg maintainers to Maintainers.txt. Cc: Andrew Fish <afish@apple.com> Cc: Kang Gao <kang.gao@intel.com> Cc: Michael D Kinney <michael.d.kinney@intel.com> Cc: Michael Kubacki <michael.kubacki@microsoft.com> Cc: Leif Lindholm <leif@nuviainc.com> Cc: Benjamin You <benjamin.you@intel.com> Cc: Liu Yun <yun.y.liu@intel.com> Cc: Ankit Sinha <ankit.sinha@intel.com> Cc: Nate DeSimone <nathaniel.l.desimone@intel.com> Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com> Acked-by: Michael D Kinney <michael.d.kinney@intel.com> Acked-by: Liming Gao <gaoliming@byosoft.com.cn> Acked-by: Leif Lindholm <quic_llindhol@quicinc.com> Reviewed-by: Ankit Sinha <ankit.sinha@intel.com>
This commit is contained in:
Michael Kubacki
mergify[bot]
parent
deea4e58b0
commit
f3c11224b5
|
|
@ -37,7 +37,7 @@ jobs:
|
|||
Build.Pkgs: 'NetworkPkg,RedfishPkg'
|
||||
Build.Targets: 'DEBUG,RELEASE,NO-TARGET'
|
||||
TARGET_OTHER:
|
||||
Build.Pkgs: 'PcAtChipsetPkg,ShellPkg,StandaloneMmPkg'
|
||||
Build.Pkgs: 'PcAtChipsetPkg,PrmPkg,ShellPkg,StandaloneMmPkg'
|
||||
Build.Targets: 'DEBUG,RELEASE,NO-TARGET'
|
||||
TARGET_FMP_FAT_TEST:
|
||||
Build.Pkgs: 'FmpDevicePkg,FatPkg,UnitTestFrameworkPkg,DynamicTablesPkg'
|
||||
|
|
|
|||
|
|
@ -65,6 +65,7 @@ class Settings(CiBuildSettingsManager, UpdateSettingsManager, SetupSettingsManag
|
|||
"StandaloneMmPkg",
|
||||
"FatPkg",
|
||||
"CryptoPkg",
|
||||
"PrmPkg",
|
||||
"UnitTestFrameworkPkg",
|
||||
"OvmfPkg",
|
||||
"RedfishPkg",
|
||||
|
|
|
|||
|
|
@ -540,6 +540,14 @@ F: PcAtChipsetPkg/
|
|||
W: https://github.com/tianocore/tianocore.github.io/wiki/PcAtChipsetPkg
|
||||
M: Ray Ni <ray.ni@intel.com> [niruiyu]
|
||||
|
||||
PrmPkg
|
||||
F: PrmPkg/
|
||||
M: Michael Kubacki <mikuback@linux.microsoft.com> [makubacki]
|
||||
M: Nate DeSimone <nathaniel.l.desimone@intel.com> [nate-desimone]
|
||||
|
||||
PrmPkg: ACPI related modules
|
||||
R: Ankit Sinha <ankit.sinha@intel.com> [ankit13s]
|
||||
|
||||
RedfishPkg: Redfish related modules
|
||||
F: RedfishPkg/
|
||||
M: Abner Chang <abner.chang@hpe.com> [changab]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,110 @@
|
|||
## @file
|
||||
# CI configuration for PrmPkg
|
||||
#
|
||||
# Copyright (c) Microsoft Corporation<BR>
|
||||
# SPDX-License-Identifier: BSD-2-Clause-Patent
|
||||
##
|
||||
{
|
||||
## options defined .pytool/Plugin/LicenseCheck
|
||||
"LicenseCheck": {
|
||||
"IgnoreFiles": []
|
||||
},
|
||||
|
||||
"EccCheck": {
|
||||
## Exception sample looks like below:
|
||||
## "ExceptionList": [
|
||||
## "<ErrorID>", "<KeyWord>"
|
||||
## ]
|
||||
"ExceptionList": [
|
||||
"5001", "PRM_HANDLER_EXPORT",
|
||||
"8006", "PRM_HANDLER_EXPORT"
|
||||
],
|
||||
## Both file path and directory path are accepted.
|
||||
"IgnoreFiles": [
|
||||
"Library/DxePrmContextBufferLib/UnitTest",
|
||||
"Library/DxePrmModuleDiscoveryLib/UnitTest",
|
||||
"Samples",
|
||||
"Test"
|
||||
]
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/CompilerPlugin
|
||||
"CompilerPlugin": {
|
||||
"DscPath": "PrmPkg.dsc"
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/HostUnitTestCompilerPlugin
|
||||
"HostUnitTestCompilerPlugin": {
|
||||
"DscPath": "Test/PrmPkgHostTest.dsc"
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/CharEncodingCheck
|
||||
"CharEncodingCheck": {
|
||||
"IgnoreFiles": []
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/DependencyCheck
|
||||
"DependencyCheck": {
|
||||
"AcceptableDependencies": [
|
||||
"MdeModulePkg/MdeModulePkg.dec",
|
||||
"MdePkg/MdePkg.dec",
|
||||
"PrmPkg/PrmPkg.dec",
|
||||
"ShellPkg/ShellPkg.dec",
|
||||
"UefiCpuPkg/UefiCpuPkg.dec"
|
||||
],
|
||||
# For host based unit tests
|
||||
"AcceptableDependencies-HOST_APPLICATION":[
|
||||
"UnitTestFrameworkPkg/UnitTestFrameworkPkg.dec"
|
||||
],
|
||||
# For UEFI shell based apps
|
||||
"AcceptableDependencies-UEFI_APPLICATION":[],
|
||||
"IgnoreInf": []
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/DscCompleteCheck
|
||||
"DscCompleteCheck": {
|
||||
"IgnoreInf": [],
|
||||
"DscPath": "PrmPkg.dsc"
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/HostUnitTestDscCompleteCheck
|
||||
"HostUnitTestDscCompleteCheck": {
|
||||
"IgnoreInf": [""],
|
||||
"DscPath": "Test/PrmPkgHostTest.dsc"
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/GuidCheck
|
||||
"GuidCheck": {
|
||||
"IgnoreGuidName": [],
|
||||
"IgnoreGuidValue": [],
|
||||
"IgnoreFoldersAndFiles": [],
|
||||
"IgnoreDuplicates": [],
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/LibraryClassCheck
|
||||
"LibraryClassCheck": {
|
||||
"IgnoreHeaderFile": []
|
||||
},
|
||||
|
||||
## options defined .pytool/Plugin/SpellCheck
|
||||
"SpellCheck": {
|
||||
"AuditOnly": False,
|
||||
"IgnoreFiles": [], # use gitignore syntax to ignore errors
|
||||
# in matching files
|
||||
"ExtendWords": [ # words to extend to the dictionary for this package
|
||||
"buffe", # note: appears in buffer ascii dump in documentation
|
||||
"iptor", # note: appears in buffer ascii dump in documentation
|
||||
"keepoptionalheader",
|
||||
"odule", # note: appears in buffer ascii dump in documentation
|
||||
"oemid",
|
||||
"prmopreg",
|
||||
"prmpecofflib",
|
||||
"prmpkg",
|
||||
"prmssdtinstall"
|
||||
],
|
||||
"IgnoreStandardPaths": [], # Standard Plugin defined paths that
|
||||
# should be ignore
|
||||
"AdditionalIncludePaths": [] # Additional paths to spell check
|
||||
# (wildcards supported)
|
||||
}
|
||||
}
|
||||
129
PrmPkg/Readme.md
129
PrmPkg/Readme.md
|
|
@ -10,15 +10,6 @@ For more details on PRM, refer to the [Platform Runtime Mechanism Specification
|
|||
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 of this feature is shared in the edk2-staging
|
||||
branch to simplify collaboration by allowing direct code contributions and early feedback throughout its development.
|
||||
|
||||
> **Use recent edk2/master** - This code makes use of a very recent change in edk2 BaseTools. Specifically, commit
|
||||
[b65afdd](https://github.com/tianocore/edk2/commit/b65afdde74d6c1fac1cdbd2efdad23ba26295808). Ensure you have that
|
||||
change to build the code in this repo as-is.
|
||||
|
||||
> By default, the build makes use of a new ACPI OperationRegion type specifically introduced for PRM called
|
||||
`PlatformRtMechanism`. Support for this OperationRegion is planned for the next release of the ACPI specification.
|
||||
However, support for `PlatformRtMechanism` is already included in the iASL Compiler/Disassembler for early prototyping
|
||||
|
|
@ -27,7 +18,13 @@ through ACPI, iASL compiler [20200528](https://acpica.org/node/181) or greater m
|
|||
interested in compiling the code and/or using direct call style PRM handlers, you can simply remove
|
||||
`PrmSsdtInstallDxe` from `PrmPkg.dsc`.
|
||||
|
||||
The changes in the ACPI Specification include two elements:
|
||||
|
||||
1. `BIT20` in Platform-Wide _OSC Capabilities DWORD2 will be used by an OS to indicate support for PRM
|
||||
2. A new Operation Region Address Space Identifier Value is defined as `0xB` for `PlatformRtMechanism`
|
||||
|
||||
## 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 `PrmConfigDxe` and `PrmLoaderDxe` drivers to its DSC and
|
||||
FDF files so they are built in the platform firmware build and dispatched during its runtime. All that is left is to
|
||||
|
|
@ -35,26 +32,18 @@ add individual PRM modules to the DSC and FDF. These can be built from source or
|
|||
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, to 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 repository locally \
|
||||
``git clone -b PlatformRuntimeMechanism --single-branch https://github.com/tianocore/edk2-staging.git``
|
||||
> __*Note*__: The *--single-branch* argument is recommended since edk2-staging hosts many branches for completely
|
||||
unrelated features. If you are just interested in PRM, this will avoid fetching all of the other branches.
|
||||
|
||||
4. Change to the edk2 workspace directory \
|
||||
3. Change to the edk2 workspace directory \
|
||||
``cd edk2``
|
||||
|
||||
5. Run *edksetup* to set local environment variables needed for build
|
||||
4. Run *edksetup* to set local environment variables needed for build
|
||||
* Windows:
|
||||
* ``edksetup.bat``
|
||||
* Linux:
|
||||
|
|
@ -62,52 +51,22 @@ To build `PrmPkg` as a standalone package:
|
|||
* ``make -C BaseTools``
|
||||
* ``. edksetup.sh``
|
||||
|
||||
6. Set the PACKAGES_PATH environment variable to include the directory path that contains `PrmPkg`
|
||||
* Windows example:
|
||||
* ``set PACKAGES_PATH=c:\src\edk2-staging``
|
||||
|
||||
7. Change to the edk2-staging workspace directory
|
||||
* Example: ``cd ../edk2-staging``
|
||||
|
||||
8. Build PrmPkg \
|
||||
5. 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**.
|
||||
> ***Note***: Due to the way PRM modules are compiled with exports, **only building on Visual Studio compiler tool
|
||||
chains has been tested**.
|
||||
|
||||
In the future, each new terminal session can start at step #4. Within a terminal session, start at step #8.
|
||||
|
||||
> __*Note*__: \
|
||||
> ***Note***: \
|
||||
> This package has been used without modification in several environments including client, server,
|
||||
> and virtual systems.
|
||||
>
|
||||
> A functional example of how to integrate this code into a platform is available here:
|
||||
> https://github.com/makubacki/edk2/tree/sample_ovmfpkg_prmpkg_integration
|
||||
>
|
||||
> That build will load the drivers and PRM sample modules provided in this package in the open source emulator
|
||||
> [QEMU](https://www.qemu.org/) by including it in the [`OvmfPkg`](https://github.com/tianocore/edk2/tree/master/OvmfPkg) build.
|
||||
>
|
||||
> You can add your own PRM modules into the build and check them with the `PrmInfo` UEFI application described
|
||||
> later in this document and dump the PRMT table in the OS to check if your PRM module is represented as expected.
|
||||
|
||||
### Build Flags
|
||||
As PRM is a new feature at a proof-of-concept (POC) level of maturity, there's some changes to the normal build
|
||||
available as build flags. By default, if no flags are specified, the build is done with the currently expected plan of
|
||||
record (POR) configuration.
|
||||
|
||||
The following list are the currently defined build flags (if any) that may be passed to the `build` command
|
||||
(e.g. -D FLAG=VALUE).
|
||||
|
||||
* NONE - No build flags are currently used.
|
||||
|
||||
Additional detail: The context buffer structure is defined in [PrmContextBuffer.h](PrmPkg/Include/PrmContextBuffer.h).
|
||||
This structure is passed as the context buffer to PRM handlers. The structure actually passed to PRM handlers is
|
||||
allocated and populated by the OS where it gets all the information to populate the context buffer from other structures.
|
||||
|
||||
### PRM Platform GUID
|
||||
**IMPORTANT**
|
||||
|
||||
PRM has a concept of a "Platform GUID" which associates a specific platform with a set of PRM modules built for
|
||||
that platform. This GUID is used to ensure system compatibility for a given collection of PRM modules.
|
||||
**IMPORTANT** PRM has a concept of a "Platform GUID" which associates a specific platform with a set of PRM modules
|
||||
built for that platform. This GUID is used to ensure system compatibility for a given collection of PRM modules.
|
||||
|
||||
Therefore, each PRM module must only target a single platform and each platform must have a unique GUID. Even if a
|
||||
PRM module is unchanged between two different platforms now, there is no guarantee that will remain the case so always
|
||||
|
|
@ -122,20 +81,30 @@ supported in the future if needed.
|
|||
In the `PrmPkg` implementation, the Platform GUID is automatically derived from the PLATFORM_GUID in the DSC file of
|
||||
the package being built.
|
||||
|
||||
### Build Output
|
||||
|
||||
Like a typical EDK II package, the PrmPkg binary build output can be found in the Build directory in the edk2
|
||||
workspace. The organization in that directory follows the same layout as other EDK II packages.
|
||||
|
||||
For example, that path to PRM module sample binaries for a DEBUG VS2017 X64 build is: \
|
||||
``edk2/Build/Prm/DEBUG_VS2017/X64/PrmPkg/Samples``
|
||||
|
||||
## 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
|
||||
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
|
||||
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 IHV PRM code, each of which can be serviced
|
||||
independently.
|
||||
3. PRM handler - The implementation/callback of a single PRM functionality as identified by a GUID.
|
||||
3. `PRM handler` - The implementation/callback of a single PRM functionality 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. A `PRM Loader driver` - Functionality is split across three phases:
|
||||
1. Discover - Find all PRM modules in the firmware image made available by the platform firmware author.
|
||||
* This phase includes verifying authenticity/integrity of the image, the image executable type, the export
|
||||
table is present and the PRM Export Module Descriptor is present and valid.
|
||||
|
|
@ -143,15 +112,16 @@ The firmware has three key generic drivers to support PRM:
|
|||
to physical address mappings required to construct the PRM ACPI table.
|
||||
3. Publish - Publish the PRM ACPI table using the information from the Process phase.
|
||||
|
||||
2. A PRM Configuration driver - A generic driver responsible for processing PRM module configuration information
|
||||
2. A `PRM Configuration driver` - A generic driver responsible for processing PRM module configuration information
|
||||
consumed through a `PRM_CONFIG_PROTOCOL` per PRM module instance. Therefore, the `PRM_CONFIG_PROTOCOL` serves
|
||||
as the dynamic interface for this driver to process PRM module resources 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 that follows the PRM module authoring process.
|
||||
3. A `PRM Module` - Not a single driver but a user written PE/COFF image that 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 below contains some notable areas to
|
||||
explore in the package:
|
||||
|
||||
|
|
@ -167,12 +137,14 @@ that infrastructure. The PrmPkg is meant to be used as-is by firmware that suppo
|
|||
prevent the package from being used as-is should be addressed directly in PrmPkg.
|
||||
|
||||
## PRM Information UEFI Application
|
||||
A UEFI application is provided in this package called "PrmInfo" that allows a user to display and test PRM
|
||||
|
||||
A UEFI application is provided in this package called `PrmInfo` that allows a user to display and test PRM
|
||||
modules on their system.
|
||||
|
||||
[Link to application source code](PrmPkg/Application/PrmInfo).
|
||||
|
||||
This application is intended to be helpful during PRM enabling by allowing the user to:
|
||||
|
||||
1. Confirm that their firmware port of the PRM infrastructure implemented in this package is functioning correctly.
|
||||
2. Quickly get information about what PRM modules and handlers that are present on a given system.
|
||||
3. Quickly test PRM handlers without booting into a full operating system.
|
||||
|
|
@ -183,32 +155,32 @@ Execute the application help command for detailed usage instructions and example
|
|||
|
||||
*Example Usage:*
|
||||
|
||||
|
||||
|
||||
|
||||
## PRM Module
|
||||
|
||||
> __*Note*__: You can find simple examples of PRM modules in the Samples directory of this package.
|
||||
> ***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.
|
||||
`IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER` to be built with exports.
|
||||
|
||||
```
|
||||
```txt
|
||||
ERROR - Linker #1294 from LINK : fatal exports and import libraries are not supported with /SUBSYSTEM:EFI_RUNTIME_DRIVER
|
||||
```
|
||||
|
||||
This can adjusted in the MSVC linker options.
|
||||
|
||||
__For the purposes of this POC__, the subsystem type is changed in the firmware build to allow the export table to be
|
||||
added but the subsystem type in the final image is still 0xC (EFI Runtime 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.
|
||||
The subsystem type is changed in the firmware build to allow the export table to be added but the subsystem type in the
|
||||
final image is still `0xC` (`EFI Runtime 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
|
||||
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 UEFI Runtime Services, notably 4KiB or more of
|
||||
available stack space must be provided and the stack must be 16-byte aligned.
|
||||
available stack space must be provided and the stack must be 16-byte aligned.
|
||||
|
||||
__*Note:*__ Long term it is possible to similarly load the modules into a EfiRuntimeServicesCode buffer and perform
|
||||
***Note:*** Long 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.
|
||||
|
||||
|
|
@ -217,10 +189,11 @@ motivation behind using PE/COFF export tables to expose PRM module information a
|
|||
definition consistent between firmware and OS load.
|
||||
|
||||
### PRM Module Exports
|
||||
|
||||
A PRM module must contain at least two exports: A PRM Module Export 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:
|
||||
|
||||
```
|
||||
```txt
|
||||
0000000000005000: 00 00 00 00 FF FF FF FF 00 00 00 00 3C 50 00 00 ............<P..
|
||||
0000000000005010: 01 00 00 00 02 00 00 00 02 00 00 00 28 50 00 00 ............(P..
|
||||
0000000000005020: 30 50 00 00 38 50 00 00 78 13 00 00 20 40 00 00 0P..8P..x... @..
|
||||
|
|
@ -245,7 +218,9 @@ an example of an export table from a PRM module that has a single PRM handler:
|
|||
2 1 00004020 PrmModuleExportDescriptor
|
||||
|
||||
```
|
||||
|
||||
### PRM Image Format
|
||||
|
||||
PRM modules are ultimately PE/COFF images. However, when packaged in firmware the PE/COFF image is placed into a
|
||||
Firmware File System (FFS) file. This is transparent to the operating system 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 shown earlier,
|
||||
|
|
@ -255,11 +230,12 @@ during the firmware build process. In either case, the PE/COFF section is contai
|
|||
image.
|
||||
|
||||
### PRM Module Implementation
|
||||
|
||||
To simplify building the PRM Module Export Descriptor, a PRM module implementation 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.
|
||||
|
||||
```
|
||||
```c
|
||||
//
|
||||
// Register the PRM export information for this PRM Module
|
||||
//
|
||||
|
|
@ -280,6 +256,7 @@ all the includes needed to author a PRM module. This export is `PRM_MODULE_UPDAT
|
|||
`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 violation at build-time.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,10 +5,12 @@ samples can also be used to verify the basic infrastructure needed in your firmw
|
|||
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 Studio compiler tool chain. Sample module
|
||||
build may fail on other tool chains. A future work item is to enable broader 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 then find the PRM sample binaries in your
|
||||
workspace build output directory. For example, if your build workspace is called "edk2" and you build
|
||||
|
|
@ -17,6 +19,7 @@ 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 that 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
|
||||
|
|
@ -33,14 +36,18 @@ It is recommended that all PRM authors write a similar set of documentation for
|
|||
and interact with their PRM modules.
|
||||
|
||||
---
|
||||
|
||||
### 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:
|
||||
|
|
@ -55,6 +62,7 @@ and interact with their PRM modules.
|
|||
* Runtime MMIO Range(s) Required: No
|
||||
|
||||
### Module: PRM Sample Context Buffer
|
||||
|
||||
>* Name: `PrmSampleContextBufferModule`
|
||||
>* GUID: `5a6cf42b-8bb4-472c-a233-5c4dc4033dc7`
|
||||
> * Purpose:
|
||||
|
|
@ -62,7 +70,9 @@ and interact with their PRM modules.
|
|||
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:
|
||||
|
|
@ -72,6 +82,7 @@ and interact with their PRM modules.
|
|||
|
||||
* Context Buffer Required: Yes
|
||||
* Static Data Buffer Contents:
|
||||
|
||||
```c
|
||||
#define SOME_VALUE_ARRAY_MAX_VALUES 16
|
||||
|
||||
|
|
@ -85,13 +96,16 @@ and interact with their PRM modules.
|
|||
* 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 PRM module
|
||||
|
||||
**Handlers:**
|
||||
|
||||
#### Handler: MSR Access Microcode Signature PRM Handler
|
||||
|
||||
* Name: `MsrAccessMicrocodeSignaturePrmHandler`
|
||||
* GUID: `2120cd3c-848b-4d8f-abbb-4b74ce64ac89`
|
||||
* Actions:
|
||||
|
|
@ -104,6 +118,7 @@ and interact with their PRM modules.
|
|||
* Runtime MMIO Range(s) Required: No
|
||||
|
||||
#### Handler: MSR Access MTRR Dump PRM Handler
|
||||
|
||||
* Name: `MsrAccessMtrrDumpPrmHandler`
|
||||
* GUID: `ea0935a7-506b-4159-bbbb-48deeecb6f58`
|
||||
* Actions:
|
||||
|
|
@ -116,6 +131,7 @@ and interact with their PRM modules.
|
|||
* Runtime MMIO Range(s) Required: No
|
||||
|
||||
#### Handler: HPET MMIO Access PRM Handler
|
||||
|
||||
* Name: `MmioAccessHpetPrmHandler`
|
||||
* GUID: `1bd1bda9-909a-4614-9699-25ec0c2783f7`
|
||||
* Actions:
|
||||
|
|
|
|||
Loading…
Reference in New Issue