MdePkg/Include/Library/SmmPeriodicSmiLib.h

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