4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync SMM Periodic Timer Dispatch Protocol as defined in PI 1.1 Specification
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Volume 4 System Management Mode Core Interface.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This protocol provides the parent dispatch service for the periodical timer SMI source generator.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @par Revision Reference:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This protocol is from PI Version 1.1.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync#define EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL_GUID \
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync 0x4cec368e, 0x8e8e, 0x4d71, {0x8b, 0xe1, 0x95, 0x8c, 0x45, 0xfc, 0x8a, 0x53 } \
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Example: A chipset supports periodic SMIs on every 64ms or 2 seconds.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// A child wishes schedule a period SMI to fire on a period of 3 seconds, there
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// are several ways to approach the problem:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// 1. The child may accept a 4 second periodic rate, in which case it registers with
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Period = 40000
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// SmiTickInterval = 20000
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The resulting SMI will occur every 2 seconds with the child called back on
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// every 2nd SMI.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// NOTE: the same result would occur if the child set SmiTickInterval = 0.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// 2. The child may choose the finer granularity SMI (64ms):
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Period = 30000
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// SmiTickInterval = 640
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The resulting SMI will occur every 64ms with the child called back on
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// every 47th SMI.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// NOTE: the child driver should be aware that this will result in more
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// SMIs occuring during system runtime which can negatively impact system
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// performance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The minimum period of time in 100 nanosecond units that the child gets called. The
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// child will be called back after a time greater than the time Period.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// The period of time interval between SMIs. Children of this interface should use this
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// field when registering for periodic timer intervals when a finer granularity periodic
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// SMI is desired.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// The DispatchFunction will be called with Context set to the same value as was passed into
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Register() in RegisterContext and with CommBuffer pointing to an instance of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// EFI_SMM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// ElapsedTime is the actual time in 100 nanosecond units elapsed since last called, a
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync /// value of 0 indicates an unknown amount of time.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsynctypedef struct _EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL;
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Register a child SMI source dispatch function for SMM periodic timer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This service registers a function (DispatchFunction) which will be called when at least the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync amount of time specified by RegisterContext has elapsed. On return, DispatchHandle
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync contains a unique handle which may be used later to unregister the function using UnRegister().
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The DispatchFunction will be called with Context set to the same value as was passed into
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync this function in RegisterContext and with CommBuffer pointing to an instance of
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_SMM_PERIODIC_TIMER_CONTEXT and CommBufferSize pointing to its size.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] DispatchFunction Function to register for handler when at least the specified amount
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of time has elapsed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] RegisterContext Pointer to the dispatch function's context.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The caller fills this context in before calling
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the register function to indicate to the register
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync function the period at which the dispatch function
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync should be invoked.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] DispatchHandle Handle generated by the dispatcher to track the function instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The dispatch function has been successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync registered and the SMI source has been enabled.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_DEVICE_ERROR The driver was unable to enable the SMI source.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER RegisterContext is invalid. The period input value
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync is not within valid range.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_OUT_OF_RESOURCES There is not enough memory (system or SMM) to manage this child.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN CONST EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL *This,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN CONST EFI_SMM_PERIODIC_TIMER_REGISTER_CONTEXT *RegisterContext,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Unregisters a periodic timer service.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This service removes the handler associated with DispatchHandle so that it will no longer be
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync called when the time has elapsed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] DispatchHandle Handle of the service to remove.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The service has been successfully removed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN CONST EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL *This,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Returns the next SMI tick period supported by the chipset.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The order returned is from longest to shortest interval period.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] This Pointer to the EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in,out] SmiTickInterval Pointer to pointer of next shorter SMI interval
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync period supported by the child. This parameter works as a get-first,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync get-next field.The first time this function is called, *SmiTickInterval
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync should be set to NULL to get the longest SMI interval.The returned
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync *SmiTickInterval should be passed in on subsequent calls to get the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync next shorter interval period until *SmiTickInterval = NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval EFI_SUCCESS The service returned successfully.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN CONST EFI_SMM_PERIODIC_TIMER_DISPATCH2_PROTOCOL *This,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// Interface structure for the SMM Periodic Timer Dispatch Protocol
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync/// This protocol provides the parent dispatch service for the periodical timer SMI source generator.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_SMM_PERIODIC_TIMER_INTERVAL2 GetNextShorterInterval;