OvmfPkg/8254TimerDxe/Timer.c

   1 /** @file
   2   Timer Architectural Protocol as defined in the DXE CIS
   3
   4 Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #include <Library/NestedInterruptTplLib.h>
  10
  11 #include "Timer.h"
  12
  13 //
  14 // The handle onto which the Timer Architectural Protocol will be installed
  15 //
  16 EFI_HANDLE  mTimerHandle = NULL;
  17
  18 //
  19 // The Timer Architectural Protocol that this driver produces
  20 //
  21 EFI_TIMER_ARCH_PROTOCOL  mTimer = {
  22   TimerDriverRegisterHandler,
  23   TimerDriverSetTimerPeriod,
  24   TimerDriverGetTimerPeriod,
  25   TimerDriverGenerateSoftInterrupt
  26 };
  27
  28 //
  29 // Pointer to the CPU Architectural Protocol instance
  30 //
  31 EFI_CPU_ARCH_PROTOCOL  *mCpu;
  32
  33 //
  34 // Pointer to the Legacy 8259 Protocol instance
  35 //
  36 EFI_LEGACY_8259_PROTOCOL  *mLegacy8259;
  37
  38 //
  39 // The notification function to call on every timer interrupt.
  40 // A bug in the compiler prevents us from initializing this here.
  41 //
  42 EFI_TIMER_NOTIFY  mTimerNotifyFunction;
  43
  44 //
  45 // The current period of the timer interrupt
  46 //
  47 volatile UINT64  mTimerPeriod = 0;
  48
  49 //
  50 // Worker Functions
  51 //
  52
  53 /**
  54   Sets the counter value for Timer #0 in a legacy 8254 timer.
  55
  56   @param Count    The 16-bit counter value to program into Timer #0 of the legacy 8254 timer.
  57 **/
  58 VOID
  59 SetPitCount (
  60   IN UINT16  Count
  61   )
  62 {
  63   IoWrite8 (TIMER_CONTROL_PORT, 0x36);
  64   IoWrite8 (TIMER0_COUNT_PORT, (UINT8)(Count & 0xff));
  65   IoWrite8 (TIMER0_COUNT_PORT, (UINT8)((Count >> 8) & 0xff));
  66 }
  67
  68 /**
  69   8254 Timer #0 Interrupt Handler.
  70
  71   @param InterruptType    The type of interrupt that occurred
  72   @param SystemContext    A pointer to the system context when the interrupt occurred
  73 **/
  74 VOID
  75 EFIAPI
  76 TimerInterruptHandler (
  77   IN EFI_EXCEPTION_TYPE  InterruptType,
  78   IN EFI_SYSTEM_CONTEXT  SystemContext
  79   )
  80 {
  81   STATIC NESTED_INTERRUPT_STATE  NestedInterruptState;
  82   EFI_TPL                        OriginalTPL;
  83
  84   OriginalTPL = NestedInterruptRaiseTPL ();
  85
  86   mLegacy8259->EndOfInterrupt (mLegacy8259, Efi8259Irq0);
  87
  88   if (mTimerNotifyFunction != NULL) {
  89     //
  90     // @bug : This does not handle missed timer interrupts
  91     //
  92     mTimerNotifyFunction (mTimerPeriod);
  93   }
  94
  95   NestedInterruptRestoreTPL (OriginalTPL, SystemContext, &NestedInterruptState);
  96 }
  97
  98 /**
  99
 100   This function registers the handler NotifyFunction so it is called every time
 101   the timer interrupt fires.  It also passes the amount of time since the last
 102   handler call to the NotifyFunction.  If NotifyFunction is NULL, then the
 103   handler is unregistered.  If the handler is registered, then EFI_SUCCESS is
 104   returned.  If the CPU does not support registering a timer interrupt handler,
 105   then EFI_UNSUPPORTED is returned.  If an attempt is made to register a handler
 106   when a handler is already registered, then EFI_ALREADY_STARTED is returned.
 107   If an attempt is made to unregister a handler when a handler is not registered,
 108   then EFI_INVALID_PARAMETER is returned.  If an error occurs attempting to
 109   register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR
 110   is returned.
 111
 112
 113   @param This             The EFI_TIMER_ARCH_PROTOCOL instance.
 114   @param NotifyFunction   The function to call when a timer interrupt fires.  This
 115                           function executes at TPL_HIGH_LEVEL.  The DXE Core will
 116                           register a handler for the timer interrupt, so it can know
 117                           how much time has passed.  This information is used to
 118                           signal timer based events.  NULL will unregister the handler.
 119
 120   @retval        EFI_SUCCESS            The timer handler was registered.
 121   @retval        EFI_UNSUPPORTED        The platform does not support timer interrupts.
 122   @retval        EFI_ALREADY_STARTED    NotifyFunction is not NULL, and a handler is already
 123                                         registered.
 124   @retval        EFI_INVALID_PARAMETER  NotifyFunction is NULL, and a handler was not
 125                                         previously registered.
 126   @retval        EFI_DEVICE_ERROR       The timer handler could not be registered.
 127
 128 **/
 129 EFI_STATUS
 130 EFIAPI
 131 TimerDriverRegisterHandler (
 132   IN EFI_TIMER_ARCH_PROTOCOL  *This,
 133   IN EFI_TIMER_NOTIFY         NotifyFunction
 134   )
 135 {
 136   //
 137   // Check for invalid parameters
 138   //
 139   if ((NotifyFunction == NULL) && (mTimerNotifyFunction == NULL)) {
 140     return EFI_INVALID_PARAMETER;
 141   }
 142
 143   if ((NotifyFunction != NULL) && (mTimerNotifyFunction != NULL)) {
 144     return EFI_ALREADY_STARTED;
 145   }
 146
 147   mTimerNotifyFunction = NotifyFunction;
 148
 149   return EFI_SUCCESS;
 150 }
 151
 152 /**
 153
 154   This function adjusts the period of timer interrupts to the value specified
 155   by TimerPeriod.  If the timer period is updated, then the selected timer
 156   period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned.  If
 157   the timer hardware is not programmable, then EFI_UNSUPPORTED is returned.
 158   If an error occurs while attempting to update the timer period, then the
 159   timer hardware will be put back in its state prior to this call, and
 160   EFI_DEVICE_ERROR is returned.  If TimerPeriod is 0, then the timer interrupt
 161   is disabled.  This is not the same as disabling the CPU's interrupts.
 162   Instead, it must either turn off the timer hardware, or it must adjust the
 163   interrupt controller so that a CPU interrupt is not generated when the timer
 164   interrupt fires.
 165
 166
 167   @param This            The EFI_TIMER_ARCH_PROTOCOL instance.
 168   @param TimerPeriod     The rate to program the timer interrupt in 100 nS units.  If
 169                          the timer hardware is not programmable, then EFI_UNSUPPORTED is
 170                          returned.  If the timer is programmable, then the timer period
 171                          will be rounded up to the nearest timer period that is supported
 172                          by the timer hardware.  If TimerPeriod is set to 0, then the
 173                          timer interrupts will be disabled.
 174
 175   @retval        EFI_SUCCESS       The timer period was changed.
 176   @retval        EFI_UNSUPPORTED   The platform cannot change the period of the timer interrupt.
 177   @retval        EFI_DEVICE_ERROR  The timer period could not be changed due to a device error.
 178
 179 **/
 180 EFI_STATUS
 181 EFIAPI
 182 TimerDriverSetTimerPeriod (
 183   IN EFI_TIMER_ARCH_PROTOCOL  *This,
 184   IN UINT64                   TimerPeriod
 185   )
 186 {
 187   UINT64  TimerCount;
 188
 189   //
 190   //  The basic clock is 1.19318 MHz or 0.119318 ticks per 100 ns.
 191   //  TimerPeriod * 0.119318 = 8254 timer divisor. Using integer arithmetic
 192   //  TimerCount = (TimerPeriod * 119318)/1000000.
 193   //
 194   //  Round up to next highest integer. This guarantees that the timer is
 195   //  equal to or slightly longer than the requested time.
 196   //  TimerCount = ((TimerPeriod * 119318) + 500000)/1000000
 197   //
 198   // Note that a TimerCount of 0 is equivalent to a count of 65,536
 199   //
 200   // Since TimerCount is limited to 16 bits for IA32, TimerPeriod is limited
 201   // to 20 bits.
 202   //
 203   if (TimerPeriod == 0) {
 204     //
 205     // Disable timer interrupt for a TimerPeriod of 0
 206     //
 207     mLegacy8259->DisableIrq (mLegacy8259, Efi8259Irq0);
 208   } else {
 209     //
 210     // Convert TimerPeriod into 8254 counts
 211     //
 212     TimerCount = DivU64x32 (MultU64x32 (119318, (UINT32)TimerPeriod) + 500000, 1000000);
 213
 214     //
 215     // Check for overflow
 216     //
 217     if (TimerCount >= 65536) {
 218       TimerCount  = 0;
 219       TimerPeriod = MAX_TIMER_TICK_DURATION;
 220     }
 221
 222     //
 223     // Program the 8254 timer with the new count value
 224     //
 225     SetPitCount ((UINT16)TimerCount);
 226
 227     //
 228     // Enable timer interrupt
 229     //
 230     mLegacy8259->EnableIrq (mLegacy8259, Efi8259Irq0, FALSE);
 231   }
 232
 233   //
 234   // Save the new timer period
 235   //
 236   mTimerPeriod = TimerPeriod;
 237
 238   return EFI_SUCCESS;
 239 }
 240
 241 /**
 242
 243   This function retrieves the period of timer interrupts in 100 ns units,
 244   returns that value in TimerPeriod, and returns EFI_SUCCESS.  If TimerPeriod
 245   is NULL, then EFI_INVALID_PARAMETER is returned.  If a TimerPeriod of 0 is
 246   returned, then the timer is currently disabled.
 247
 248
 249   @param This            The EFI_TIMER_ARCH_PROTOCOL instance.
 250   @param TimerPeriod     A pointer to the timer period to retrieve in 100 ns units.  If
 251                          0 is returned, then the timer is currently disabled.
 252
 253   @retval EFI_SUCCESS            The timer period was returned in TimerPeriod.
 254   @retval EFI_INVALID_PARAMETER  TimerPeriod is NULL.
 255
 256 **/
 257 EFI_STATUS
 258 EFIAPI
 259 TimerDriverGetTimerPeriod (
 260   IN EFI_TIMER_ARCH_PROTOCOL  *This,
 261   OUT UINT64                  *TimerPeriod
 262   )
 263 {
 264   if (TimerPeriod == NULL) {
 265     return EFI_INVALID_PARAMETER;
 266   }
 267
 268   *TimerPeriod = mTimerPeriod;
 269
 270   return EFI_SUCCESS;
 271 }
 272
 273 /**
 274
 275   This function generates a soft timer interrupt. If the platform does not support soft
 276   timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned.
 277   If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler()
 278   service, then a soft timer interrupt will be generated. If the timer interrupt is
 279   enabled when this service is called, then the registered handler will be invoked. The
 280   registered handler should not be able to distinguish a hardware-generated timer
 281   interrupt from a software-generated timer interrupt.
 282
 283
 284   @param This              The EFI_TIMER_ARCH_PROTOCOL instance.
 285
 286   @retval EFI_SUCCESS       The soft timer interrupt was generated.
 287   @retval EFI_UNSUPPORTED   The platform does not support the generation of soft timer interrupts.
 288
 289 **/
 290 EFI_STATUS
 291 EFIAPI
 292 TimerDriverGenerateSoftInterrupt (
 293   IN EFI_TIMER_ARCH_PROTOCOL  *This
 294   )
 295 {
 296   EFI_STATUS  Status;
 297   UINT16      IRQMask;
 298   EFI_TPL     OriginalTPL;
 299
 300   //
 301   // If the timer interrupt is enabled, then the registered handler will be invoked.
 302   //
 303   Status = mLegacy8259->GetMask (mLegacy8259, NULL, NULL, &IRQMask, NULL);
 304   ASSERT_EFI_ERROR (Status);
 305   if ((IRQMask & 0x1) == 0) {
 306     //
 307     // Invoke the registered handler
 308     //
 309     OriginalTPL = gBS->RaiseTPL (TPL_HIGH_LEVEL);
 310
 311     if (mTimerNotifyFunction != NULL) {
 312       //
 313       // @bug : This does not handle missed timer interrupts
 314       //
 315       mTimerNotifyFunction (mTimerPeriod);
 316     }
 317
 318     gBS->RestoreTPL (OriginalTPL);
 319   } else {
 320     return EFI_UNSUPPORTED;
 321   }
 322
 323   return EFI_SUCCESS;
 324 }
 325
 326 /**
 327   Initialize the Timer Architectural Protocol driver
 328
 329   @param ImageHandle     ImageHandle of the loaded driver
 330   @param SystemTable     Pointer to the System Table
 331
 332   @retval EFI_SUCCESS            Timer Architectural Protocol created
 333   @retval EFI_OUT_OF_RESOURCES   Not enough resources available to initialize driver.
 334   @retval EFI_DEVICE_ERROR       A device error occurred attempting to initialize the driver.
 335
 336 **/
 337 EFI_STATUS
 338 EFIAPI
 339 TimerDriverInitialize (
 340   IN EFI_HANDLE        ImageHandle,
 341   IN EFI_SYSTEM_TABLE  *SystemTable
 342   )
 343 {
 344   EFI_STATUS  Status;
 345   UINT32      TimerVector;
 346
 347   //
 348   // Initialize the pointer to our notify function.
 349   //
 350   mTimerNotifyFunction = NULL;
 351
 352   //
 353   // Make sure the Timer Architectural Protocol is not already installed in the system
 354   //
 355   ASSERT_PROTOCOL_ALREADY_INSTALLED (NULL, &gEfiTimerArchProtocolGuid);
 356
 357   //
 358   // Find the CPU architectural protocol.
 359   //
 360   Status = gBS->LocateProtocol (&gEfiCpuArchProtocolGuid, NULL, (VOID **)&mCpu);
 361   ASSERT_EFI_ERROR (Status);
 362
 363   //
 364   // Find the Legacy8259 protocol.
 365   //
 366   Status = gBS->LocateProtocol (&gEfiLegacy8259ProtocolGuid, NULL, (VOID **)&mLegacy8259);
 367   ASSERT_EFI_ERROR (Status);
 368
 369   //
 370   // Force the timer to be disabled
 371   //
 372   Status = TimerDriverSetTimerPeriod (&mTimer, 0);
 373   ASSERT_EFI_ERROR (Status);
 374
 375   //
 376   // Get the interrupt vector number corresponding to IRQ0 from the 8259 driver
 377   //
 378   TimerVector = 0;
 379   Status      = mLegacy8259->GetVector (mLegacy8259, Efi8259Irq0, (UINT8 *)&TimerVector);
 380   ASSERT_EFI_ERROR (Status);
 381
 382   //
 383   // Install interrupt handler for 8254 Timer #0 (ISA IRQ0)
 384   //
 385   Status = mCpu->RegisterInterruptHandler (mCpu, TimerVector, TimerInterruptHandler);
 386   ASSERT_EFI_ERROR (Status);
 387
 388   //
 389   // Force the timer to be enabled at its default period
 390   //
 391   Status = TimerDriverSetTimerPeriod (&mTimer, DEFAULT_TIMER_TICK_DURATION);
 392   ASSERT_EFI_ERROR (Status);
 393
 394   //
 395   // Install the Timer Architectural Protocol onto a new handle
 396   //
 397   Status = gBS->InstallMultipleProtocolInterfaces (
 398                   &mTimerHandle,
 399                   &gEfiTimerArchProtocolGuid,
 400                   &mTimer,
 401                   NULL
 402                   );
 403   ASSERT_EFI_ERROR (Status);
 404
 405   return Status;
 406 }