MdeModulePkg/Include/Ppi/SmmAccess.h

   1 /** @file
   2   EFI SMM Access PPI definition.
   3
   4   This PPI is used to control the visibility of the SMRAM on the platform.
   5   It abstracts the location and characteristics of SMRAM.  The expectation is
   6   that the north bridge or memory controller would publish this PPI.
   7
   8   The principal functionality found in the memory controller includes the following:
   9   - Exposing the SMRAM to all non-SMM agents, or the "open" state
  10   - Shrouding the SMRAM to all but the SMM agents, or the "closed" state
  11   - Preserving the system integrity, or "locking" the SMRAM, such that the settings cannot be
  12     perturbed by either boot service or runtime agents
  13
  14 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
  15
  16 SPDX-License-Identifier: BSD-2-Clause-Patent
  17
  18 **/
  19
  20 #ifndef _SMM_ACCESS_PPI_H_
  21 #define _SMM_ACCESS_PPI_H_
  22
  23 #define PEI_SMM_ACCESS_PPI_GUID \
  24   { 0x268f33a9, 0xcccd, 0x48be, { 0x88, 0x17, 0x86, 0x5, 0x3a, 0xc3, 0x2e, 0xd6 }}
  25
  26 typedef struct _PEI_SMM_ACCESS_PPI  PEI_SMM_ACCESS_PPI;
  27
  28 /**
  29   Opens the SMRAM area to be accessible by a PEIM driver.
  30
  31   This function "opens" SMRAM so that it is visible while not inside of SMM. The function should
  32   return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM. The function
  33   should return EFI_DEVICE_ERROR if the SMRAM configuration is locked.
  34
  35   @param  PeiServices            General purpose services available to every PEIM.
  36   @param  This                   The pointer to the SMM Access Interface.
  37   @param  DescriptorIndex        The region of SMRAM to Open.
  38
  39   @retval EFI_SUCCESS            The region was successfully opened.
  40   @retval EFI_DEVICE_ERROR       The region could not be opened because locked by chipset.
  41   @retval EFI_INVALID_PARAMETER  The descriptor index was out of bounds.
  42
  43 **/
  44 typedef
  45 EFI_STATUS
  46 (EFIAPI *PEI_SMM_OPEN)(
  47   IN EFI_PEI_SERVICES                **PeiServices,
  48   IN PEI_SMM_ACCESS_PPI              *This,
  49   IN UINTN                           DescriptorIndex
  50   );
  51
  52 /**
  53   Inhibits access to the SMRAM.
  54
  55   This function "closes" SMRAM so that it is not visible while outside of SMM. The function should
  56   return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM.
  57
  58   @param  PeiServices              General purpose services available to every PEIM.
  59   @param  This                     The pointer to the SMM Access Interface.
  60   @param  DescriptorIndex          The region of SMRAM to Close.
  61
  62   @retval EFI_SUCCESS              The region was successfully closed.
  63   @retval EFI_DEVICE_ERROR         The region could not be closed because locked by chipset.
  64   @retval EFI_INVALID_PARAMETER    The descriptor index was out of bounds.
  65
  66 **/
  67 typedef
  68 EFI_STATUS
  69 (EFIAPI *PEI_SMM_CLOSE)(
  70   IN EFI_PEI_SERVICES                **PeiServices,
  71   IN PEI_SMM_ACCESS_PPI              *This,
  72   IN UINTN                           DescriptorIndex
  73   );
  74
  75 /**
  76   Inhibits access to the SMRAM.
  77
  78   This function prohibits access to the SMRAM region.  This function is usually implemented such
  79   that it is a write-once operation.
  80
  81   @param  PeiServices              General purpose services available to every PEIM.
  82   @param  This                     The pointer to the SMM Access Interface.
  83   @param  DescriptorIndex          The region of SMRAM to Close.
  84
  85   @retval EFI_SUCCESS            The region was successfully locked.
  86   @retval EFI_DEVICE_ERROR       The region could not be locked because at least
  87                                  one range is still open.
  88   @retval EFI_INVALID_PARAMETER  The descriptor index was out of bounds.
  89
  90 **/
  91 typedef
  92 EFI_STATUS
  93 (EFIAPI *PEI_SMM_LOCK)(
  94   IN EFI_PEI_SERVICES                **PeiServices,
  95   IN PEI_SMM_ACCESS_PPI              *This,
  96   IN UINTN                           DescriptorIndex
  97   );
  98
  99 /**
 100   Queries the memory controller for the possible regions that will support SMRAM.
 101
 102   @param  PeiServices           General purpose services available to every PEIM.
 103   @param This                   The pointer to the SmmAccessPpi Interface.
 104   @param SmramMapSize           The pointer to the variable containing size of the
 105                                 buffer to contain the description information.
 106   @param SmramMap               The buffer containing the data describing the Smram
 107                                 region descriptors.
 108
 109   @retval EFI_BUFFER_TOO_SMALL  The user did not provide a sufficient buffer.
 110   @retval EFI_SUCCESS           The user provided a sufficiently-sized buffer.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *PEI_SMM_CAPABILITIES)(
 116   IN EFI_PEI_SERVICES                **PeiServices,
 117   IN PEI_SMM_ACCESS_PPI              *This,
 118   IN OUT UINTN                       *SmramMapSize,
 119   IN OUT EFI_SMRAM_DESCRIPTOR        *SmramMap
 120   );
 121
 122 ///
 123 ///  EFI SMM Access PPI is used to control the visibility of the SMRAM on the platform.
 124 ///  It abstracts the location and characteristics of SMRAM. The platform should report
 125 ///  all MMRAM via PEI_SMM_ACCESS_PPI. The expectation is that the north bridge or
 126 ///  memory controller would publish this PPI.
 127 ///
 128 struct _PEI_SMM_ACCESS_PPI {
 129   PEI_SMM_OPEN          Open;
 130   PEI_SMM_CLOSE         Close;
 131   PEI_SMM_LOCK          Lock;
 132   PEI_SMM_CAPABILITIES  GetCapabilities;
 133   BOOLEAN               LockState;
 134   BOOLEAN               OpenState;
 135 };
 136
 137 extern EFI_GUID gPeiSmmAccessPpiGuid;
 138
 139 #endif