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
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
26 #include <Protocol/Timer.h>
27 #include <Protocol/Cpu.h>
29 #include <Library/BaseLib.h>
30 #include <Library/DebugLib.h>
31 #include <Library/UefiLib.h>
32 #include <Library/UefiDriverEntryPoint.h>
33 #include <Library/MemoryAllocationLib.h>
34 #include <Library/UefiBootServicesTableLib.h>
36 #include <Library/UnixLib.h>
39 // Pointer to the CPU Architectural Protocol instance
41 EFI_CPU_ARCH_PROTOCOL
*mCpu
;
44 // The Timer Architectural Protocol that this driver produces
46 EFI_TIMER_ARCH_PROTOCOL mTimer
= {
47 UnixTimerDriverRegisterHandler
,
48 UnixTimerDriverSetTimerPeriod
,
49 UnixTimerDriverGetTimerPeriod
,
50 UnixTimerDriverGenerateSoftInterrupt
54 // The notification function to call on every timer interrupt
56 EFI_TIMER_NOTIFY mTimerNotifyFunction
= NULL
;
59 // The current period of the timer interrupt
61 UINT64 mTimerPeriodMs
;
66 TimerCallback (UINT64 DeltaMs
)
71 TODO: Add function description
75 wTimerID - TODO: add argument description
76 msg - TODO: add argument description
77 dwUser - TODO: add argument description
78 dw1 - TODO: add argument description
79 dw2 - TODO: add argument description
83 TODO: add return values
88 EFI_TIMER_NOTIFY CallbackFunction
;
91 OriginalTPL
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
93 if (OriginalTPL
< TPL_HIGH_LEVEL
) {
94 CallbackFunction
= mTimerNotifyFunction
;
97 // Only invoke the callback function if a Non-NULL handler has been
98 // registered. Assume all other handlers are legal.
100 if (CallbackFunction
!= NULL
) {
101 CallbackFunction ((UINT64
) (DeltaMs
* 10000));
105 gBS
->RestoreTPL (OriginalTPL
);
111 UnixTimerDriverRegisterHandler (
112 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
113 IN EFI_TIMER_NOTIFY NotifyFunction
119 This function registers the handler NotifyFunction so it is called every time
120 the timer interrupt fires. It also passes the amount of time since the last
121 handler call to the NotifyFunction. If NotifyFunction is NULL, then the
122 handler is unregistered. If the handler is registered, then EFI_SUCCESS is
123 returned. If the CPU does not support registering a timer interrupt handler,
124 then EFI_UNSUPPORTED is returned. If an attempt is made to register a handler
125 when a handler is already registered, then EFI_ALREADY_STARTED is returned.
126 If an attempt is made to unregister a handler when a handler is not registered,
127 then EFI_INVALID_PARAMETER is returned. If an error occurs attempting to
128 register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR
133 This - The EFI_TIMER_ARCH_PROTOCOL instance.
135 NotifyFunction - The function to call when a timer interrupt fires. This
136 function executes at TPL_HIGH_LEVEL. The DXE Core will
137 register a handler for the timer interrupt, so it can know
138 how much time has passed. This information is used to
139 signal timer based events. NULL will unregister the handler.
143 EFI_SUCCESS - The timer handler was registered.
145 EFI_UNSUPPORTED - The platform does not support timer interrupts.
147 EFI_ALREADY_STARTED - NotifyFunction is not NULL, and a handler is already
150 EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not
151 previously registered.
153 EFI_DEVICE_ERROR - The timer handler could not be registered.
158 // Check for invalid parameters
160 if (NotifyFunction
== NULL
&& mTimerNotifyFunction
== NULL
) {
161 return EFI_INVALID_PARAMETER
;
164 if (NotifyFunction
!= NULL
&& mTimerNotifyFunction
!= NULL
) {
165 return EFI_ALREADY_STARTED
;
168 if (NotifyFunction
== NULL
) {
170 gUnix
->SetTimer (0, TimerCallback
);
171 } else if (mTimerNotifyFunction
== NULL
) {
173 gUnix
->SetTimer (mTimerPeriodMs
, TimerCallback
);
175 mTimerNotifyFunction
= NotifyFunction
;
182 UnixTimerDriverSetTimerPeriod (
183 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
184 IN UINT64 TimerPeriod
190 This function adjusts the period of timer interrupts to the value specified
191 by TimerPeriod. If the timer period is updated, then the selected timer
192 period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned. If
193 the timer hardware is not programmable, then EFI_UNSUPPORTED is returned.
194 If an error occurs while attempting to update the timer period, then the
195 timer hardware will be put back in its state prior to this call, and
196 EFI_DEVICE_ERROR is returned. If TimerPeriod is 0, then the timer interrupt
197 is disabled. This is not the same as disabling the CPU's interrupts.
198 Instead, it must either turn off the timer hardware, or it must adjust the
199 interrupt controller so that a CPU interrupt is not generated when the timer
204 This - The EFI_TIMER_ARCH_PROTOCOL instance.
206 TimerPeriod - The rate to program the timer interrupt in 100 nS units. If
207 the timer hardware is not programmable, then EFI_UNSUPPORTED is
208 returned. If the timer is programmable, then the timer period
209 will be rounded up to the nearest timer period that is supported
210 by the timer hardware. If TimerPeriod is set to 0, then the
211 timer interrupts will be disabled.
215 EFI_SUCCESS - The timer period was changed.
217 EFI_UNSUPPORTED - The platform cannot change the period of the timer interrupt.
219 EFI_DEVICE_ERROR - The timer period could not be changed due to a device error.
225 // If TimerPeriod is 0, then the timer thread should be canceled
226 // If the TimerPeriod is valid, then create and/or adjust the period of the timer thread
229 || ((TimerPeriod
> TIMER_MINIMUM_VALUE
)
230 && (TimerPeriod
< TIMER_MAXIMUM_VALUE
))) {
231 mTimerPeriodMs
= DivU64x32 (TimerPeriod
+ 5000, 10000);
233 gUnix
->SetTimer (mTimerPeriodMs
, TimerCallback
);
241 UnixTimerDriverGetTimerPeriod (
242 IN EFI_TIMER_ARCH_PROTOCOL
*This
,
243 OUT UINT64
*TimerPeriod
249 This function retrieves the period of timer interrupts in 100 ns units,
250 returns that value in TimerPeriod, and returns EFI_SUCCESS. If TimerPeriod
251 is NULL, then EFI_INVALID_PARAMETER is returned. If a TimerPeriod of 0 is
252 returned, then the timer is currently disabled.
256 This - The EFI_TIMER_ARCH_PROTOCOL instance.
258 TimerPeriod - A pointer to the timer period to retrieve in 100 ns units. If
259 0 is returned, then the timer is currently disabled.
263 EFI_SUCCESS - The timer period was returned in TimerPeriod.
265 EFI_INVALID_PARAMETER - TimerPeriod is NULL.
269 if (TimerPeriod
== NULL
) {
270 return EFI_INVALID_PARAMETER
;
273 *TimerPeriod
= mTimerPeriodMs
* 10000;
280 UnixTimerDriverGenerateSoftInterrupt (
281 IN EFI_TIMER_ARCH_PROTOCOL
*This
287 This function generates a soft timer interrupt. If the platform does not support soft
288 timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned.
289 If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler()
290 service, then a soft timer interrupt will be generated. If the timer interrupt is
291 enabled when this service is called, then the registered handler will be invoked. The
292 registered handler should not be able to distinguish a hardware-generated timer
293 interrupt from a software-generated timer interrupt.
297 This - The EFI_TIMER_ARCH_PROTOCOL instance.
301 EFI_SUCCESS - The soft timer interrupt was generated.
303 EFI_UNSUPPORTEDT - The platform does not support the generation of soft timer interrupts.
307 return EFI_UNSUPPORTED
;
312 UnixTimerDriverInitialize (
313 IN EFI_HANDLE ImageHandle
,
314 IN EFI_SYSTEM_TABLE
*SystemTable
320 Initialize the Timer Architectural Protocol driver
324 ImageHandle - ImageHandle of the loaded driver
326 SystemTable - Pointer to the System Table
330 EFI_SUCCESS - Timer Architectural Protocol created
332 EFI_OUT_OF_RESOURCES - Not enough resources available to initialize driver.
334 EFI_DEVICE_ERROR - A device error occured attempting to initialize the driver.
342 // Make sure the Timer Architectural Protocol is not already installed in the system
344 ASSERT_PROTOCOL_ALREADY_INSTALLED (NULL
, &gEfiTimerArchProtocolGuid
);
347 // Get the CPU Architectural Protocol instance
349 Status
= gBS
->LocateProtocol (&gEfiCpuArchProtocolGuid
, NULL
, (void *)&mCpu
);
350 ASSERT_EFI_ERROR (Status
);
353 // Install the Timer Architectural Protocol onto a new handle
356 Status
= gBS
->InstallProtocolInterface (
358 &gEfiTimerArchProtocolGuid
,
359 EFI_NATIVE_INTERFACE
,
362 if (EFI_ERROR (Status
)) {
367 // Start the timer thread at the default timer period
369 Status
= mTimer
.SetTimerPeriod (&mTimer
, DEFAULT_TIMER_TICK_DURATION
);
370 if (EFI_ERROR (Status
)) {