IntelFrameworkPkg/Include/Protocol/SmmBase.h

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