PrmContextBuffer.h 5.8 KB

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