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 /**
 114   Remove a given driver SMRAM.  This is the equivalent of performing
 115   the UnloadImage System Management Mode.
 116
 117   @param  This                  Protocol instance pointer.
 118   @param  ImageHandle           Pointer to the handle that reflects the driver
 119                                 loaded into SMM.
 120
 121   @retval EFI_SUCCESS           The operation was successful
 122   @retval EFI_INVALID_PARAMETER The handler did not exist
 123   @retval EFI_UNSUPPORTED       In runtime.
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *EFI_SMM_UNREGISTER_HANDLER) (
 129   IN EFI_SMM_BASE_PROTOCOL          *This,
 130   IN EFI_HANDLE                     ImageHandle
 131   )
 132 ;
 133
 134 /**
 135   The SMM Inter-module Communicate Service Communicate() function
 136   provides a services to send/received messages from a registered
 137   EFI service.  The BASE protocol driver is responsible for doing
 138   any of the copies such that the data lives in boot-service accessible RAM.
 139
 140   @param  This                  Protocol instance pointer.
 141   @param  ImageHandle           Pointer to the handle that reflects the driver
 142                                 loaded into SMM.
 143   @param  CommunicationBuffer   Pointer to the buffer to convey into SMRAM.
 144   @param  SourceSize            Size of the contents of buffer..
 145
 146   @retval EFI_SUCCESS           The message was successfully posted
 147   @retval EFI_INVALID_PARAMETER The buffer was NULL
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_SMM_COMMUNICATE) (
 153   IN EFI_SMM_BASE_PROTOCOL          *This,
 154   IN EFI_HANDLE                     ImageHandle,
 155   IN OUT VOID                       *CommunicationBuffer,
 156   IN OUT UINTN                      *SourceSize
 157   )
 158 ;
 159
 160 /**
 161   Register a callback to execute within SMM.
 162   This allows receipt of messages created with the Boot Service COMMUNICATE.
 163
 164   @param  This                  Protocol instance pointer.
 165   @param  CallbackAddress       Address of the callback service
 166   @param  MakeFirst             If present, will stipulate that the handler is posted
 167                                 to be the first module executed in the dispatch table.
 168   @param  MakeLast              If present, will stipulate that the handler is posted
 169                                 to be last executed in the dispatch table.
 170   @param  FloatingPointSave     This is an optional parameter which informs the
 171                                 EFI_SMM_ACCESS_PROTOCOL Driver core if it needs to save
 172                                 the floating point register state. If any of the handlers
 173                                 require this, then the state will be saved for all of the handlers.
 174
 175   @retval EFI_SUCCESS           The operation was successful
 176   @retval EFI_OUT_OF_RESOURCES  Not enough space in the dispatch queue
 177   @retval EFI_UNSUPPORTED       In runtime.
 178   @retval EFI_UNSUPPORTED       Not in SMM.
 179
 180 **/
 181 typedef
 182 EFI_STATUS
 183 (EFIAPI *EFI_SMM_CALLBACK_SERVICE) (
 184   IN EFI_SMM_BASE_PROTOCOL                            *This,
 185   IN EFI_HANDLE                                       SmmImageHandle,
 186   IN EFI_SMM_CALLBACK_ENTRY_POINT                     CallbackAddress,
 187   IN BOOLEAN                                          MakeLast OPTIONAL,
 188   IN BOOLEAN                                          FloatingPointSave OPTIONAL
 189   )
 190 ;
 191
 192 /**
 193   The SmmAllocatePool() function allocates a memory region of Size bytes from memory of
 194   type PoolType and returns the address of the allocated memory in the location referenced
 195   by Buffer.  This function allocates pages from EFI SMRAM Memory as needed to grow the
 196   requested pool type.  All allocations are eight-byte aligned.
 197
 198   @param  This                  Protocol instance pointer.
 199   @param  PoolType              The type of pool to allocate.
 200                                 The only supported type is EfiRuntimeServicesData;
 201                                 the interface will internally map this runtime request to SMRAM.
 202   @param  Size                  The number of bytes to allocate from the pool.
 203   @param  Buffer                A pointer to a pointer to the allocated buffer if the call
 204                                 succeeds; undefined otherwise.
 205
 206   @retval EFI_SUCCESS           The requested number of bytes was allocated.
 207   @retval EFI_OUT_OF_RESOURCES  The pool requested could not be allocated.
 208   @retval EFI_INVALID_PARAMETER PoolType was invalid.
 209   @retval EFI_UNSUPPORTED       In runtime.
 210
 211 **/
 212 typedef
 213 EFI_STATUS
 214 (EFIAPI *EFI_SMM_ALLOCATE_POOL) (
 215   IN EFI_SMM_BASE_PROTOCOL          *This,
 216   IN EFI_MEMORY_TYPE                PoolType,
 217   IN UINTN                          Size,
 218   OUT VOID                          **Buffer
 219   )
 220 ;
 221
 222 /**
 223   The SmmFreePool() function returns the memory specified by Buffer to the system.
 224   On return, the memory's type is EFI SMRAM Memory.  The Buffer that is freed must
 225   have been allocated by SmmAllocatePool().
 226
 227   @param  This                  Protocol instance pointer.
 228   @param  Buffer                Pointer to the buffer allocation.
 229
 230   @retval EFI_SUCCESS           The memory was returned to the system.
 231   @retval EFI_INVALID_PARAMETER Buffer was invalid.
 232   @retval EFI_UNSUPPORTED       In runtime.
 233
 234 **/
 235 typedef
 236 EFI_STATUS
 237 (EFIAPI *EFI_SMM_FREE_POOL) (
 238   IN EFI_SMM_BASE_PROTOCOL          *This,
 239   IN VOID                           *Buffer
 240   )
 241 ;
 242
 243 /**
 244   This routine tells caller if execution context is SMM or not.
 245
 246   @param  This                  Protocol instance pointer.
 247   @param  InSmm                 Whether the caller is inside SMM for IA-32 or servicing a PMI for the Itanium processor family.
 248
 249   @retval EFI_SUCCESS           The operation was successful
 250
 251 **/
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_SMM_INSIDE_OUT) (
 255   IN EFI_SMM_BASE_PROTOCOL          *This,
 256   OUT BOOLEAN                       *InSmm
 257   )
 258 ;
 259
 260 /**
 261   The GetSmstLocation() function returns the locatin of the System Management
 262   Service Table.  The use of the API is such that a driver can discover the
 263   location of the SMST in its entry point and then cache it in some driver
 264   global variable so that the SMST can be invoked in subsequent callbacks.
 265
 266   @param  This                  Protocol instance pointer.
 267   @param  Smst                  Pointer to the SMST.
 268
 269   @retval EFI_SUCCESS           The operation was successful
 270   @retval EFI_INVALID_PARAMETER Smst was invalid.
 271   @retval EFI_UNSUPPORTED       Not in SMM.
 272
 273 **/
 274 typedef
 275 EFI_STATUS
 276 (EFIAPI *EFI_SMM_GET_SMST_LOCATION) (
 277   IN EFI_SMM_BASE_PROTOCOL          *This,
 278   IN OUT EFI_SMM_SYSTEM_TABLE       **Smst
 279   )
 280 ;
 281
 282 /**
 283   @par Protocol Description:
 284   This protocol is used to install SMM handlers for support of subsequent SMI/PMI
 285   activations. This protocol is available on both IA-32 and Itanium-based systems.
 286
 287   @param Register
 288   Registers a handler to run in System Management RAM (SMRAM).
 289
 290   @param UnRegister
 291   Removes a handler from execution in SMRAM.
 292
 293   @param Communicate
 294   Sends/receives a message for a registered handler.
 295
 296   @param RegisterCallback
 297   Registers a callback from the constructor.
 298
 299   @param InSmm
 300   Detects whether the caller is inside or outside of SMM. SName
 301
 302   @param SmmAllocatePool
 303   Allocates SMRAM.
 304
 305   @param SmmFreePool
 306   Deallocates SMRAM.
 307
 308   @param GetSmstLocation
 309   Retrieves the location of the System Management System Table (SMST).
 310
 311 **/
 312 struct _EFI_SMM_BASE_PROTOCOL {
 313   EFI_SMM_REGISTER_HANDLER    Register;
 314   EFI_SMM_UNREGISTER_HANDLER  UnRegister;
 315   EFI_SMM_COMMUNICATE         Communicate;
 316   EFI_SMM_CALLBACK_SERVICE    RegisterCallback;
 317   EFI_SMM_INSIDE_OUT          InSmm;
 318   EFI_SMM_ALLOCATE_POOL       SmmAllocatePool;
 319   EFI_SMM_FREE_POOL           SmmFreePool;
 320   EFI_SMM_GET_SMST_LOCATION   GetSmstLocation;
 321 };
 322
 323 extern EFI_GUID gEfiSmmBaseProtocolGuid;
 324
 325 #endif