/** @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) | |
// | |
// Associates an ACPI parameter buffer with a particular PRM handler in | |
// a PRM module. | |
// | |
// If either the GUID or address are zero then neither value is used to | |
// copy the ACPI parameter buffer address to the PRMT ACPI table. | |
// | |
typedef struct { | |
EFI_GUID HandlerGuid; | |
UINT64 AcpiParameterBufferAddress; | |
} ACPI_PARAMETER_BUFFER_DESCRIPTOR; | |
// | |
// 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; | |
/// | |
/// The number of ACPI parameter buffer descriptors in the array | |
/// AcpiParameterBufferDescriptors | |
/// | |
UINTN AcpiParameterBufferDescriptorCount; | |
/// | |
/// A pointer to an array of ACPI parameter buffer descriptors. PRM module | |
/// configuration code uses this structure to associate a specific PRM | |
/// handler with an ACPI parameter buffer. | |
/// | |
/// An ACPI parameter buffer is a parameter buffer allocated by the PRM | |
/// module configuration code to be used by ACPI as a parameter buffer | |
/// to the associated PRM handler at OS runtime. | |
/// | |
/// This buffer is not required if: | |
/// 1. A parameter buffer is not used by a PRM handler at all | |
/// 2. A parameter buffer is used but the PRM handler is never invoked | |
/// from ACPI (it is directly called by an OS device driver for example) | |
/// | |
/// In case #2 above, the direct PRM handler is responsible for allocating | |
/// a parameter buffer and passing that buffer to the PRM handler. | |
/// | |
/// A PRM module only needs to provide an ACPI_PARAMETER_BUFFER_DESCRIPTOR | |
/// for each PRM handler that actually uses an ACPI parameter buffer. If | |
/// no handlers use an ACPI parameter buffer this pointer should be NULL. | |
/// | |
ACPI_PARAMETER_BUFFER_DESCRIPTOR *AcpiParameterBufferDescriptors; | |
} PRM_MODULE_CONTEXT_BUFFERS; | |
#pragma pack(pop) | |
#endif |