EdkCompatibilityPkg/Foundation/Core/Dxe/ArchProtocol/WatchdogTimer/WatchdogTimer.h

   1 /*++
   2
   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
   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   WatchdogTimer.h
  15
  16 Abstract:
  17
  18   Watchdog Timer Architectural Protocol as defined in the DXE CIS
  19
  20   Used to provide system watchdog timer services
  21
  22 --*/
  23
  24 #ifndef _ARCH_PROTOCOL_WATCHDOG_TIMER_H_
  25 #define _ARCH_PROTOCOL_WATCHDOG_TIMER_H_
  26
  27 //
  28 // Global ID for the Watchdog Timer Architectural Protocol
  29 //
  30 #define EFI_WATCHDOG_TIMER_ARCH_PROTOCOL_GUID \
  31   { 0x665E3FF5, 0x46CC, 0x11d4, {0x9A, 0x38, 0x00, 0x90, 0x27, 0x3F, 0xC1, 0x4D} }
  32
  33 //
  34 // Declare forward reference for the Timer Architectural Protocol
  35 //
  36 EFI_FORWARD_DECLARATION (EFI_WATCHDOG_TIMER_ARCH_PROTOCOL);
  37
  38 typedef
  39 VOID
  40 (EFIAPI *EFI_WATCHDOG_TIMER_NOTIFY) (
  41   IN UINT64  Time
  42   );
  43 /*++
  44
  45 Routine Description:
  46
  47   A function of this type is called when the watchdog timer fires if a
  48   handler has been registered.
  49
  50 Arguments:
  51
  52   Time - The time in 100 ns units that has passed since the watchdog
  53          timer was armed.  For the notify function to be called, this
  54          must be greater than TimerPeriod.
  55
  56 Returns:
  57
  58   None.
  59
  60 --*/
  61
  62 typedef
  63 EFI_STATUS
  64 (EFIAPI *EFI_WATCHDOG_TIMER_REGISTER_HANDLER) (
  65   IN EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  *This,
  66   IN EFI_WATCHDOG_TIMER_NOTIFY                 NotifyFunction
  67   );
  68 /*++
  69
  70 Routine Description:
  71
  72   This function registers a handler that is to be invoked when the watchdog
  73   timer fires.  By default, the EFI_WATCHDOG_TIMER protocol will call the
  74   Runtime Service ResetSystem() when the watchdog timer fires.  If a
  75   NotifyFunction is registered, then the NotifyFunction will be called before
  76   the Runtime Service ResetSystem() is called.  If NotifyFunction is NULL, then
  77   the watchdog handler is unregistered.  If a watchdog handler is registered,
  78   then EFI_SUCCESS is returned.  If an attempt is made to register a handler
  79   when a handler is already registered, then EFI_ALREADY_STARTED is returned.
  80   If an attempt is made to uninstall a handler when a handler is not installed,
  81   then return EFI_INVALID_PARAMETER.
  82
  83 Arguments:
  84
  85   This           - The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.
  86
  87   NotifyFunction - The function to call when the watchdog timer fires.  If this
  88                    is NULL, then the handler will be unregistered.
  89
  90 Returns:
  91
  92   EFI_SUCCESS           - The watchdog timer handler was registered or
  93                           unregistered.
  94
  95   EFI_ALREADY_STARTED   - NotifyFunction is not NULL, and a handler is already
  96                           registered.
  97
  98   EFI_INVALID_PARAMETER - NotifyFunction is NULL, and a handler was not
  99                           previously registered.
 100
 101 --*/
 102
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD) (
 106   IN EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  *This,
 107   IN UINT64                                    TimerPeriod
 108   );
 109 /*++
 110
 111 Routine Description:
 112
 113   This function sets the amount of time to wait before firing the watchdog
 114   timer to TimerPeriod 100 nS units.  If TimerPeriod is 0, then the watchdog
 115   timer is disabled.
 116
 117 Arguments:
 118
 119   This        - The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.
 120
 121   TimerPeriod - The amount of time in 100 nS units to wait before the watchdog
 122                 timer is fired.  If TimerPeriod is zero, then the watchdog
 123                 timer is disabled.
 124
 125 Returns:
 126
 127   EFI_SUCCESS      - The watchdog timer has been programmed to fire in Time
 128                      100 nS units.
 129
 130   EFI_DEVICE_ERROR - A watchdog timer could not be programmed due to a device
 131                      error.
 132
 133 --*/
 134
 135 typedef
 136 EFI_STATUS
 137 (EFIAPI *EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD) (
 138   IN  EFI_WATCHDOG_TIMER_ARCH_PROTOCOL  *This,
 139   OUT UINT64                            *TimerPeriod
 140   );
 141 /*++
 142
 143 Routine Description:
 144
 145   This function retrieves the amount of time the system will wait before firing
 146   the watchdog timer.  This period is returned in TimerPeriod, and EFI_SUCCESS
 147   is returned.  If TimerPeriod is NULL, then EFI_INVALID_PARAMETER is returned.
 148
 149 Arguments:
 150
 151   This        - The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.
 152
 153   TimerPeriod - A pointer to the amount of time in 100 nS units that the system
 154                 will wait before the watchdog timer is fired.  If TimerPeriod of
 155                 zero is returned, then the watchdog timer is disabled.
 156
 157 Returns:
 158
 159   EFI_SUCCESS           - The amount of time that the system will wait before
 160                           firing the watchdog timer was returned in TimerPeriod.
 161
 162   EFI_INVALID_PARAMETER - TimerPeriod is NULL.
 163
 164 --*/
 165
 166 //
 167 // Interface stucture for the Watchdog Timer Architectural Protocol
 168 //
 169 struct _EFI_WATCHDOG_TIMER_ARCH_PROTOCOL {
 170   EFI_WATCHDOG_TIMER_REGISTER_HANDLER  RegisterHandler;
 171   EFI_WATCHDOG_TIMER_SET_TIMER_PERIOD  SetTimerPeriod;
 172   EFI_WATCHDOG_TIMER_GET_TIMER_PERIOD  GetTimerPeriod;
 173 };
 174
 175 /*++
 176
 177   Protocol Description:
 178     This protocol provides the services required to implement the Boot Service
 179     SetWatchdogTimer().  It provides a service to set the amount of time to wait
 180     before firing the watchdog timer, and it also provides a service to register
 181     a handler that is invoked when the watchdog timer fires.  This protocol can
 182     implement the watchdog timer by using the event and timer Boot Services, or
 183     it can make use of custom hardware.  When the watchdog timer fires, control
 184     will be passed to a handler if one has been registered.  If no handler has
 185     been registered, or the registered handler returns, then the system will be
 186     reset by calling the Runtime Service ResetSystem().
 187
 188   Parameters:
 189
 190     RegisterHandler - Registers a handler that is invoked when the watchdog
 191                       timer fires.
 192
 193     SetTimerPeriod  - Sets the amount of time in 100 ns units to wait before the
 194                       watchdog timer is fired.  If this function is supported,
 195                       then the watchdog timer period will be rounded up to the
 196                       nearest supported watchdog timer period.
 197
 198     GetTimerPeriod  - Retrieves the amount of time in 100 ns units that the
 199                       system will wait before the watchdog timer is fired.
 200
 201 --*/
 202
 203 extern EFI_GUID gEfiWatchdogTimerArchProtocolGuid;
 204
 205 #endif
 206