1 /*++ 2 3 Copyright (c) 2004, Intel Corporation. All rights reserved.<BR> 4 This program and the accompanying materials 5 are licensed and made available under the terms and conditions of the BSD License 6 which accompanies this distribution. The full text of the license may be found at 7 http://opensource.org/licenses/bsd-license.php 8 9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 11 12 Module Name: 13 14 Timer.h 15 16 Abstract: 17 18 Timer Architectural Protocol as defined in the DXE CIS 19 20 This code is used to provide the timer tick for the DXE core. 21 22 --*/ 23 24 #ifndef _ARCH_PROTOCOL_TIMER_H_ 25 #define _ARCH_PROTOCOL_TIMER_H_ 26 27 // 28 // Global ID for the Timer Architectural Protocol 29 // 30 #define EFI_TIMER_ARCH_PROTOCOL_GUID \ 31 { 0x26baccb3, 0x6f42, 0x11d4, {0xbc, 0xe7, 0x0, 0x80, 0xc7, 0x3c, 0x88, 0x81} } 32 33 // 34 // Declare forward reference for the Timer Architectural Protocol 35 // 36 EFI_FORWARD_DECLARATION (EFI_TIMER_ARCH_PROTOCOL); 37 38 typedef 39 VOID 40 (EFIAPI *EFI_TIMER_NOTIFY) ( 41 IN UINT64 Time 42 ); 43 /*++ 44 45 Routine Description: 46 47 This function of this type is called when a timer interrupt fires. This 48 function executes at TPL_HIGH_LEVEL. The DXE Core will register a funtion 49 of tyis type to be called for the timer interrupt, so it can know how much 50 time has passed. This information is used to signal timer based events. 51 52 Arguments: 53 54 Time - Time since the last timer interrupt in 100 ns units. This will 55 typically be TimerPeriod, but if a timer interrupt is missed, and the 56 EFI_TIMER_ARCH_PROTOCOL driver can detect missed interrupts, then Time 57 will contain the actual amount of time since the last interrupt. 58 59 Returns: 60 61 None. 62 63 --*/ 64 65 typedef 66 EFI_STATUS 67 (EFIAPI *EFI_TIMER_REGISTER_HANDLER) ( 68 IN EFI_TIMER_ARCH_PROTOCOL *This, 69 IN EFI_TIMER_NOTIFY NotifyFunction 70 ); 71 /*++ 72 73 Routine Description: 74 75 This function registers the handler NotifyFunction so it is called every time 76 the timer interrupt fires. It also passes the amount of time since the last 77 handler call to the NotifyFunction. If NotifyFunction is NULL, then the 78 handler is unregistered. If the handler is registered, then EFI_SUCCESS is 79 returned. If the CPU does not support registering a timer interrupt handler, 80 then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler 81 when a handler is already registered, then EFI_ALREADY_STARTED is returned. 82 If an attempt is made to unregister a handler when a handler is not registered, 83 then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to 84 register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR 85 is returned. 86 87 Arguments: 88 89 This - The EFI_TIMER_ARCH_PROTOCOL instance. 90 91 NotifyFunction - The function to call when a timer interrupt fires. This 92 function executes at TPL_HIGH_LEVEL. The DXE Core will 93 register a handler for the timer interrupt, so it can know 94 how much time has passed. This information is used to 95 signal timer based events. NULL will unregister the handler. 96 97 Returns: 98 99 EFI_SUCCESS - The timer handler was registered. 100 101 EFI_UNSUPPORTED - The platform does not support timer interrupts. 102 103 EFI_ALREADY_STARTED - NotifyFunction is not NULL, and a handler is already 104 registered. 105 106 EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not 107 previously registered. 108 109 EFI_DEVICE_ERROR - The timer handler could not be registered. 110 111 --*/ 112 113 typedef 114 EFI_STATUS 115 (EFIAPI *EFI_TIMER_SET_TIMER_PERIOD) ( 116 IN EFI_TIMER_ARCH_PROTOCOL *This, 117 IN UINT64 TimerPeriod 118 ); 119 /*++ 120 121 Routine Description: 122 123 This function adjusts the period of timer interrupts to the value specified 124 by TimerPeriod. If the timer period is updated, then the selected timer 125 period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned. If 126 the timer hardware is not programmable, then EFI_UNSUPPORTED is returned. 127 If an error occurs while attempting to update the timer period, then the 128 timer hardware will be put back in its state prior to this call, and 129 EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt 130 is disabled. This is not the same as disabling the CPU's interrupts. 131 Instead, it must either turn off the timer hardware, or it must adjust the 132 interrupt controller so that a CPU interrupt is not generated when the timer 133 interrupt fires. 134 135 Arguments: 136 137 This - The EFI_TIMER_ARCH_PROTOCOL instance. 138 139 TimerPeriod - The rate to program the timer interrupt in 100 nS units. If 140 the timer hardware is not programmable, then EFI_UNSUPPORTED is 141 returned. If the timer is programmable, then the timer period 142 will be rounded up to the nearest timer period that is supported 143 by the timer hardware. If TimerPeriod is set to 0, then the 144 timer interrupts will be disabled. 145 146 Returns: 147 148 EFI_SUCCESS - The timer period was changed. 149 150 EFI_UNSUPPORTED - The platform cannot change the period of the timer interrupt. 151 152 EFI_DEVICE_ERROR - The timer period could not be changed due to a device error. 153 154 --*/ 155 156 typedef 157 EFI_STATUS 158 (EFIAPI *EFI_TIMER_GET_TIMER_PERIOD) ( 159 IN EFI_TIMER_ARCH_PROTOCOL *This, 160 OUT UINT64 *TimerPeriod 161 ); 162 /*++ 163 164 Routine Description: 165 166 This function retrieves the period of timer interrupts in 100 ns units, 167 returns that value in TimerPeriod, and returns EFI_SUCCESS. If TimerPeriod 168 is NULL, then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is 169 returned, then the timer is currently disabled. 170 171 Arguments: 172 173 This - The EFI_TIMER_ARCH_PROTOCOL instance. 174 175 TimerPeriod - A pointer to the timer period to retrieve in 100 ns units. If 176 0 is returned, then the timer is currently disabled. 177 178 Returns: 179 180 EFI_SUCCESS - The timer period was returned in TimerPeriod. 181 182 EFI_INVALID_PARAMETER - TimerPeriod is NULL. 183 184 --*/ 185 186 typedef 187 EFI_STATUS 188 (EFIAPI *EFI_TIMER_GENERATE_SOFT_INTERRUPT) ( 189 IN EFI_TIMER_ARCH_PROTOCOL *This 190 ); 191 /*++ 192 193 Routine Description: 194 195 This function generates a soft timer interrupt. If the platform does not support soft 196 timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned. 197 If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler() 198 service, then a soft timer interrupt will be generated. If the timer interrupt is 199 enabled when this service is called, then the registered handler will be invoked. The 200 registered handler should not be able to distinguish a hardware-generated timer 201 interrupt from a software-generated timer interrupt. 202 203 Arguments: 204 205 This - The EFI_TIMER_ARCH_PROTOCOL instance. 206 207 Returns: 208 209 EFI_SUCCESS - The soft timer interrupt was generated. 210 211 EFI_UNSUPPORTEDT - The platform does not support the generation of soft timer interrupts. 212 213 --*/ 214 215 // 216 // Interface stucture for the Timer Architectural Protocol 217 // 218 struct _EFI_TIMER_ARCH_PROTOCOL { 219 EFI_TIMER_REGISTER_HANDLER RegisterHandler; 220 EFI_TIMER_SET_TIMER_PERIOD SetTimerPeriod; 221 EFI_TIMER_GET_TIMER_PERIOD GetTimerPeriod; 222 EFI_TIMER_GENERATE_SOFT_INTERRUPT GenerateSoftInterrupt; 223 }; 224 225 /*++ 226 227 Protocol Description: 228 This protocol provides the services to initialize a periodic timer 229 interrupt, and to register a handler that is called each time the timer 230 interrupt fires. It may also provide a service to adjust the rate of the 231 periodic timer interrupt. When a timer interrupt occurs, the handler is 232 passed the amount of time that has passed since the previous timer 233 interrupt. 234 235 Parameters: 236 237 RegisterHandler - Registers a handler that will be called each time the 238 timer interrupt fires. TimerPeriod defines the minimum 239 time between timer interrupts, so TimerPeriod will also 240 be the minimum time between calls to the registered 241 handler. 242 243 SetTimerPeriod - Sets the period of the timer interrupt in 100 nS units. 244 This function is optional, and may return EFI_UNSUPPORTED. 245 If this function is supported, then the timer period will 246 be rounded up to the nearest supported timer period. 247 248 GetTimerPeriod - Retrieves the period of the timer interrupt in 100 nS units. 249 250 GenerateSoftInterrupt - 251 Generates a soft timer interrupt that simulates the firing of 252 the timer interrupt. This service can be used to invoke the 253 registered handler if the timer interrupt has been masked for 254 a period of time. 255 256 --*/ 257 258 extern EFI_GUID gEfiTimerArchProtocolGuid; 259 260 #endif 261
