PrmPkg/SampleAcpiParameterBufferModule: Add initial module

Adds a new PRM module called SampleAcpiParameterBufferModule that
demonstrates how a PRM module can use an ACPI parameter buffer with
a PRM handler.

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>

PrmPkg/PrmPkg.dsc

@@ -68,6 +68,7 @@
   # PRM Libraries
   #
   $(PLATFORM_PACKAGE)/Library/DxePrmContextBufferLib/DxePrmContextBufferLib.inf
+  $(PLATFORM_PACKAGE)/Samples/PrmSampleAcpiParameterBufferModule/Library/DxeAcpiParameterBufferModuleConfigLib/DxeAcpiParameterBufferModuleConfigLib.inf
   $(PLATFORM_PACKAGE)/Samples/PrmSampleContextBufferModule/Library/DxeContextBufferModuleConfigLib/DxeContextBufferModuleConfigLib.inf
   $(PLATFORM_PACKAGE)/Samples/PrmSampleHardwareAccessModule/Library/DxeHardwareAccessModuleConfigLib/DxeHardwareAccessModuleConfigLib.inf
 
@@ -76,6 +77,7 @@
   #
   $(PLATFORM_PACKAGE)/PrmConfigDxe/PrmConfigDxe.inf {
     <LibraryClasses>
+      NULL|$(PLATFORM_PACKAGE)/Samples/PrmSampleAcpiParameterBufferModule/Library/DxeAcpiParameterBufferModuleConfigLib/DxeAcpiParameterBufferModuleConfigLib.inf
       NULL|$(PLATFORM_PACKAGE)/Samples/PrmSampleContextBufferModule/Library/DxeContextBufferModuleConfigLib/DxeContextBufferModuleConfigLib.inf
   }
 
@@ -93,6 +95,7 @@
   # PRM Sample Modules
   #
   $(PLATFORM_PACKAGE)/Samples/PrmSamplePrintModule/PrmSamplePrintModule.inf
+  $(PLATFORM_PACKAGE)/Samples/PrmSampleAcpiParameterBufferModule/PrmSampleAcpiParameterBufferModule.inf
   $(PLATFORM_PACKAGE)/Samples/PrmSampleHardwareAccessModule/PrmSampleHardwareAccessModule.inf {
     <LibraryClasses>
       DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf

PrmPkg/Samples/PrmSampleAcpiParameterBufferModule/Library/DxeAcpiParameterBufferModuleConfigLib/DxeAcpiParameterBufferModuleConfigLib.c

@@ -0,0 +1,120 @@
+/** @file
+
+  The boot services environment configuration library for the ACPI Parameter Buffer Sample PRM module.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Library/BaseLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
+#include <Library/UefiBootServicesTableLib.h>
+#include <Protocol/PrmConfig.h>
+
+STATIC EFI_HANDLE  mPrmConfigProtocolHandle;
+
+// {dc2a58a6-5927-4776-b995-d118a27335a2}
+STATIC CONST EFI_GUID mPrmModuleGuid = {0xdc2a58a6, 0x5927, 0x4776, {0xb9, 0x95, 0xd1, 0x18, 0xa2, 0x73, 0x35, 0xa2}};
+
+// {2e4f2d13-6240-4ed0-a401-c723fbdc34e8}
+STATIC CONST EFI_GUID mCheckParamBufferPrmHandlerGuid = {0x2e4f2d13, 0x6240, 0x4ed0, {0xa4, 0x01, 0xc7, 0x23, 0xfb, 0xdc, 0x34, 0xe8}};
+
+/**
+  Constructor of the PRM configuration library.
+
+  @param[in] ImageHandle        The image handle of the driver.
+  @param[in] SystemTable        The EFI System Table pointer.
+
+  @retval EFI_SUCCESS           The shell command handlers were installed successfully.
+  @retval EFI_UNSUPPORTED       The shell level required was not found.
+**/
+EFI_STATUS
+EFIAPI
+AcpiParameterBufferModuleConfigLibConstructor (
+  IN  EFI_HANDLE                    ImageHandle,
+  IN  EFI_SYSTEM_TABLE              *SystemTable
+  )
+{
+  EFI_STATUS                        Status;
+  VOID                              *AcpiParameterBuffer;
+  ACPI_PARAMETER_BUFFER_DESCRIPTOR  *AcpiParamBufferDescriptor;
+  PRM_CONFIG_PROTOCOL               *PrmConfigProtocol;
+
+  AcpiParameterBuffer = NULL;
+  AcpiParamBufferDescriptor = NULL;
+  PrmConfigProtocol = NULL;
+
+  /*
+    In this sample PRM module, the protocol describing this sample module's resources is simply
+    installed in the constructor.
+
+    However, if some data is not available until later, this constructor could register a callback
+    on the dependency for the data to be available (e.g. ability to communicate with some device)
+    and then install the protocol. The requirement is that the protocol is installed before end of DXE.
+  */
+
+  // Allocate the ACPI parameter buffer
+
+  // A parameter buffer is arbitrary data that is handler specific. This handler buffer is specified
+  // to consist of a UINT32 that represents the test data signature ('T', 'E', 'S', 'T').
+  AcpiParameterBuffer = AllocateRuntimeZeroPool (sizeof (UINT32));
+  ASSERT (AcpiParameterBuffer != NULL);
+  if (AcpiParameterBuffer == NULL) {
+    Status = EFI_OUT_OF_RESOURCES;
+    goto Done;
+  }
+
+  // Allocate the ACPI Parameter Buffer Descriptor structure for a single PRM handler
+  AcpiParamBufferDescriptor = AllocateZeroPool (sizeof (*AcpiParamBufferDescriptor));
+  ASSERT (AcpiParamBufferDescriptor != NULL);
+  if (AcpiParamBufferDescriptor == NULL) {
+    Status = EFI_OUT_OF_RESOURCES;
+    goto Done;
+  }
+
+  // Allocate the PRM Configuration protocol structure for this PRM module
+  PrmConfigProtocol = AllocateZeroPool (sizeof (*PrmConfigProtocol));
+  ASSERT (PrmConfigProtocol != NULL);
+  if (PrmConfigProtocol == NULL) {
+    Status = EFI_OUT_OF_RESOURCES;
+    goto Done;
+  }
+  CopyGuid (&PrmConfigProtocol->ModuleContextBuffers.ModuleGuid, &mPrmModuleGuid);
+
+  // Populate the ACPI Parameter Buffer Descriptor structure
+  CopyGuid (&AcpiParamBufferDescriptor->HandlerGuid, &mCheckParamBufferPrmHandlerGuid);
+  AcpiParamBufferDescriptor->AcpiParameterBufferAddress = (UINT64) (UINTN) AcpiParameterBuffer;
+
+  // Populate the PRM Module Context Buffers structure
+  PrmConfigProtocol->ModuleContextBuffers.AcpiParameterBufferDescriptorCount = 1;
+  PrmConfigProtocol->ModuleContextBuffers.AcpiParameterBufferDescriptors = AcpiParamBufferDescriptor;
+
+  //
+  // Install the PRM Configuration Protocol for this module. This indicates the configuration
+  // library has completed resource initialization for the PRM module.
+  //
+  Status = gBS->InstallProtocolInterface (
+                  &mPrmConfigProtocolHandle,
+                  &gPrmConfigProtocolGuid,
+                  EFI_NATIVE_INTERFACE,
+                  (VOID *) PrmConfigProtocol
+                  );
+
+Done:
+  if (EFI_ERROR (Status)) {
+    if (AcpiParameterBuffer != NULL) {
+      FreePool (AcpiParameterBuffer);
+    }
+    if (AcpiParamBufferDescriptor != NULL) {
+      FreePool (AcpiParamBufferDescriptor);
+    }
+    if (PrmConfigProtocol != NULL) {
+      FreePool (PrmConfigProtocol);
+    }
+  }
+
+  return Status;
+}

PrmPkg/Samples/PrmSampleAcpiParameterBufferModule/Library/DxeAcpiParameterBufferModuleConfigLib/DxeAcpiParameterBufferModuleConfigLib.inf

@@ -0,0 +1,39 @@
+## @file
+#  Sample PRM Configuration Library Instance
+#
+#  The PRM configuration library instance is responsible for initializing and setting the corresponding
+#  PRM module's configuration in the boot environment.
+#
+#  Copyright (c) Microsoft Corporation
+#
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION         = 0x00010005
+  BASE_NAME           = DxeAcpiParameterBufferModuleConfigLib
+  FILE_GUID           = D43D19E9-007A-4D40-AC4A-418F958AFB9D
+  MODULE_TYPE         = DXE_DRIVER
+  VERSION_STRING      = 1.0
+  LIBRARY_CLASS       = NULL |DXE_DRIVER
+  CONSTRUCTOR         = AcpiParameterBufferModuleConfigLibConstructor
+
+[Sources]
+  DxeAcpiParameterBufferModuleConfigLib.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+  MdeModulePkg/MdeModulePkg.dec
+  PrmPkg/PrmPkg.dec
+
+[Protocols]
+  gPrmConfigProtocolGuid
+
+[LibraryClasses]
+  BaseLib
+  BaseMemoryLib
+  DebugLib
+  MemoryAllocationLib
+  UefiBootServicesTableLib
+  UefiDriverEntryPoint

PrmPkg/Samples/PrmSampleAcpiParameterBufferModule/PrmSampleAcpiParameterBufferModule.c

@@ -0,0 +1,79 @@
+/** @file
+
+  This PRM Module demonstrates how to define an ACPI parameter buffer that is used by a PRM handler.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <PrmModule.h>
+
+#include <Library/BaseLib.h>
+#include <Library/UefiLib.h>
+
+// TEMP
+#include <Library/DebugLib.h>
+
+#define PARAM_BUFFER_TEST_SIGNATURE         SIGNATURE_32('T','E','S','T')
+
+//
+// PRM Handler GUIDs
+//
+
+// {2e4f2d13-6240-4ed0-a401-c723fbdc34e8}
+#define CHECK_PARAM_BUFFER_PRM_HANDLER_GUID {0x2e4f2d13, 0x6240, 0x4ed0, {0xa4, 0x01, 0xc7, 0x23, 0xfb, 0xdc, 0x34, 0xe8}}
+
+/**
+  A sample Platform Runtime Mechanism (PRM) handler.
+
+  This sample handler checks if a parameter buffer is provided with the data signature
+  ('T', 'E', 'S', 'T') at the beginning of the buffer.
+
+  The contents are expected to be updated by ACPI code at OS runtime.
+
+  @param[in]  ParameterBuffer     A pointer to the PRM handler parameter buffer
+  @param[in]  ContextBUffer       A pointer to the PRM handler context buffer
+
+  @retval EFI_STATUS              The PRM handler executed successfully.
+  @retval Others                  An error occurred in the PRM handler.
+
+**/
+PRM_HANDLER_EXPORT (CheckParamBufferPrmHandler)
+{
+  if (ParameterBuffer == NULL) {
+    return EFI_INVALID_PARAMETER;
+  }
+
+  if (*((UINT32 *) ParameterBuffer) == PARAM_BUFFER_TEST_SIGNATURE) {
+    return EFI_SUCCESS;
+  }
+
+  return EFI_NOT_FOUND;
+}
+
+//
+// Register the PRM export information for this PRM Module
+//
+PRM_MODULE_EXPORT (
+  PRM_HANDLER_EXPORT_ENTRY (CHECK_PARAM_BUFFER_PRM_HANDLER_GUID, CheckParamBufferPrmHandler)
+  );
+
+/**
+  Module entry point.
+
+  @param[in]   ImageHandle     The image handle.
+  @param[in]   SystemTable     A pointer to the system table.
+
+  @retval  EFI_SUCCESS         This function always returns success.
+
+**/
+EFI_STATUS
+EFIAPI
+PrmSampleAcpiParameterBufferModuleInit (
+  IN  EFI_HANDLE                  ImageHandle,
+  IN  EFI_SYSTEM_TABLE            *SystemTable
+  )
+{
+  return EFI_SUCCESS;
+}

PrmPkg/Samples/PrmSampleAcpiParameterBufferModule/PrmSampleAcpiParameterBufferModule.inf

@@ -0,0 +1,41 @@
+## @file
+#  Sample PRM Driver
+#
+#  A sample PRM Module implementation. This PRM Module includes a PRM Module configuration library instance
+#  that applies the configuration for an ACPI parameter buffer in the boot environment. A PRM handler
+#  is provided that checks for a specific value in the parameter buffer that should be provided by ACPI
+#  code at OS runtime.
+#
+#  Copyright (c) Microsoft Corporation
+#
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION         = 0x00010005
+  BASE_NAME           = PrmSampleAcpiParameterBufferModule
+  FILE_GUID           = DC2A58A6-5927-4776-B995-D118A27335A2
+  MODULE_TYPE         = DXE_RUNTIME_DRIVER
+  VERSION_STRING      = 1.0
+  ENTRY_POINT         = PrmSampleAcpiParameterBufferModuleInit
+
+[Sources]
+  PrmSampleAcpiParameterBufferModule.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+  PrmPkg/PrmPkg.dec
+
+[LibraryClasses]
+  BaseLib
+  DebugLib
+  UefiDriverEntryPoint
+  UefiLib
+
+[Depex]
+  TRUE
+
+[BuildOptions.common]
+  MSFT:*_*_*_DLINK_FLAGS  = /DLL /SUBSYSTEM:CONSOLE /VERSION:1.0
+  MSFT:*_*_*_GENFW_FLAGS = --keepoptionalheader