IntelFrameworkPkg/Include/Protocol/SmmBase.h

   1 /** @file
   2   This file declares SMM Base abstraction protocol.
   3   This protocol is used to install SMM handlers for support of subsequent SMI/PMI activations. This
   4   protocol is available on both IA-32 and Itanium based systems.
   5
   6   The EFI_SMM_BASE_PROTOCOL is a set of services that is exported by a processor device. It is
   7   a required protocol for the platform processor. This protocol can be used in both boot services and
   8   runtime mode. However, only the following member functions need to exist into runtime:
   9   - InSmm()
  10   - Communicate()
  11   This protocol is responsible for registering the handler services. The order in which the handlers are
  12   executed is prescribed only with respect to the MakeLast flag in the RegisterCallback()
  13   service. The driver exports these registration and unregistration services in boot services mode, but
  14   the registered handlers will execute through the preboot and runtime. The only way to change the
  15   behavior of a registered driver after ExitBootServices() has been invoked is to use some
  16   private communication mechanism with the driver to order it to quiesce. This model permits typical
  17   use cases, such as invoking the handler to enter ACPI mode, where the OS loader would make this
  18   call before boot services are terminated. On the other hand, handlers for services such as chipset
  19   workarounds for the century rollover in CMOS should provide commensurate services throughout
  20   preboot and OS runtime.
  21
  22   Copyright (c) 2007, Intel Corporation
  23   All rights reserved. This program and the accompanying materials
  24   are licensed and made available under the terms and conditions of the BSD License
  25   which accompanies this distribution.  The full text of the license may be found at
  26   http://opensource.org/licenses/bsd-license.php
  27
  28   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  29   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  30
  31   @par Revision Reference:
  32   This Protocol is defined in Framework of EFI SMM Core Interface Spec
  33   Version 0.9.
  34
  35 **/
  36
  37 #ifndef _SMM_BASE_H_
  38 #define _SMM_BASE_H_
  39
  40 #include <FrameworkSmm.h>
  41
  42 #define EFI_SMM_BASE_PROTOCOL_GUID \
  43   { \
  44     0x1390954D, 0xda95, 0x4227, {0x93, 0x28, 0x72, 0x82, 0xc2, 0x17, 0xda, 0xa8 } \
  45   }
  46
  47 typedef struct _EFI_SMM_BASE_PROTOCOL             EFI_SMM_BASE_PROTOCOL;
  48
  49 //
  50 // SMM Handler Definition
  51 //
  52 #define EFI_HANDLER_SUCCESS         0x0000
  53 #define EFI_HANDLER_CRITICAL_EXIT   0x0001
  54 #define EFI_HANDLER_SOURCE_QUIESCED 0x0002
  55 #define EFI_HANDLER_SOURCE_PENDING  0x0003
  56
  57 /**
  58   Entry Point to Callback service
  59
  60   @param  SmmImageHandle        A handle allocated by the SMM infrastructure code
  61                                 to uniquely designate a specific DXE SMM driver.
  62   @param  CommunicationBuffer   A pointer to a collection of data in memory
  63                                 that will be conveyed from a non-SMM environment into an SMM environment.
  64                                 The buffer must be contiguous, physically mapped, and be a physical address.
  65   @param  SourceSize            The size of the CommunicationBuffer.
  66
  67   @return Status code
  68
  69 **/
  70 typedef
  71 EFI_STATUS
  72 (EFIAPI *EFI_SMM_CALLBACK_ENTRY_POINT)(
  73   IN EFI_HANDLE             SmmImageHandle,
  74   IN OUT VOID               *CommunicationBuffer OPTIONAL,
  75   IN OUT UINTN              *SourceSize OPTIONAL
  76   );
  77
  78 //
  79 // SMM Base Protocol Definition
  80 //
  81 /**
  82   Register a given driver into SMRAM.This is the equivalent of performing
  83   the LoadImage/StartImage into System Management Mode.
  84
  85   @param  This                  Protocol instance pointer.
  86   @param  FilePath              Location of the image to be installed as the handler.
  87   @param  SourceBuffer          Optional source buffer in case of the image file
  88                                 being in memory.
  89   @param  SourceSize            Size of the source image file, if in memory.
  90   @param  ImageHandle           Pointer to the handle that reflects the driver
  91                                 loaded into SMM.
  92   @param  LegacyIA32Binary      The binary image to load is legacy 16 bit code.
  93
  94   @retval EFI_SUCCESS           The operation was successful.
  95   @retval EFI_OUT_OF_RESOURCES  There were no additional SMRAM resources to load the handler
  96   @retval EFI_UNSUPPORTED       This platform does not support 16-bit handlers.
  97   @retval EFI_UNSUPPORTED       In runtime.
  98   @retval EFI_INVALID_PARAMETER The handlers was not the correct image type
  99
 100 **/
 101 typedef
 102 EFI_STATUS
 103 (EFIAPI *EFI_SMM_REGISTER_HANDLER)(
 104   IN EFI_SMM_BASE_PROTOCOL                           *This,
 105   IN  EFI_DEVICE_PATH_PROTOCOL                       *FilePath,
 106   IN  VOID                                           *SourceBuffer OPTIONAL,
 107   IN  UINTN                                          SourceSize,
 108   OUT EFI_HANDLE                                     *ImageHandle,
 109   IN  BOOLEAN                                        LegacyIA32Binary OPTIONAL
 110   );
 111
 112 /**
 113   Remove a given driver SMRAM.  This is the equivalent of performing
 114   the UnloadImage System Management Mode.
 115
 116   @param  This                  Protocol instance pointer.
 117   @param  ImageHandle           Pointer to the handle that reflects the driver
 118                                 loaded into SMM.
 119
 120   @retval EFI_SUCCESS           The operation was successful
 121   @retval EFI_INVALID_PARAMETER The handler did not exist
 122   @retval EFI_UNSUPPORTED       In runtime.
 123
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *EFI_SMM_UNREGISTER_HANDLER)(
 128   IN EFI_SMM_BASE_PROTOCOL          *This,
 129   IN EFI_HANDLE                     ImageHandle
 130   );
 131
 132 /**
 133   The SMM Inter-module Communicate Service Communicate() function
 134   provides a services to send/received messages from a registered
 135   EFI service.  The BASE protocol driver is responsible for doing
 136   any of the copies such that the data lives in boot-service accessible RAM.
 137
 138   @param  This                  Protocol instance pointer.
 139   @param  ImageHandle           Pointer to the handle that reflects the driver
 140                                 loaded into SMM.
 141   @param  CommunicationBuffer   Pointer to the buffer to convey into SMRAM.
 142   @param  SourceSize            Size of the contents of buffer..
 143
 144   @retval EFI_SUCCESS           The message was successfully posted
 145   @retval EFI_INVALID_PARAMETER The buffer was NULL
 146
 147 **/
 148 typedef
 149 EFI_STATUS
 150 (EFIAPI *EFI_SMM_COMMUNICATE)(
 151   IN EFI_SMM_BASE_PROTOCOL          *This,
 152   IN EFI_HANDLE                     ImageHandle,
 153   IN OUT VOID                       *CommunicationBuffer,
 154   IN OUT UINTN                      *SourceSize
 155   );
 156
 157 /**
 158   Register a callback to execute within SMM.
 159   This allows receipt of messages created with the Boot Service COMMUNICATE.
 160
 161   @param  This                  Protocol instance pointer.
 162   @param  CallbackAddress       Address of the callback service
 163   @param  MakeFirst             If present, will stipulate that the handler is posted
 164                                 to be the first module executed in the dispatch table.
 165   @param  MakeLast              If present, will stipulate that the handler is posted
 166                                 to be last executed in the dispatch table.
 167   @param  FloatingPointSave     This is an optional parameter which informs the
 168                                 EFI_SMM_ACCESS_PROTOCOL Driver core if it needs to save
 169                                 the floating point register state. If any of the handlers
 170                                 require this, then the state will be saved for all of the handlers.
 171
 172   @retval EFI_SUCCESS           The operation was successful
 173   @retval EFI_OUT_OF_RESOURCES  Not enough space in the dispatch queue
 174   @retval EFI_UNSUPPORTED       In runtime.
 175   @retval EFI_UNSUPPORTED       Not in SMM.
 176
 177 **/
 178 typedef
 179 EFI_STATUS
 180 (EFIAPI *EFI_SMM_CALLBACK_SERVICE)(
 181   IN EFI_SMM_BASE_PROTOCOL                            *This,
 182   IN EFI_HANDLE                                       SmmImageHandle,
 183   IN EFI_SMM_CALLBACK_ENTRY_POINT                     CallbackAddress,
 184   IN BOOLEAN                                          MakeLast OPTIONAL,
 185   IN BOOLEAN                                          FloatingPointSave OPTIONAL
 186   );
 187
 188 /**
 189   The SmmAllocatePool() function allocates a memory region of Size bytes from memory of
 190   type PoolType and returns the address of the allocated memory in the location referenced
 191   by Buffer.  This function allocates pages from EFI SMRAM Memory as needed to grow the
 192   requested pool type.  All allocations are eight-byte aligned.
 193
 194   @param  This                  Protocol instance pointer.
 195   @param  PoolType              The type of pool to allocate.
 196                                 The only supported type is EfiRuntimeServicesData;
 197                                 the interface will internally map this runtime request to SMRAM.
 198   @param  Size                  The number of bytes to allocate from the pool.
 199   @param  Buffer                A pointer to a pointer to the allocated buffer if the call
 200                                 succeeds; undefined otherwise.
 201
 202   @retval EFI_SUCCESS           The requested number of bytes was allocated.
 203   @retval EFI_OUT_OF_RESOURCES  The pool requested could not be allocated.
 204   @retval EFI_INVALID_PARAMETER PoolType was invalid.
 205   @retval EFI_UNSUPPORTED       In runtime.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI *EFI_SMM_ALLOCATE_POOL)(
 211   IN EFI_SMM_BASE_PROTOCOL          *This,
 212   IN EFI_MEMORY_TYPE                PoolType,
 213   IN UINTN                          Size,
 214   OUT VOID                          **Buffer
 215   );
 216
 217 /**
 218   The SmmFreePool() function returns the memory specified by Buffer to the system.
 219   On return, the memory's type is EFI SMRAM Memory.  The Buffer that is freed must
 220   have been allocated by SmmAllocatePool().
 221
 222   @param  This                  Protocol instance pointer.
 223   @param  Buffer                Pointer to the buffer allocation.
 224
 225   @retval EFI_SUCCESS           The memory was returned to the system.
 226   @retval EFI_INVALID_PARAMETER Buffer was invalid.
 227   @retval EFI_UNSUPPORTED       In runtime.
 228
 229 **/
 230 typedef
 231 EFI_STATUS
 232 (EFIAPI *EFI_SMM_FREE_POOL)(
 233   IN EFI_SMM_BASE_PROTOCOL          *This,
 234   IN VOID                           *Buffer
 235   );
 236
 237 /**
 238   This routine tells caller if execution context is SMM or not.
 239
 240   @param  This                  Protocol instance pointer.
 241   @param  InSmm                 Whether the caller is inside SMM for IA-32 or servicing a PMI for the Itanium processor family.
 242
 243   @retval EFI_SUCCESS           The operation was successful
 244
 245 **/
 246 typedef
 247 EFI_STATUS
 248 (EFIAPI *EFI_SMM_INSIDE_OUT)(
 249   IN EFI_SMM_BASE_PROTOCOL          *This,
 250   OUT BOOLEAN                       *InSmm
 251   );
 252
 253 /**
 254   The GetSmstLocation() function returns the locatin of the System Management
 255   Service Table.  The use of the API is such that a driver can discover the
 256   location of the SMST in its entry point and then cache it in some driver
 257   global variable so that the SMST can be invoked in subsequent callbacks.
 258
 259   @param  This                  Protocol instance pointer.
 260   @param  Smst                  Pointer to the SMST.
 261
 262   @retval EFI_SUCCESS           The operation was successful
 263   @retval EFI_INVALID_PARAMETER Smst was invalid.
 264   @retval EFI_UNSUPPORTED       Not in SMM.
 265
 266 **/
 267 typedef
 268 EFI_STATUS
 269 (EFIAPI *EFI_SMM_GET_SMST_LOCATION)(
 270   IN EFI_SMM_BASE_PROTOCOL          *This,
 271   IN OUT EFI_SMM_SYSTEM_TABLE       **Smst
 272   );
 273
 274 /**
 275   @par Protocol Description:
 276   This protocol is used to install SMM handlers for support of subsequent SMI/PMI
 277   activations. This protocol is available on both IA-32 and Itanium-based systems.
 278
 279   @param Register
 280   Registers a handler to run in System Management RAM (SMRAM).
 281
 282   @param UnRegister
 283   Removes a handler from execution in SMRAM.
 284
 285   @param Communicate
 286   Sends/receives a message for a registered handler.
 287
 288   @param RegisterCallback
 289   Registers a callback from the constructor.
 290
 291   @param InSmm
 292   Detects whether the caller is inside or outside of SMM. SName
 293
 294   @param SmmAllocatePool
 295   Allocates SMRAM.
 296
 297   @param SmmFreePool
 298   Deallocates SMRAM.
 299
 300   @param GetSmstLocation
 301   Retrieves the location of the System Management System Table (SMST).
 302
 303 **/
 304 struct _EFI_SMM_BASE_PROTOCOL {
 305   EFI_SMM_REGISTER_HANDLER    Register;
 306   EFI_SMM_UNREGISTER_HANDLER  UnRegister;
 307   EFI_SMM_COMMUNICATE         Communicate;
 308   EFI_SMM_CALLBACK_SERVICE    RegisterCallback;
 309   EFI_SMM_INSIDE_OUT          InSmm;
 310   EFI_SMM_ALLOCATE_POOL       SmmAllocatePool;
 311   EFI_SMM_FREE_POOL           SmmFreePool;
 312   EFI_SMM_GET_SMST_LOCATION   GetSmstLocation;
 313 };
 314
 315 extern EFI_GUID gEfiSmmBaseProtocolGuid;
 316
 317 #endif