audk/PrmPkg/Include/PrmContextBuffer.h

/** @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