IntelFrameworkPkg/Include/Protocol/SmmPeriodicTimerDispatch.h

   1 /** @file
   2   Provides the parent dispatch service for the periodical timer SMI source generator.
   3
   4 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8   This Protocol is defined in Framework of EFI SMM Core Interface Spec
   9   Version 0.9.
  10
  11 **/
  12
  13 #ifndef _EFI_SMM_PERIODIC_TIMER_DISPATCH_H_
  14 #define _EFI_SMM_PERIODIC_TIMER_DISPATCH_H_
  15
  16
  17 //
  18 // Global ID for the Periodic Timer SMI Protocol
  19 //
  20 #define EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL_GUID \
  21   { \
  22     0x9cca03fc, 0x4c9e, 0x4a19, {0x9b, 0x6, 0xed, 0x7b, 0x47, 0x9b, 0xde, 0x55 } \
  23   }
  24
  25 typedef struct _EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL  EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL;
  26
  27 //
  28 // Related Definitions
  29 //
  30
  31 typedef struct {
  32   ///
  33   /// The minimum period of time that the child gets called, in 100 nanosecond units.
  34   /// The child will be called back after a time greater than the time Period.
  35   ///
  36   UINT64  Period;
  37   ///
  38   /// The period of time interval between SMIs.  Children of this interface
  39   /// should use this field when registering for periodic timer intervals when a finer
  40   /// granularity periodic SMI is desired.  Valid values for this field are those returned
  41   /// by GetNextInterval.  A value of 0 indicates the parent is allowed to use any SMI
  42   /// interval period to satisfy the requested period.
  43   ///
  44   UINT64  SmiTickInterval;
  45   ///
  46   /// The actual time in 100 nanosecond units elapsed since last called. A
  47   /// value of 0 indicates an unknown amount of time.
  48   ///
  49   UINT64  ElapsedTime;
  50 } EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT;
  51
  52 //
  53 // Member functions
  54 //
  55 /**
  56   Dispatch function for a Periodic Timer SMI handler.
  57
  58   @param  DispatchHandle        The handle of this dispatch function.
  59   @param  DispatchContext       The pointer to the dispatch function's context.
  60                                 The DispatchContext fields are filled in
  61                                 by the dispatching driver prior to
  62                                 invoking this dispatch function.
  63
  64   @return None
  65
  66 **/
  67 typedef
  68 VOID
  69 (EFIAPI *EFI_SMM_PERIODIC_TIMER_DISPATCH)(
  70   IN EFI_HANDLE                                DispatchHandle,
  71   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT   *DispatchContext
  72   );
  73
  74 /**
  75   Returns the next SMI tick period supported by the chipset.  The order
  76   returned is from longest to shortest interval period.
  77
  78   @param  This                  The protocol instance pointer.
  79   @param  SmiTickInterval       The pointer to pointer of next shorter SMI interval
  80                                 period supported by the child. This parameter works as a get-first,
  81                                 get-next field. The first time this function is called, *SmiTickInterval
  82                                 should be set to NULL to get the longest SMI interval. The returned
  83                                 *SmiTickInterval should be passed in on subsequent calls to get the
  84                                 next shorter interval period until *SmiTickInterval = NULL.
  85
  86   @retval EFI_SUCCESS           The service returned successfully.
  87
  88 **/
  89 typedef
  90 EFI_STATUS
  91 (EFIAPI *EFI_SMM_PERIODIC_TIMER_INTERVAL)(
  92   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL           *This,
  93   IN OUT UINT64                                         **SmiTickInterval
  94   );
  95
  96 /**
  97   Register a child SMI source dispatch function with a parent SMM driver
  98
  99   @param  This                  The pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance.
 100   @param  DispatchFunction      The function to install.
 101   @param  DispatchContext       The pointer to the dispatch function's context.
 102                                 Indicates to the register
 103                                 function the period at which the dispatch function
 104                                 should be invoked.
 105   @param  DispatchHandle        The handle generated by the dispatcher to track the function instance.
 106
 107   @retval EFI_SUCCESS           The dispatch function has been successfully
 108                                 registered, and the SMI source has been enabled.
 109   @retval EFI_DEVICE_ERROR      The driver was unable to enable the SMI source.
 110   @retval EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this
 111                                 child.
 112   @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The period input value
 113                                 is not within valid range.
 114
 115 **/
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *EFI_SMM_PERIODIC_TIMER_REGISTER)(
 119   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL          *This,
 120   IN EFI_SMM_PERIODIC_TIMER_DISPATCH                   DispatchFunction,
 121   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_CONTEXT           *DispatchContext,
 122   OUT EFI_HANDLE                                       *DispatchHandle
 123   );
 124
 125 /**
 126   Unregisters a periodic timer service.
 127
 128   @param  This                  The pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL instance.
 129   @param  DispatchHandle        The handle of the service to remove.
 130
 131   @retval EFI_SUCCESS           The dispatch function has been successfully
 132                                 unregistered, and the SMI source has been disabled
 133                                 if there are no other registered child dispatch
 134                                 functions for this SMI source.
 135   @retval EFI_INVALID_PARAMETER The handle is invalid.
 136
 137 **/
 138 typedef
 139 EFI_STATUS
 140 (EFIAPI *EFI_SMM_PERIODIC_TIMER_UNREGISTER)(
 141   IN EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL          *This,
 142   IN EFI_HANDLE                                        DispatchHandle
 143   );
 144
 145 //
 146 // Interface structure for the SMM Periodic Timer Dispatch Protocol
 147 //
 148 /**
 149   Provides the parent dispatch service for the periodical timer SMI source generator.
 150 **/
 151 struct _EFI_SMM_PERIODIC_TIMER_DISPATCH_PROTOCOL {
 152   ///
 153   /// Installs a child service to be dispatched by this protocol.
 154   ///
 155   EFI_SMM_PERIODIC_TIMER_REGISTER   Register;
 156
 157   ///
 158   /// Removes a child service dispatched by this protocol.
 159   ///
 160   EFI_SMM_PERIODIC_TIMER_UNREGISTER UnRegister;
 161
 162   ///
 163   /// Returns the next SMI tick period that is supported by the chipset.
 164   ///
 165   EFI_SMM_PERIODIC_TIMER_INTERVAL   GetNextShorterInterval;
 166 };
 167
 168 extern EFI_GUID gEfiSmmPeriodicTimerDispatchProtocolGuid;
 169
 170 #endif