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 185