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