3 Copyright (c) 2004, Intel Corporation
4 All rights reserved. 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
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.
18 UNIX Emulation Timer Architectural Protocol Driver as defined in DXE CIS
20 This Timer module uses an UNIX Thread to simulate the timer-tick driven
21 timer service. In the future, the Thread creation should possibly be
22 abstracted by the CPU architectural protocol
29 // Pointer to the CPU Architectural Protocol instance
31 EFI_CPU_ARCH_PROTOCOL
*mCpu
;
34 // The Timer Architectural Protocol that this driver produces
36 EFI_TIMER_ARCH_PROTOCOL mTimer
= {
37 UnixTimerDriverRegisterHandler
,
38 UnixTimerDriverSetTimerPeriod
,
39 UnixTimerDriverGetTimerPeriod
,
40 UnixTimerDriverGenerateSoftInterrupt
44 // The notification function to call on every timer interrupt
46 EFI_TIMER_NOTIFY mTimerNotifyFunction
= NULL
;
49 // The current period of the timer interrupt
54 // The timer value from the last timer interrupt
59 TimerCallback (UINT64 DeltaMs
)
64 TODO: Add function description
68 wTimerID - TODO: add argument description
69 msg - TODO: add argument description
70 dwUser - TODO: add argument description
71 dw1 - TODO: add argument description
72 dw2 - TODO: add argument description
76 TODO: add return values
81 EFI_TIMER_NOTIFY CallbackFunction
;
84 OriginalTPL
= gBS
->RaiseTPL (EFI_TPL_HIGH_LEVEL
);
86 CallbackFunction
= mTimerNotifyFunction
;
89 // Only invoke the callback function if a Non-NULL handler has been
90 // registered. Assume all other handlers are legal.
92 if (CallbackFunction
!= NULL
) {
93 CallbackFunction ((UINT64
) (DeltaMs
* 10000));
96 gBS
->RestoreTPL (OriginalTPL
);
102 UnixTimerDriverRegisterHandler (
103 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
104 IN EFI_TIMER_NOTIFY NotifyFunction
110 This function registers the handler NotifyFunction so it is called every time
111 the timer interrupt fires. It also passes the amount of time since the last
112 handler call to the NotifyFunction. If NotifyFunction is NULL, then the
113 handler is unregistered. If the handler is registered, then EFI_SUCCESS is
114 returned. If the CPU does not support registering a timer interrupt handler,
115 then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler
116 when a handler is already registered, then EFI_ALREADY_STARTED is returned.
117 If an attempt is made to unregister a handler when a handler is not registered,
118 then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to
119 register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR
124 This - The EFI_TIMER_ARCH_PROTOCOL instance.
126 NotifyFunction - The function to call when a timer interrupt fires. This
127 function executes at TPL_HIGH_LEVEL. The DXE Core will
128 register a handler for the timer interrupt, so it can know
129 how much time has passed. This information is used to
130 signal timer based events. NULL will unregister the handler.
134 EFI_SUCCESS - The timer handler was registered.
136 EFI_UNSUPPORTED - The platform does not support timer interrupts.
138 EFI_ALREADY_STARTED - NotifyFunction is not NULL, and a handler is already
141 EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not
142 previously registered.
144 EFI_DEVICE_ERROR - The timer handler could not be registered.
149 // Check for invalid parameters
151 if (NotifyFunction
== NULL
&& mTimerNotifyFunction
== NULL
) {
152 return EFI_INVALID_PARAMETER
;
155 if (NotifyFunction
!= NULL
&& mTimerNotifyFunction
!= NULL
) {
156 return EFI_ALREADY_STARTED
;
159 if (NotifyFunction
== NULL
) {
161 gUnix
->SetTimer (0, TimerCallback
);
162 } else if (mTimerNotifyFunction
== NULL
) {
164 gUnix
->SetTimer (mTimerPeriod
* 10, TimerCallback
);
166 mTimerNotifyFunction
= NotifyFunction
;
173 UnixTimerDriverSetTimerPeriod (
174 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
175 IN UINT64 TimerPeriod
181 This function adjusts the period of timer interrupts to the value specified
182 by TimerPeriod. If the timer period is updated, then the selected timer
183 period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned. If
184 the timer hardware is not programmable, then EFI_UNSUPPORTED is returned.
185 If an error occurs while attempting to update the timer period, then the
186 timer hardware will be put back in its state prior to this call, and
187 EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt
188 is disabled. This is not the same as disabling the CPU's interrupts.
189 Instead, it must either turn off the timer hardware, or it must adjust the
190 interrupt controller so that a CPU interrupt is not generated when the timer
195 This - The EFI_TIMER_ARCH_PROTOCOL instance.
197 TimerPeriod - The rate to program the timer interrupt in 100 nS units. If
198 the timer hardware is not programmable, then EFI_UNSUPPORTED is
199 returned. If the timer is programmable, then the timer period
200 will be rounded up to the nearest timer period that is supported
201 by the timer hardware. If TimerPeriod is set to 0, then the
202 timer interrupts will be disabled.
206 EFI_SUCCESS - The timer period was changed.
208 EFI_UNSUPPORTED - The platform cannot change the period of the timer interrupt.
210 EFI_DEVICE_ERROR - The timer period could not be changed due to a device error.
216 // If TimerPeriod is 0, then the timer thread should be canceled
217 // If the TimerPeriod is valid, then create and/or adjust the period of the timer thread
220 || ((TimerPeriod
> TIMER_MINIMUM_VALUE
)
221 && (TimerPeriod
< TIMER_MAXIMUM_VALUE
))) {
222 mTimerPeriod
= TimerPeriod
;
224 gUnix
->SetTimer (TimerPeriod
* 10, TimerCallback
);
232 UnixTimerDriverGetTimerPeriod (
233 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
234 OUT UINT64
*TimerPeriod
240 This function retrieves the period of timer interrupts in 100 ns units,
241 returns that value in TimerPeriod, and returns EFI_SUCCESS. If TimerPeriod
242 is NULL, then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is
243 returned, then the timer is currently disabled.
247 This - The EFI_TIMER_ARCH_PROTOCOL instance.
249 TimerPeriod - A pointer to the timer period to retrieve in 100 ns units. If
250 0 is returned, then the timer is currently disabled.
254 EFI_SUCCESS - The timer period was returned in TimerPeriod.
256 EFI_INVALID_PARAMETER - TimerPeriod is NULL.
260 if (TimerPeriod
== NULL
) {
261 return EFI_INVALID_PARAMETER
;
264 *TimerPeriod
= mTimerPeriod
;
271 UnixTimerDriverGenerateSoftInterrupt (
272 IN EFI_TIMER_ARCH_PROTOCOL
*This
278 This function generates a soft timer interrupt. If the platform does not support soft
279 timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned.
280 If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler()
281 service, then a soft timer interrupt will be generated. If the timer interrupt is
282 enabled when this service is called, then the registered handler will be invoked. The
283 registered handler should not be able to distinguish a hardware-generated timer
284 interrupt from a software-generated timer interrupt.
288 This - The EFI_TIMER_ARCH_PROTOCOL instance.
292 EFI_SUCCESS - The soft timer interrupt was generated.
294 EFI_UNSUPPORTEDT - The platform does not support the generation of soft timer interrupts.
298 return EFI_UNSUPPORTED
;
303 UnixTimerDriverInitialize (
304 IN EFI_HANDLE ImageHandle
,
305 IN EFI_SYSTEM_TABLE
*SystemTable
311 Initialize the Timer Architectural Protocol driver
315 ImageHandle - ImageHandle of the loaded driver
317 SystemTable - Pointer to the System Table
321 EFI_SUCCESS - Timer Architectural Protocol created
323 EFI_OUT_OF_RESOURCES - Not enough resources available to initialize driver.
325 EFI_DEVICE_ERROR - A device error occured attempting to initialize the driver.
333 // Make sure the Timer Architectural Protocol is not already installed in the system
335 ASSERT_PROTOCOL_ALREADY_INSTALLED (NULL
, &gEfiTimerArchProtocolGuid
);
338 // Get the CPU Architectural Protocol instance
340 Status
= gBS
->LocateProtocol (&gEfiCpuArchProtocolGuid
, NULL
, (void *)&mCpu
);
341 ASSERT_EFI_ERROR (Status
);
344 // Install the Timer Architectural Protocol onto a new handle
347 Status
= gBS
->InstallProtocolInterface (
349 &gEfiTimerArchProtocolGuid
,
350 EFI_NATIVE_INTERFACE
,
353 if (EFI_ERROR (Status
)) {