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