MdePkg/Include/Protocol/SmmPeriodicTimerDispatch.h

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