DuetPkg/8254TimerDxe/Timer.h

   1 /*++
   2
   3 Copyright (c) 2005 - 2006, 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
   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
  13 Module Name:
  14
  15  Timer.h
  16
  17 Abstract:
  18
  19   Private data structures
  20
  21 --*/
  22
  23 #ifndef _TIMER_H_
  24 #define _TIMER_H_
  25
  26 #include <PiDxe.h>
  27
  28 #include <Protocol/Cpu.h>
  29 #include <Protocol/CpuIo.h>
  30 #include <Protocol/Legacy8259.h>
  31 #include <Protocol/Timer.h>
  32
  33 #include <Library/UefiBootServicesTableLib.h>
  34 #include <Library/BaseLib.h>
  35 #include <Library/DebugLib.h>
  36
  37 //
  38 // The PCAT 8253/8254 has an input clock at 1.193182 MHz and Timer 0 is
  39 // initialized as a 16 bit free running counter that generates an interrupt(IRQ0)
  40 // each time the counter rolls over.
  41 //
  42 //   65536 counts
  43 // ---------------- * 1,000,000 uS/S = 54925.4 uS = 549254 * 100 ns
  44 //   1,193,182 Hz
  45 //
  46 #define DEFAULT_TIMER_TICK_DURATION 549254
  47 #define TIMER_CONTROL_PORT          0x43
  48 #define TIMER0_COUNT_PORT           0x40
  49
  50 //
  51 // Function Prototypes
  52 //
  53 EFI_STATUS
  54 EFIAPI
  55 TimerDriverInitialize (
  56   IN EFI_HANDLE        ImageHandle,
  57   IN EFI_SYSTEM_TABLE  *SystemTable
  58   )
  59 /*++
  60
  61 Routine Description:
  62
  63   Initialize the Timer Architectural Protocol driver
  64
  65 Arguments:
  66
  67   ImageHandle - ImageHandle of the loaded driver
  68
  69   SystemTable - Pointer to the System Table
  70
  71 Returns:
  72
  73   EFI_SUCCESS           - Timer Architectural Protocol created
  74
  75   EFI_OUT_OF_RESOURCES  - Not enough resources available to initialize driver.
  76
  77   EFI_DEVICE_ERROR      - A device error occured attempting to initialize the driver.
  78
  79 --*/
  80 ;
  81
  82 EFI_STATUS
  83 EFIAPI
  84 TimerDriverRegisterHandler (
  85   IN EFI_TIMER_ARCH_PROTOCOL  *This,
  86   IN EFI_TIMER_NOTIFY         NotifyFunction
  87   )
  88 /*++
  89
  90 Routine Description:
  91
  92   This function registers the handler NotifyFunction so it is called every time
  93   the timer interrupt fires.  It also passes the amount of time since the last
  94   handler call to the NotifyFunction.  If NotifyFunction is NULL, then the
  95   handler is unregistered.  If the handler is registered, then EFI_SUCCESS is
  96   returned.  If the CPU does not support registering a timer interrupt handler,
  97   then EFI_UNSUPPORTED is returned.  If an attempt is made to register a handler
  98   when a handler is already registered, then EFI_ALREADY_STARTED is returned.
  99   If an attempt is made to unregister a handler when a handler is not registered,
 100   then EFI_INVALID_PARAMETER is returned.  If an error occurs attempting to
 101   register the NotifyFunction with the timer interrupt, then EFI_DEVICE_ERROR
 102   is returned.
 103
 104 Arguments:
 105
 106   This           - The EFI_TIMER_ARCH_PROTOCOL instance.
 107
 108   NotifyFunction - The function to call when a timer interrupt fires.  This
 109                    function executes at TPL_HIGH_LEVEL.  The DXE Core will
 110                    register a handler for the timer interrupt, so it can know
 111                    how much time has passed.  This information is used to
 112                    signal timer based events.  NULL will unregister the handler.
 113
 114 Returns:
 115
 116   EFI_SUCCESS           - The timer handler was registered.
 117
 118   EFI_UNSUPPORTED       - The platform does not support timer interrupts.
 119
 120   EFI_ALREADY_STARTED   - NotifyFunction is not NULL, and a handler is already
 121                           registered.
 122
 123   EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not
 124                           previously registered.
 125
 126   EFI_DEVICE_ERROR      - The timer handler could not be registered.
 127
 128 --*/
 129 ;
 130
 131 EFI_STATUS
 132 EFIAPI
 133 TimerDriverSetTimerPeriod (
 134   IN EFI_TIMER_ARCH_PROTOCOL  *This,
 135   IN UINT64                   TimerPeriod
 136   )
 137 /*++
 138
 139 Routine Description:
 140
 141   This function adjusts the period of timer interrupts to the value specified
 142   by TimerPeriod.  If the timer period is updated, then the selected timer
 143   period is stored in EFI_TIMER.TimerPeriod, and EFI_SUCCESS is returned.  If
 144   the timer hardware is not programmable, then EFI_UNSUPPORTED is returned.
 145   If an error occurs while attempting to update the timer period, then the
 146   timer hardware will be put back in its state prior to this call, and
 147   EFI_DEVICE_ERROR is returned.  If TimerPeriod is 0, then the timer interrupt
 148   is disabled.  This is not the same as disabling the CPU's interrupts.
 149   Instead, it must either turn off the timer hardware, or it must adjust the
 150   interrupt controller so that a CPU interrupt is not generated when the timer
 151   interrupt fires.
 152
 153 Arguments:
 154
 155   This        - The EFI_TIMER_ARCH_PROTOCOL instance.
 156
 157   TimerPeriod - The rate to program the timer interrupt in 100 nS units.  If
 158                 the timer hardware is not programmable, then EFI_UNSUPPORTED is
 159                 returned.  If the timer is programmable, then the timer period
 160                 will be rounded up to the nearest timer period that is supported
 161                 by the timer hardware.  If TimerPeriod is set to 0, then the
 162                 timer interrupts will be disabled.
 163
 164 Returns:
 165
 166   EFI_SUCCESS      - The timer period was changed.
 167
 168   EFI_UNSUPPORTED  - The platform cannot change the period of the timer interrupt.
 169
 170   EFI_DEVICE_ERROR - The timer period could not be changed due to a device error.
 171
 172 --*/
 173 ;
 174
 175 EFI_STATUS
 176 EFIAPI
 177 TimerDriverGetTimerPeriod (
 178   IN EFI_TIMER_ARCH_PROTOCOL   *This,
 179   OUT UINT64                   *TimerPeriod
 180   )
 181 /*++
 182
 183 Routine Description:
 184
 185   This function retrieves the period of timer interrupts in 100 ns units,
 186   returns that value in TimerPeriod, and returns EFI_SUCCESS.  If TimerPeriod
 187   is NULL, then EFI_INVALID_PARAMETER is returned.  If a TimerPeriod of 0 is
 188   returned, then the timer is currently disabled.
 189
 190 Arguments:
 191
 192   This        - The EFI_TIMER_ARCH_PROTOCOL instance.
 193
 194   TimerPeriod - A pointer to the timer period to retrieve in 100 ns units.  If
 195                 0 is returned, then the timer is currently disabled.
 196
 197 Returns:
 198
 199   EFI_SUCCESS           - The timer period was returned in TimerPeriod.
 200
 201   EFI_INVALID_PARAMETER - TimerPeriod is NULL.
 202
 203 --*/
 204 ;
 205
 206 EFI_STATUS
 207 EFIAPI
 208 TimerDriverGenerateSoftInterrupt (
 209   IN EFI_TIMER_ARCH_PROTOCOL  *This
 210   )
 211 /*++
 212
 213 Routine Description:
 214
 215   This function generates a soft timer interrupt. If the platform does not support soft
 216   timer interrupts, then EFI_UNSUPPORTED is returned. Otherwise, EFI_SUCCESS is returned.
 217   If a handler has been registered through the EFI_TIMER_ARCH_PROTOCOL.RegisterHandler()
 218   service, then a soft timer interrupt will be generated. If the timer interrupt is
 219   enabled when this service is called, then the registered handler will be invoked. The
 220   registered handler should not be able to distinguish a hardware-generated timer
 221   interrupt from a software-generated timer interrupt.
 222
 223 Arguments:
 224
 225   This  -  The EFI_TIMER_ARCH_PROTOCOL instance.
 226
 227 Returns:
 228
 229   EFI_SUCCESS       - The soft timer interrupt was generated.
 230
 231   EFI_UNSUPPORTEDT  - The platform does not support the generation of soft timer interrupts.
 232
 233 --*/
 234 ;
 235
 236 #endif