UnixPkg/TimerDxe/Timer.c

   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.c
  15
  16 Abstract:
  17
  18   UNIX Emulation Timer Architectural Protocol Driver as defined in DXE CIS
  19
  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
  23
  24 --*/
  25 #include "PiDxe.h"
  26 #include <Protocol/Timer.h>
  27 #include <Protocol/Cpu.h>
  28 #include "Timer.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>
  35 #include "UnixDxe.h"
  36 #include <Library/UnixLib.h>
  37
  38 //
  39 // Pointer to the CPU Architectural Protocol instance
  40 //
  41 EFI_CPU_ARCH_PROTOCOL   *mCpu;
  42
  43 //
  44 // The Timer Architectural Protocol that this driver produces
  45 //
  46 EFI_TIMER_ARCH_PROTOCOL mTimer = {
  47   UnixTimerDriverRegisterHandler,
  48   UnixTimerDriverSetTimerPeriod,
  49   UnixTimerDriverGetTimerPeriod,
  50   UnixTimerDriverGenerateSoftInterrupt
  51 };
  52
  53 //
  54 // The notification function to call on every timer interrupt
  55 //
  56 EFI_TIMER_NOTIFY        mTimerNotifyFunction = NULL;
  57
  58 //
  59 // The current period of the timer interrupt
  60 //
  61 UINT64                  mTimerPeriodMs;
  62
  63
  64 VOID
  65 EFIAPI
  66 TimerCallback (UINT64 DeltaMs)
  67 /*++
  68
  69 Routine Description:
  70
  71   TODO: Add function description
  72
  73 Arguments:
  74
  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
  80
  81 Returns:
  82
  83   TODO: add return values
  84
  85 --*/
  86 {
  87   EFI_TPL           OriginalTPL;
  88   EFI_TIMER_NOTIFY  CallbackFunction;
  89
  90
  91   OriginalTPL = gBS->RaiseTPL (TPL_HIGH_LEVEL);
  92
  93   if (OriginalTPL < TPL_HIGH_LEVEL) {
  94     CallbackFunction = mTimerNotifyFunction;
  95
  96     //
  97     // Only invoke the callback function if a Non-NULL handler has been
  98     // registered. Assume all other handlers are legal.
  99     //
 100     if (CallbackFunction != NULL) {
 101       CallbackFunction ((UINT64) (DeltaMs * 10000));
 102     }
 103   }
 104
 105   gBS->RestoreTPL (OriginalTPL);
 106
 107 }
 108
 109 EFI_STATUS
 110 EFIAPI
 111 UnixTimerDriverRegisterHandler (
 112   IN EFI_TIMER_ARCH_PROTOCOL           *This,
 113   IN EFI_TIMER_NOTIFY                  NotifyFunction
 114   )
 115 /*++
 116
 117 Routine Description:
 118
 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
 129   is returned.
 130
 131 Arguments:
 132
 133   This           - The EFI_TIMER_ARCH_PROTOCOL instance.
 134
 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.
 140
 141 Returns:
 142
 143   EFI_SUCCESS           - The timer handler was registered.
 144
 145   EFI_UNSUPPORTED       - The platform does not support timer interrupts.
 146
 147   EFI_ALREADY_STARTED   - NotifyFunction is not NULL, and a handler is already
 148                           registered.
 149
 150   EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not
 151                           previously registered.
 152
 153   EFI_DEVICE_ERROR      - The timer handler could not be registered.
 154
 155 --*/
 156 {
 157   //
 158   // Check for invalid parameters
 159   //
 160   if (NotifyFunction == NULL && mTimerNotifyFunction == NULL) {
 161     return EFI_INVALID_PARAMETER;
 162   }
 163
 164   if (NotifyFunction != NULL && mTimerNotifyFunction != NULL) {
 165     return EFI_ALREADY_STARTED;
 166   }
 167
 168   if (NotifyFunction == NULL) {
 169     /* Disable timer.  */
 170     gUnix->SetTimer (0, TimerCallback);
 171   } else if (mTimerNotifyFunction == NULL) {
 172     /* Enable Timer.  */
 173     gUnix->SetTimer (mTimerPeriodMs, TimerCallback);
 174   }
 175   mTimerNotifyFunction = NotifyFunction;
 176
 177   return EFI_SUCCESS;
 178 }
 179
 180 EFI_STATUS
 181 EFIAPI
 182 UnixTimerDriverSetTimerPeriod (
 183   IN EFI_TIMER_ARCH_PROTOCOL  *This,
 184   IN UINT64                   TimerPeriod
 185   )
 186 /*++
 187
 188 Routine Description:
 189
 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
 200   interrupt fires.
 201
 202 Arguments:
 203
 204   This        - The EFI_TIMER_ARCH_PROTOCOL instance.
 205
 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.
 212
 213 Returns:
 214
 215   EFI_SUCCESS      - The timer period was changed.
 216
 217   EFI_UNSUPPORTED  - The platform cannot change the period of the timer interrupt.
 218
 219   EFI_DEVICE_ERROR - The timer period could not be changed due to a device error.
 220
 221 --*/
 222 {
 223
 224   //
 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
 227   //
 228   if (TimerPeriod == 0
 229       || ((TimerPeriod > TIMER_MINIMUM_VALUE)
 230           && (TimerPeriod < TIMER_MAXIMUM_VALUE))) {
 231     mTimerPeriodMs = DivU64x32 (TimerPeriod + 5000, 10000);
 232
 233     gUnix->SetTimer (mTimerPeriodMs, TimerCallback);
 234   }
 235
 236   return EFI_SUCCESS;
 237 }
 238
 239 EFI_STATUS
 240 EFIAPI
 241 UnixTimerDriverGetTimerPeriod (
 242   IN EFI_TIMER_ARCH_PROTOCOL            *This,
 243   OUT UINT64                            *TimerPeriod
 244   )
 245 /*++
 246
 247 Routine Description:
 248
 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.
 253
 254 Arguments:
 255
 256   This        - The EFI_TIMER_ARCH_PROTOCOL instance.
 257
 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.
 260
 261 Returns:
 262
 263   EFI_SUCCESS           - The timer period was returned in TimerPeriod.
 264
 265   EFI_INVALID_PARAMETER - TimerPeriod is NULL.
 266
 267 --*/
 268 {
 269   if (TimerPeriod == NULL) {
 270     return EFI_INVALID_PARAMETER;
 271   }
 272
 273   *TimerPeriod = mTimerPeriodMs * 10000;
 274
 275   return EFI_SUCCESS;
 276 }
 277
 278 EFI_STATUS
 279 EFIAPI
 280 UnixTimerDriverGenerateSoftInterrupt (
 281   IN EFI_TIMER_ARCH_PROTOCOL  *This
 282   )
 283 /*++
 284
 285 Routine Description:
 286
 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.
 294
 295 Arguments:
 296
 297   This  -  The EFI_TIMER_ARCH_PROTOCOL instance.
 298
 299 Returns:
 300
 301   EFI_SUCCESS       - The soft timer interrupt was generated.
 302
 303   EFI_UNSUPPORTEDT  - The platform does not support the generation of soft timer interrupts.
 304
 305 --*/
 306 {
 307   return EFI_UNSUPPORTED;
 308 }
 309
 310 EFI_STATUS
 311 EFIAPI
 312 UnixTimerDriverInitialize (
 313   IN EFI_HANDLE        ImageHandle,
 314   IN EFI_SYSTEM_TABLE  *SystemTable
 315   )
 316 /*++
 317
 318 Routine Description:
 319
 320   Initialize the Timer Architectural Protocol driver
 321
 322 Arguments:
 323
 324   ImageHandle - ImageHandle of the loaded driver
 325
 326   SystemTable - Pointer to the System Table
 327
 328 Returns:
 329
 330   EFI_SUCCESS           - Timer Architectural Protocol created
 331
 332   EFI_OUT_OF_RESOURCES  - Not enough resources available to initialize driver.
 333
 334   EFI_DEVICE_ERROR      - A device error occured attempting to initialize the driver.
 335
 336 --*/
 337 {
 338   EFI_STATUS  Status;
 339   EFI_HANDLE  Handle;
 340
 341   //
 342   // Make sure the Timer Architectural Protocol is not already installed in the system
 343   //
 344   ASSERT_PROTOCOL_ALREADY_INSTALLED (NULL, &gEfiTimerArchProtocolGuid);
 345
 346   //
 347   // Get the CPU Architectural Protocol instance
 348   //
 349   Status = gBS->LocateProtocol (&gEfiCpuArchProtocolGuid, NULL, (void *)&mCpu);
 350   ASSERT_EFI_ERROR (Status);
 351
 352   //
 353   // Install the Timer Architectural Protocol onto a new handle
 354   //
 355   Handle = NULL;
 356   Status = gBS->InstallProtocolInterface (
 357                   &Handle,
 358                   &gEfiTimerArchProtocolGuid,
 359                   EFI_NATIVE_INTERFACE,
 360                   &mTimer
 361                   );
 362   if (EFI_ERROR (Status)) {
 363     return Status;
 364   }
 365
 366   //
 367   // Start the timer thread at the default timer period
 368   //
 369   Status = mTimer.SetTimerPeriod (&mTimer, DEFAULT_TIMER_TICK_DURATION);
 370   if (EFI_ERROR (Status)) {
 371     return Status;
 372   }
 373
 374   return EFI_SUCCESS;
 375 }