PrmPkg/Include/PrmContextBuffer.h

   1 /** @file
   2
   3   Definitions for the Platform Runtime Mechanism (PRM) context buffer structures.
   4
   5   Copyright (c) Microsoft Corporation
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef PRM_CONTEXT_BUFFER_H_
  11 #define PRM_CONTEXT_BUFFER_H_
  12
  13 #include <PrmDataBuffer.h>
  14 #include <PrmMmio.h>
  15 #include <Uefi.h>
  16
  17 #define PRM_CONTEXT_BUFFER_SIGNATURE          SIGNATURE_32('P','R','M','C')
  18 #define PRM_CONTEXT_BUFFER_INTERFACE_VERSION  1
  19
  20 #pragma pack(push, 1)
  21
  22 //
  23 // This is the context buffer structure that is passed to a PRM handler.
  24 //
  25 // At OS runtime, the OS will allocate and populate this structure and
  26 // place virtual addresses in the pointer fields.
  27 //
  28 // It is also reused internally in FW (in the PRM_MODULE_CONTEXT_BUFFERS structure)
  29 // to track context buffers within a given PRM module. In that internal usage,
  30 // the addresses will be physical addresses.
  31 //
  32 typedef struct {
  33   ///
  34   /// Signature of this interface.
  35   ///
  36   UINT32                                  Signature;
  37
  38   ///
  39   /// Version of this interface.
  40   ///
  41   UINT16                                  Version;
  42
  43   ///
  44   /// Reserved field.
  45   ///
  46   UINT16                                  Reserved;
  47
  48   ///
  49   /// The GUID of the PRM handler represented by this context instance.
  50   ///
  51   EFI_GUID                                HandlerGuid;
  52
  53   ///
  54   /// A virtual address pointer to the static data buffer allocated for
  55   /// the PRM handler represented by this context instance.
  56   ///
  57   /// The static buffer is intended to be populated in the PRM module
  58   /// configuration library and treated as read-only data at OS runtime.
  59   ///
  60   /// This pointer may be NULL if a static data buffer is not needed.
  61   ///
  62   PRM_DATA_BUFFER                         *StaticDataBuffer;
  63
  64   ///
  65   /// A virtual address pointer to an array of PRM_RUNTIME_MMIO_RANGE
  66   /// structures that describe MMIO physical address ranges mapped to
  67   /// virtual memory addresses for access at OS runtime.
  68   ///
  69   /// This pointer is ignored in firmware internal usage of this structure
  70   /// as this field is present to allow a PRM handler to get the list
  71   /// of MMIO ranges described as accessible by its PRM module.
  72   ///
  73   /// The module list of MMIO ranges is specified by the PRM configuration
  74   /// code as a single array in PRM_MODULE_CONTEXT_BUFFERS.
  75   ///
  76   /// The OS is responsible for ensuring the pointer to the array in this
  77   /// structure is converted to a virtual address during construction of
  78   /// of the context buffer in the OS.
  79   ///
  80   /// This pointer may be NULL if runtime memory ranges are not needed.
  81   ///
  82   PRM_RUNTIME_MMIO_RANGES                 *RuntimeMmioRanges;
  83 } PRM_CONTEXT_BUFFER;
  84
  85 //
  86 // A firmware internal data structure used to track context buffer and
  87 // runtime MMIO range usage across a PRM module.
  88 //
  89 typedef struct
  90 {
  91   ///
  92   /// The GUID of the PRM module.
  93   ///
  94   EFI_GUID                                ModuleGuid;
  95
  96   ///
  97   /// The number of PRM context buffers in ContextBuffers[].
  98   /// This count should equal the number of PRM handlers in the module being configured.
  99   ///
 100   UINTN                                   BufferCount;
 101
 102   ///
 103   /// A pointer to an array of PRM context buffers
 104   ///
 105   PRM_CONTEXT_BUFFER                      *Buffer;
 106
 107   /// The MMIO ranges are defined in the firmware boot environment.
 108   /// The addresses within the PRM_RUNTIME_MMIO_RANGES structure will
 109   /// be converted to virtual addresses by firmware.
 110
 111   ///
 112   /// A physical address pointer to an array of PRM_RUNTIME_MMIO_RANGE
 113   /// structures that describe memory ranges that need to be mapped to
 114   /// virtual memory addresses for access at OS runtime.
 115   ///
 116   /// This is a consolidated array of MMIO ranges accessed by any PRM
 117   /// handler in the PRM module at OS runtime. The MMIO range physical
 118   /// addresses registered here will automatically be converted to the
 119   /// corresponding virtual address in the structure by PRM infrastructure
 120   /// code. No action is required to convert MMIO range base physical
 121   /// addresses to virtual addresses by either the PRM configuration code
 122   /// or the OS.
 123   ///
 124   /// This pointer may be NULL if runtime memory ranges are not needed.
 125   ///
 126   PRM_RUNTIME_MMIO_RANGES                 *RuntimeMmioRanges;
 127 } PRM_MODULE_CONTEXT_BUFFERS;
 128
 129 #pragma pack(pop)
 130
 131 #endif