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