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, Intel Corporation. All rights reserved.<BR>
  15
  16 This program and the accompanying materials
  17 are licensed and made available under the terms and conditions
  18 of the BSD License which accompanies this distribution.  The
  19 full text of the license may be found at
  20 http://opensource.org/licenses/bsd-license.php
  21
  22 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  23 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  24
  25 **/
  26
  27 #ifndef _SMM_ACCESS_PPI_H_
  28 #define _SMM_ACCESS_PPI_H_
  29
  30 #define PEI_SMM_ACCESS_PPI_GUID \
  31   { 0x268f33a9, 0xcccd, 0x48be, { 0x88, 0x17, 0x86, 0x5, 0x3a, 0xc3, 0x2e, 0xd6 }}
  32
  33 typedef struct _PEI_SMM_ACCESS_PPI  PEI_SMM_ACCESS_PPI;
  34
  35 /**
  36   Opens the SMRAM area to be accessible by a PEIM driver.
  37
  38   This function "opens" SMRAM so that it is visible while not inside of SMM. The function should
  39   return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM. The function
  40   should return EFI_DEVICE_ERROR if the SMRAM configuration is locked.
  41
  42   @param  PeiServices            General purpose services available to every PEIM.
  43   @param  This                   The pointer to the SMM Access Interface.
  44   @param  DescriptorIndex        The region of SMRAM to Open.
  45
  46   @retval EFI_SUCCESS            The region was successfully opened.
  47   @retval EFI_DEVICE_ERROR       The region could not be opened because locked by chipset.
  48   @retval EFI_INVALID_PARAMETER  The descriptor index was out of bounds.
  49
  50 **/
  51 typedef
  52 EFI_STATUS
  53 (EFIAPI *PEI_SMM_OPEN)(
  54   IN EFI_PEI_SERVICES                **PeiServices,
  55   IN PEI_SMM_ACCESS_PPI              *This,
  56   IN UINTN                           DescriptorIndex
  57   );
  58
  59 /**
  60   Inhibits access to the SMRAM.
  61
  62   This function "closes" SMRAM so that it is not visible while outside of SMM. The function should
  63   return EFI_UNSUPPORTED if the hardware does not support hiding of SMRAM.
  64
  65   @param  PeiServices              General purpose services available to every PEIM.
  66   @param  This                     The pointer to the SMM Access Interface.
  67   @param  DescriptorIndex          The region of SMRAM to Close.
  68
  69   @retval EFI_SUCCESS              The region was successfully closed.
  70   @retval EFI_DEVICE_ERROR         The region could not be closed because locked by chipset.
  71   @retval EFI_INVALID_PARAMETER    The descriptor index was out of bounds.
  72
  73 **/
  74 typedef
  75 EFI_STATUS
  76 (EFIAPI *PEI_SMM_CLOSE)(
  77   IN EFI_PEI_SERVICES                **PeiServices,
  78   IN PEI_SMM_ACCESS_PPI              *This,
  79   IN UINTN                           DescriptorIndex
  80   );
  81
  82 /**
  83   Inhibits access to the SMRAM.
  84
  85   This function prohibits access to the SMRAM region.  This function is usually implemented such
  86   that it is a write-once operation.
  87
  88   @param  PeiServices              General purpose services available to every PEIM.
  89   @param  This                     The pointer to the SMM Access Interface.
  90   @param  DescriptorIndex          The region of SMRAM to Close.
  91
  92   @retval EFI_SUCCESS            The region was successfully locked.
  93   @retval EFI_DEVICE_ERROR       The region could not be locked because at least
  94                                  one range is still open.
  95   @retval EFI_INVALID_PARAMETER  The descriptor index was out of bounds.
  96
  97 **/
  98 typedef
  99 EFI_STATUS
 100 (EFIAPI *PEI_SMM_LOCK)(
 101   IN EFI_PEI_SERVICES                **PeiServices,
 102   IN PEI_SMM_ACCESS_PPI              *This,
 103   IN UINTN                           DescriptorIndex
 104   );
 105
 106 /**
 107   Queries the memory controller for the possible regions that will support SMRAM.
 108
 109   @param  PeiServices           General purpose services available to every PEIM.
 110   @param This                   The pointer to the SmmAccessPpi Interface.
 111   @param SmramMapSize           The pointer to the variable containing size of the
 112                                 buffer to contain the description information.
 113   @param SmramMap               The buffer containing the data describing the Smram
 114                                 region descriptors.
 115
 116   @retval EFI_BUFFER_TOO_SMALL  The user did not provide a sufficient buffer.
 117   @retval EFI_SUCCESS           The user provided a sufficiently-sized buffer.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *PEI_SMM_CAPABILITIES)(
 123   IN EFI_PEI_SERVICES                **PeiServices,
 124   IN PEI_SMM_ACCESS_PPI              *This,
 125   IN OUT UINTN                       *SmramMapSize,
 126   IN OUT EFI_SMRAM_DESCRIPTOR        *SmramMap
 127   );
 128
 129 ///
 130 ///  EFI SMM Access PPI is used to control the visibility of the SMRAM on the platform.
 131 ///  It abstracts the location and characteristics of SMRAM.  The expectation is
 132 ///  that the north bridge or memory controller would publish this PPI.
 133 ///
 134 struct _PEI_SMM_ACCESS_PPI {
 135   PEI_SMM_OPEN          Open;
 136   PEI_SMM_CLOSE         Close;
 137   PEI_SMM_LOCK          Lock;
 138   PEI_SMM_CAPABILITIES  GetCapabilities;
 139   BOOLEAN               LockState;
 140   BOOLEAN               OpenState;
 141 };
 142
 143 extern EFI_GUID gPeiSmmAccessPpiGuid;
 144
 145 #endif