MdePkg/Include/Library/SmmPeriodicSmiLib.h

   1 /** @file
   2   Provides services to enable and disable periodic SMI handlers.
   3
   4 Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __PERIODIC_SMI_LIB_H__
  16 #define __PERIODIC_SMI_LIB_H__
  17
  18 #define PERIODIC_SMI_LIBRARY_ANY_CPU  0xffffffff
  19
  20 /**
  21   This function returns a pointer to a table of supported periodic
  22   SMI tick periods in 100 ns units sorted from largest to smallest.
  23   The table contains a array of UINT64 values terminated by a tick
  24   period value of 0.  The returned table must be treated as read-only
  25   data and must not be freed.
  26
  27   @return  A pointer to a table of UINT64 tick period values in
  28            100ns units sorted from largest to smallest terminated
  29            by a tick period of 0.
  30
  31 **/
  32 UINT64 *
  33 EFIAPI
  34 PeriodicSmiSupportedTickPeriod (
  35   VOID
  36   );
  37
  38 /**
  39   This function returns the time in 100ns units since the periodic SMI
  40   handler function was called.  If the periodic SMI handler was resumed
  41   through PeriodicSmiYield(), then the time returned is the time in
  42   100ns units since PeriodicSmiYield() returned.
  43
  44   @return  The actual time in 100ns units that the periodic SMI handler
  45            has been executing.  If this function is not called from within
  46            an enabled periodic SMI handler, then 0 is returned.
  47
  48 **/
  49 UINT64
  50 EFIAPI
  51 PeriodicSmiExecutionTime (
  52   VOID
  53   );
  54
  55 /**
  56   This function returns control back to the SMM Foundation.  When the next
  57   periodic SMI for the currently executing handler is triggered, the periodic
  58   SMI handler will restarted from its registered DispatchFunction entry point.
  59   If this function is not called from within an enabled periodic SMI handler,
  60   then control is returned to the calling function.
  61
  62 **/
  63 VOID
  64 EFIAPI
  65 PeriodicSmiExit (
  66   VOID
  67   );
  68
  69 /**
  70   This function yields control back to the SMM Foundation.  When the next
  71   periodic SMI for the currently executing handler is triggered, the periodic
  72   SMI handler will be resumed and this function will return.  Use of this
  73   function requires a seperate stack for the periodic SMI handler.  A non zero
  74   stack size must be specified in PeriodicSmiEnable() for this function to be
  75   used.
  76
  77   If the stack size passed into PeriodicSmiEnable() was zero, the 0 is returned.
  78
  79   If this function is not called from within an enabled periodic SMI handler,
  80   then 0 is returned.
  81
  82   @return  The actual time in 100ns units elapsed since this function was
  83            called.  A value of 0 indicates an unknown amount of time.
  84
  85 **/
  86 UINT64
  87 EFIAPI
  88 PeriodicSmiYield (
  89   VOID
  90   );
  91
  92 /**
  93   This function is a prototype for a periodic SMI handler function
  94   that may be enabled with PeriodicSmiEnable() and disabled with
  95   PeriodicSmiDisable().
  96
  97   @param[in] Context      Content registered with PeriodicSmiEnable().
  98   @param[in] ElapsedTime  The actual time in 100ns units elapsed since
  99                           this function was called.  A value of 0 indicates
 100                           an unknown amount of time.
 101
 102 **/
 103 typedef
 104 VOID
 105 (EFIAPI *PERIODIC_SMI_LIBRARY_HANDLER) (
 106   IN CONST VOID  *Context OPTIONAL,
 107   IN UINT64      ElapsedTime
 108   );
 109
 110 /**
 111   This function enables a periodic SMI handler.
 112
 113   @param[in, out] DispatchHandle   A pointer to the handle associated with the
 114                                    enabled periodic SMI handler.  This is an
 115                                    optional parameter that may be NULL.  If it is
 116                                    NULL, then the handle will not be returned,
 117                                    which means that the periodic SMI handler can
 118                                    never be disabled.
 119   @param[in]     DispatchFunction  A pointer to a periodic SMI handler function.
 120   @param[in]     Context           Optional content to pass into DispatchFunction.
 121   @param[in]     TickPeriod        The requested tick period in 100ns units that
 122                                    control should be givien to the periodic SMI
 123                                    handler.  Must be one of the supported values
 124                                    returned by PeriodicSmiSupportedPickPeriod().
 125   @param[in]     Cpu               Specifies the CPU that is required to execute
 126                                    the periodic SMI handler.  If Cpu is
 127                                    PERIODIC_SMI_LIBRARY_ANY_CPU, then the periodic
 128                                    SMI handler will always be executed on the SMST
 129                                    CurrentlyExecutingCpu, which may vary across
 130                                    periodic SMIs.  If Cpu is between 0 and the SMST
 131                                    NumberOfCpus, then the periodic SMI will always
 132                                    be executed on the requested CPU.
 133   @param[in]     StackSize         The size, in bytes, of the stack to allocate for
 134                                    use by the periodic SMI handler.  If 0, then the
 135                                    default stack will be used.
 136
 137   @retval EFI_INVALID_PARAMETER  DispatchFunction is NULL.
 138   @retval EFI_UNSUPPORTED        TickPeriod is not a supported tick period.  The
 139                                  supported tick periods can be retrieved using
 140                                  PeriodicSmiSupportedTickPeriod().
 141   @retval EFI_INVALID_PARAMETER  Cpu is not PERIODIC_SMI_LIBRARY_ANY_CPU or in
 142                                  the range 0 to SMST NumberOfCpus.
 143   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to enable the
 144                                  periodic SMI handler.
 145   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the
 146                                  stack speficied by StackSize.
 147   @retval EFI_SUCCESS            The periodic SMI handler was enabled.
 148
 149 **/
 150 EFI_STATUS
 151 EFIAPI
 152 PeriodicSmiEnable (
 153   IN OUT EFI_HANDLE                    *DispatchHandle,    OPTIONAL
 154   IN     PERIODIC_SMI_LIBRARY_HANDLER  DispatchFunction,
 155   IN     CONST VOID                    *Context,           OPTIONAL
 156   IN     UINT64                        TickPeriod,
 157   IN     UINTN                         Cpu,
 158   IN     UINTN                         StackSize
 159   );
 160
 161 /**
 162   This function disables a periodic SMI handler that has been previously
 163   enabled with PeriodicSmiEnable().
 164
 165   @param[in] DispatchHandle  A handle associated with a previously enabled periodic
 166                              SMI handler.  This is an optional parameter that may
 167                              be NULL.  If it is NULL, then the active periodic SMI
 168                              handlers is disabled.
 169
 170   @retval FALSE  DispatchHandle is NULL and there is no active periodic SMI handler.
 171   @retval FALSE  The periodic SMI handler specified by DispatchHandle has
 172                  not been enabled with PeriodicSmiEnable().
 173   @retval TRUE   The periodic SMI handler specified by DispatchHandle has
 174                  been disabled.  If DispatchHandle is NULL, then the active
 175                  periodic SMI handler has been disabled.
 176
 177 **/
 178 BOOLEAN
 179 EFIAPI
 180 PeriodicSmiDisable (
 181   IN EFI_HANDLE  DispatchHandle    OPTIONAL
 182   );
 183
 184 #endif