PrmPkg: Add package and include headers

REF:https://bugzilla.tianocore.org/show_bug.cgi?id=3812

Adds a new package to maintain Platform Runtime Mechanism (PRM)
support.

This package is intended to include generic code that provides a
common infrastructure to support PRM in firmware and a collection
of sample PRM modules that demonstrate how to use the interfaces
and other package resources to author a PRM module.

The following initial headers are included in this commit:

* Prm.h - Includes common content for PRM with no dependencies on
  other PRM header files.

* PrmContextBuffer.h - Includes definitions for PRM context buffers.

  Context buffers are standardized structures that point to various
  resources available to a PRM handler during its execution.

* PrmDataBuffer.h - Includes definitions for PRM data buffers.

  Within the context of PRM, these data buffers are composed of a
  generic header followed by a variable length blob of arbitrary
  data.

* PrmExportDescriptor.h - Includes definitions for  creating PRM
  export descriptors.

  A PRM export descriptor is a structure referenced in the export
  table of PRM module that contains PRM-specific metadata about the
  module.

* PrmMmio.h - Includes definitions for describing MMIO ranges uses
  by PRM modules.

* PrmModule.h - Includes definitions commonly used by PRM module
  authors.

  This file is provided to serve as a convenient include for PRM
  module authors.

* PrmOsServices.h - Includes content specific to PRM OS services.

  OS Services will not planned to be present in the final version
  of PRM. The OS Services have been reduced to a simple debug print
  function. So this is currently planned to be a temporary file to
  support debugging during PRM development.

Note: Modules built for the UEFI environment can be built by Visual
      Studio and non-Visual Studio toolchains. However, PRM modules
      are currently only supported on Visual Studio toolchain due to
      usage of export tables.

Cc: Andrew Fish <[email protected]>
Cc: Kang Gao <[email protected]>
Cc: Michael D Kinney <[email protected]>
Cc: Michael Kubacki <[email protected]>
Cc: Leif Lindholm <[email protected]>
Cc: Benjamin You <[email protected]>
Cc: Liu Yun <[email protected]>
Cc: Ankit Sinha <[email protected]>
Cc: Nate DeSimone <[email protected]>
Signed-off-by: Michael Kubacki <[email protected]>
Acked-by: Michael D Kinney <[email protected]>
Acked-by: Liming Gao <[email protected]>
Acked-by: Leif Lindholm <[email protected]>
Reviewed-by: Ankit Sinha <[email protected]>

Author: makubacki

PrmPkg/Include/Prm.h

@@ -0,0 +1,46 @@
+/** @file
+
+  Common Platform Runtime Mechanism (PRM) definitions.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef PRM_H_
+#define PRM_H_
+
+#include <Uefi.h>
+#include <PrmContextBuffer.h>
+
+#if defined(_MSC_VER)
+  #define PRM_EXPORT_API                          __declspec(dllexport)
+#else
+  #define PRM_EXPORT_API
+#endif
+
+#define PRM_HANDLER_NAME_MAXIMUM_LENGTH           128
+
+#define PRM_STRING_(x)                            #x
+#define PRM_STRING(x)                             PRM_STRING_(x)
+
+/**
+  A Platform Runtime Mechanism (PRM) handler function.
+
+  @param[in]  ParameterBuffer             A pointer to a buffer with arbitrary data that is allocated and populated
+                                          by the PRM handler caller.
+  @param[in]  ContextBuffer               A pointer to a buffer with arbitrary data that is allocated in the firmware
+                                          boot environment.
+
+  @retval EFI_STATUS              The PRM handler executed successfully.
+  @retval Others                  An error occurred in the PRM handler.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI PRM_HANDLER) (
+  IN VOID                 *ParameterBuffer  OPTIONAL,
+  IN PRM_CONTEXT_BUFFER   *ContextBuffer  OPTIONAL
+  );
+
+#endif

PrmPkg/Include/PrmContextBuffer.h

@@ -0,0 +1,131 @@
+/** @file
+
+  Definitions for the Platform Runtime Mechanism (PRM) context buffer structures.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef PRM_CONTEXT_BUFFER_H_
+#define PRM_CONTEXT_BUFFER_H_
+
+#include <PrmDataBuffer.h>
+#include <PrmMmio.h>
+#include <Uefi.h>
+
+#define PRM_CONTEXT_BUFFER_SIGNATURE          SIGNATURE_32('P','R','M','C')
+#define PRM_CONTEXT_BUFFER_INTERFACE_VERSION  1
+
+#pragma pack(push, 1)
+
+//
+// This is the context buffer structure that is passed to a PRM handler.
+//
+// At OS runtime, the OS will allocate and populate this structure and
+// place virtual addresses in the pointer fields.
+//
+// It is also reused internally in FW (in the PRM_MODULE_CONTEXT_BUFFERS structure)
+// to track context buffers within a given PRM module. In that internal usage,
+// the addresses will be physical addresses.
+//
+typedef struct {
+  ///
+  /// Signature of this interface.
+  ///
+  UINT32                                  Signature;
+
+  ///
+  /// Version of this interface.
+  ///
+  UINT16                                  Version;
+
+  ///
+  /// Reserved field.
+  ///
+  UINT16                                  Reserved;
+
+  ///
+  /// The GUID of the PRM handler represented by this context instance.
+  ///
+  EFI_GUID                                HandlerGuid;
+
+  ///
+  /// A virtual address pointer to the static data buffer allocated for
+  /// the PRM handler represented by this context instance.
+  ///
+  /// The static buffer is intended to be populated in the PRM module
+  /// configuration library and treated as read-only data at OS runtime.
+  ///
+  /// This pointer may be NULL if a static data buffer is not needed.
+  ///
+  PRM_DATA_BUFFER                         *StaticDataBuffer;
+
+  ///
+  /// A virtual address pointer to an array of PRM_RUNTIME_MMIO_RANGE
+  /// structures that describe MMIO physical address ranges mapped to
+  /// virtual memory addresses for access at OS runtime.
+  ///
+  /// This pointer is ignored in firmware internal usage of this structure
+  /// as this field is present to allow a PRM handler to get the list
+  /// of MMIO ranges described as accessible by its PRM module.
+  ///
+  /// The module list of MMIO ranges is specified by the PRM configuration
+  /// code as a single array in PRM_MODULE_CONTEXT_BUFFERS.
+  ///
+  /// The OS is responsible for ensuring the pointer to the array in this
+  /// structure is converted to a virtual address during construction of
+  /// of the context buffer in the OS.
+  ///
+  /// This pointer may be NULL if runtime memory ranges are not needed.
+  ///
+  PRM_RUNTIME_MMIO_RANGES                 *RuntimeMmioRanges;
+} PRM_CONTEXT_BUFFER;
+
+//
+// A firmware internal data structure used to track context buffer and
+// runtime MMIO range usage across a PRM module.
+//
+typedef struct
+{
+  ///
+  /// The GUID of the PRM module.
+  ///
+  EFI_GUID                                ModuleGuid;
+
+  ///
+  /// The number of PRM context buffers in ContextBuffers[].
+  /// This count should equal the number of PRM handlers in the module being configured.
+  ///
+  UINTN                                   BufferCount;
+
+  ///
+  /// A pointer to an array of PRM context buffers
+  ///
+  PRM_CONTEXT_BUFFER                      *Buffer;
+
+  /// The MMIO ranges are defined in the firmware boot environment.
+  /// The addresses within the PRM_RUNTIME_MMIO_RANGES structure will
+  /// be converted to virtual addresses by firmware.
+
+  ///
+  /// A physical address pointer to an array of PRM_RUNTIME_MMIO_RANGE
+  /// structures that describe memory ranges that need to be mapped to
+  /// virtual memory addresses for access at OS runtime.
+  ///
+  /// This is a consolidated array of MMIO ranges accessed by any PRM
+  /// handler in the PRM module at OS runtime. The MMIO range physical
+  /// addresses registered here will automatically be converted to the
+  /// corresponding virtual address in the structure by PRM infrastructure
+  /// code. No action is required to convert MMIO range base physical
+  /// addresses to virtual addresses by either the PRM configuration code
+  /// or the OS.
+  ///
+  /// This pointer may be NULL if runtime memory ranges are not needed.
+  ///
+  PRM_RUNTIME_MMIO_RANGES                 *RuntimeMmioRanges;
+} PRM_MODULE_CONTEXT_BUFFERS;
+
+#pragma pack(pop)
+
+#endif

PrmPkg/Include/PrmDataBuffer.h

@@ -0,0 +1,50 @@
+/** @file
+
+  Definitions for the Platform Runtime Mechanism (PRM) data buffer structures.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef PRM_DATA_BUFFER_H_
+#define PRM_DATA_BUFFER_H_
+
+#include <Uefi.h>
+
+#define PRM_DATA_BUFFER_HEADER_SIGNATURE      SIGNATURE_32('P','R','M','D')
+
+#pragma pack(push, 1)
+
+///
+/// A generic header that describes the PRM data buffer.
+///
+typedef struct {
+  ///
+  /// PRM Data Buffer signature.
+  ///
+  UINT32                                  Signature;
+  ///
+  /// Length of the entire data buffer, including the size of the header.
+  ///
+  UINT32                                  Length;
+} PRM_DATA_BUFFER_HEADER;
+
+///
+/// A PRM data buffer is a generic header followed by variable length arbitrary data.
+///
+typedef struct {
+  ///
+  /// The header is required at the beginning of every PRM data buffer.
+  ///
+  PRM_DATA_BUFFER_HEADER                  Header;
+
+  ///
+  /// The beginning of data immediately follows the header.
+  ///
+  UINT8                                   Data[1];
+} PRM_DATA_BUFFER;
+
+#pragma pack(pop)
+
+#endif

PrmPkg/Include/PrmExportDescriptor.h

@@ -0,0 +1,87 @@
+/** @file
+
+  Definitions for the Platform Runtime Mechanism (PRM) export descriptor structures.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef PRM_EXPORT_DESCRIPTOR_H_
+#define PRM_EXPORT_DESCRIPTOR_H_
+
+#include <Prm.h>
+
+#define PRM_MODULE_EXPORT_DESCRIPTOR_NAME         PrmModuleExportDescriptor
+#define PRM_MODULE_EXPORT_DESCRIPTOR_SIGNATURE    SIGNATURE_64 ('P', 'R', 'M', '_', 'M', 'E', 'D', 'T')
+#define PRM_MODULE_EXPORT_REVISION                0x0
+
+//
+// Platform Runtime Mechanism (PRM) Export Descriptor Structures
+//
+#pragma pack(push, 1)
+
+typedef struct {
+  GUID                                  PrmHandlerGuid;
+  CHAR8                                 PrmHandlerName[PRM_HANDLER_NAME_MAXIMUM_LENGTH];
+} PRM_HANDLER_EXPORT_DESCRIPTOR_STRUCT;
+
+typedef struct {
+  UINT64                                Signature;
+  UINT16                                Revision;
+  UINT16                                NumberPrmHandlers;
+  GUID                                  ModuleGuid;
+  PRM_HANDLER_EXPORT_DESCRIPTOR_STRUCT  PrmHandlerExportDescriptors[3];
+} PRM_MODULE_EXPORT_DESCRIPTOR_STRUCT;
+
+#pragma pack(pop)
+
+/**
+  A macro that declares a PRM Handler Export Descriptor for a PRM Handler.
+
+  This macro is intended to be used once per PRM Handler to describe the handler when the
+  module description is defined. It should be provided as an argument to PRM_MODULE_EXPORT.
+
+  @param  Guid    The GUID of the PRM Handler being exported.
+
+  @param  Name    The name of the PRM Handler being exported. This string should exactly
+                  match the function name.
+
+**/
+#define PRM_HANDLER_EXPORT_ENTRY(Guid, Name)  \
+      {                                       \
+        Guid,                                 \
+        PRM_STRING_(Name)                     \
+      }                                       \
+
+/**
+  A macro that returns the count of the number of variable-length arguments given.
+
+  @param  VariableArgumentList  A variable argument list of elements that will be included
+                                in the return value of the list count.
+**/
+#define VA_ARG_COUNT(...)  (sizeof((PRM_HANDLER_EXPORT_DESCRIPTOR_STRUCT[]){__VA_ARGS__})/sizeof(PRM_HANDLER_EXPORT_DESCRIPTOR_STRUCT))
+
+/**
+  A macro that declares the PRM Module Export Descriptor for a PRM Module.
+
+  This macro is intended to be used once in a PRM Module after all of the PRM Handler definitions
+  to describe the PRM Handlers being exported in the module.
+
+  @param  PrmHandlerExportEntries   A variable argument list of PRM_HANDLER_EXPORT_ENTRY values.
+                                    This list should include all PRM Handlers being exported by
+                                    this module.
+
+**/
+#define PRM_MODULE_EXPORT(...)                                                              \
+  PRM_EXPORT_API PRM_MODULE_EXPORT_DESCRIPTOR_STRUCT PRM_MODULE_EXPORT_DESCRIPTOR_NAME = {               \
+    {                                                                                                     \
+      PRM_MODULE_EXPORT_DESCRIPTOR_SIGNATURE,                                                             \
+      PRM_MODULE_EXPORT_REVISION,                                                                         \
+      VA_ARG_COUNT(__VA_ARGS__),                                                                          \
+      EFI_CALLER_ID_GUID                                                                                  \
+    },                                                                                                    \
+    { __VA_ARGS__ }                                                                                       \
+  }                                                                                                       \
+
+#endif

PrmPkg/Include/PrmMmio.h

@@ -0,0 +1,45 @@
+/** @file
+
+  Definitions for the Platform Runtime Mechanism (PRM) MMIO elements.
+
+  Copyright (c) Microsoft Corporation
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef PRM_MMIO_H_
+#define PRM_MMIO_H_
+
+#include <Uefi.h>
+
+#pragma pack(push, 1)
+
+///
+/// Describes a memory range that needs to be made accessible at OS runtime.
+///
+/// The memory range with the given base address and length will be marked as EFI_MEMORY_RUNTIME.
+///
+typedef struct {
+  EFI_PHYSICAL_ADDRESS                    PhysicalBaseAddress;
+  EFI_PHYSICAL_ADDRESS                    VirtualBaseAddress;
+  UINT32                                  Length;
+} PRM_RUNTIME_MMIO_RANGE;
+
+///
+/// Describes a buffer with an array of PRM module
+/// config runtime memory ranges.
+///
+typedef struct {
+  ///
+  /// The number of runtime memory range elements in this buffer.
+  ///
+  UINT64                                  Count;
+  ///
+  /// The beginning of the runtime memory range data.
+  ///
+  PRM_RUNTIME_MMIO_RANGE                  Range[1];
+} PRM_RUNTIME_MMIO_RANGES;
+
+#pragma pack(pop)
+
+#endif