EdkCompatibilityPkg/Foundation/Framework/Protocol/SmmPeriodicTimerDispatch/SmmPeriodicTimerDispatch.h

   1 /*++
   2
   3 Copyright (c) 1999 - 2002, 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     SmmPeriodicTimerDispatch.h
  16
  17 Abstract:
  18
  19     EFI Smm Periodic Timer Smi Child Protocol
  20
  21 Revision History
  22
  23 --*/
  24
  25 #ifndef _EFI_SMM_PERIODIC_TIMER_DISPATCH_H_
  26 #define _EFI_SMM_PERIODIC_TIMER_DISPATCH_H_
  27
  28 //
  29 // Global ID for the Periodic Timer SMI Protocol
  30 //
  31 #define EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL_GUID \
  32   { \
  33     0x9cca03fc, 0x4c9e, 0x4a19, 0x9b, 0x6, 0xed, 0x7b, 0x47, 0x9b, 0xde, 0x55 \
  34   }
  35
  36 EFI_FORWARD_DECLARATION (EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL);
  37
  38 //
  39 // Related Definitions
  40 //
  41 //
  42 // Period is the minimum period of time in 100 nanosecond units that child gets called.
  43 // The child will be called back after a time greater than the time Period.
  44 //
  45 // SmiTickInterval is the period of time interval between SMIs.  Children of this interface
  46 // should use this field when registering for periodic timer intervals when a finer
  47 // granularity periodic SMI is desired.  Valid values for this field are those returned
  48 // by GetNextInterval.  A value of 0 indicates the parent is allowed to use any SMI
  49 // interval period to satisfy the requested period.
  50 //    Example: A chipset supports periodic SMIs on every 64ms or 2 seconds.
  51 //      A child wishes schedule a period SMI to fire on a period of 3 seconds, there
  52 //      are several ways to approach the problem:
  53 //      1. The child may accept a 4 second periodic rate, in which case it registers with
  54 //           Period = 40000
  55 //           SmiTickInterval = 20000
  56 //         The resulting SMI will occur every 2 seconds with the child called back on
  57 //         every 2nd SMI.
  58 //         NOTE: the same result would occur if the child set SmiTickInterval = 0.
  59 //      2. The child may choose the finer granularity SMI (64ms):
  60 //           Period = 30000
  61 //           SmiTickInterval = 640
  62 //         The resulting SMI will occur every 64ms with the child called back on
  63 //         every 47th SMI.
  64 //         NOTE: the child driver should be aware that this will result in more
  65 //           SMIs occuring during system runtime which can negatively impact system
  66 //           performance.
  67 //
  68 // ElapsedTime is the actual time in 100 nanosecond units elapsed since last called, a
  69 // value of 0 indicates an unknown amount of time.
  70 //
  71 typedef struct {
  72   UINT64  Period;
  73   UINT64  SmiTickInterval;
  74   UINT64  ElapsedTime;
  75 } EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT;
  76
  77 //
  78 // Member functions
  79 //
  80 typedef
  81 VOID
  82 (EFIAPI *EFI_SMM_PERIODIC_TIMER_DISPATCH) (
  83   IN  EFI_HANDLE                                DispatchHandle,
  84   IN  EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT   * DispatchContext
  85   );
  86
  87 /*++
  88
  89   Routine Description:
  90     Dispatch function for a Periodic Timer SMI handler.
  91
  92   Arguments:
  93     DispatchHandle      - Handle of this dispatch function.
  94     DispatchContext     - Pointer to the dispatch function's context.
  95                           The DispatchContext fields are filled in
  96                           by the dispatching driver prior to
  97                           invoking this dispatch function.
  98
  99   Returns:
 100     Nothing
 101
 102 --*/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_SMM_PERIODIC_TIMER_INTERVAL) (
 106   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL           * This,
 107   IN OUT UINT64                                         **SmiTickInterval
 108   );
 109
 110 /*++
 111
 112   Routine Description:
 113     Returns the next SMI tick period supported by the chipset.  The order
 114     returned is from longest to shortest interval period.
 115
 116   Arguments:
 117     This                  - Protocol instance pointer.
 118     SmiTickInterval       - Pointer to pointer of next shorter SMI interval
 119                             period supported by the child.  This parameter
 120                             works as a get-first, get-next field.   The first
 121                             time this function is called, *SmiTickInterval
 122                             should be set to NULL to get the longest SMI
 123                             interval.  The returned *SmiTickInterval should
 124                             be passed in on subsequent calls to get
 125                             the next shorter interval period until
 126                             *SmiTickInterval = NULL.
 127
 128   Returns:
 129     EFI_SUCCESS
 130
 131 --*/
 132 typedef
 133 EFI_STATUS
 134 (EFIAPI *EFI_SMM_PERIODIC_TIMER_REGISTER) (
 135   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL           * This,
 136   IN  EFI_SMM_PERIODIC_TIMER_DISPATCH                   DispatchFunction,
 137   IN  EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT           * DispatchContext,
 138   OUT EFI_HANDLE                                        * DispatchHandle
 139   );
 140
 141 /*++
 142
 143   Routine Description:
 144     Register a child SMI source dispatch function with a parent SMM driver
 145
 146   Arguments:
 147     This                  - Protocol instance pointer.
 148     DispatchFunction      - Pointer to dispatch function to be invoked for
 149                             this SMI source
 150     DispatchContext       - Pointer to the dispatch function's context.
 151                             The caller fills this context in before calling
 152                             the register function to indicate to the register
 153                             function the period at which the dispatch function
 154                             should be invoked.
 155     DispatchHandle        - Handle of dispatch function, for when interfacing
 156                             with the parent Sx state SMM driver.
 157
 158   Returns:
 159     EFI_SUCCESS           - The dispatch function has been successfully
 160                             registered and the SMI source has been enabled.
 161     EFI_DEVICE_ERROR      - The driver was unable to enable the SMI source.
 162     EFI_OUT_OF_RESOURCES  - Not enough memory (system or SMM) to manage this
 163                             child.
 164     EFI_INVALID_PARAMETER - DispatchContext is invalid. The period input value
 165                             is not within valid range.
 166
 167 --*/
 168 typedef
 169 EFI_STATUS
 170 (EFIAPI *EFI_SMM_PERIODIC_TIMER_UNREGISTER) (
 171   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL           * This,
 172   IN  EFI_HANDLE                                        DispatchHandle
 173   );
 174
 175 /*++
 176
 177   Routine Description:
 178     Unregister a child SMI source dispatch function with a parent SMM driver
 179
 180   Arguments:
 181     This                  - Protocol instance pointer.
 182     DispatchHandle        - Handle of dispatch function to deregister.
 183
 184   Returns:
 185     EFI_SUCCESS           - The dispatch function has been successfully
 186                             unregistered and the SMI source has been disabled
 187                             if there are no other registered child dispatch
 188                             functions for this SMI source.
 189     EFI_INVALID_PARAMETER - Handle is invalid.
 190     other                 - TBD
 191
 192 --*/
 193
 194 //
 195 // Interface structure for the SMM Periodic Timer Dispatch Protocol
 196 //
 197 typedef struct _EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL {
 198   EFI_SMM_PERIODIC_TIMER_REGISTER   Register;
 199   EFI_SMM_PERIODIC_TIMER_UNREGISTER UnRegister;
 200   EFI_SMM_PERIODIC_TIMER_INTERVAL   GetNextShorterInterval;
 201 } EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL;
 202
 203 extern EFI_GUID gEfiSmmPeriodicTimerDispatchProtocolGuid;
 204
 205 #endif