MdePkg: Clean up source files

[mirror_edk2.git] / MdePkg / Include / Library / SmmPeriodicSmiLib.h

/** @file\r
  Provides services to enable and disable periodic SMI handlers.\r
\r
Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef __PERIODIC_SMI_LIB_H__\r
#define __PERIODIC_SMI_LIB_H__\r
\r
#define PERIODIC_SMI_LIBRARY_ANY_CPU  0xffffffff\r
\r
/**\r
  This function returns a pointer to a table of supported periodic\r
  SMI tick periods in 100 ns units sorted from largest to smallest.\r
  The table contains a array of UINT64 values terminated by a tick\r
  period value of 0.  The returned table must be treated as read-only\r
  data and must not be freed.\r
\r
  @return  A pointer to a table of UINT64 tick period values in\r
           100ns units sorted from largest to smallest terminated\r
           by a tick period of 0.\r
\r
**/\r
UINT64 *\r
EFIAPI\r
PeriodicSmiSupportedTickPeriod (\r
  VOID\r
  );\r
\r
/**\r
  This function returns the time in 100ns units since the periodic SMI\r
  handler function was called.  If the periodic SMI handler was resumed\r
  through PeriodicSmiYield(), then the time returned is the time in\r
  100ns units since PeriodicSmiYield() returned.\r
\r
  @return  The actual time in 100ns units that the periodic SMI handler\r
           has been executing.  If this function is not called from within\r
           an enabled periodic SMI handler, then 0 is returned.\r
\r
**/\r
UINT64\r
EFIAPI\r
PeriodicSmiExecutionTime (\r
  VOID\r
  );\r
\r
/**\r
  This function returns control back to the SMM Foundation.  When the next\r
  periodic SMI for the currently executing handler is triggered, the periodic\r
  SMI handler will restarted from its registered DispatchFunction entry point.\r
  If this function is not called from within an enabled periodic SMI handler,\r
  then control is returned to the calling function.\r
\r
**/\r
VOID\r
EFIAPI\r
PeriodicSmiExit (\r
  VOID\r
  );\r
\r
/**\r
  This function yields control back to the SMM Foundation.  When the next\r
  periodic SMI for the currently executing handler is triggered, the periodic\r
  SMI handler will be resumed and this function will return.  Use of this\r
  function requires a seperate stack for the periodic SMI handler.  A non zero\r
  stack size must be specified in PeriodicSmiEnable() for this function to be\r
  used.\r
\r
  If the stack size passed into PeriodicSmiEnable() was zero, the 0 is returned.\r
\r
  If this function is not called from within an enabled periodic SMI handler,\r
  then 0 is returned.\r
\r
  @return  The actual time in 100ns units elapsed since this function was\r
           called.  A value of 0 indicates an unknown amount of time.\r
\r
**/\r
UINT64\r
EFIAPI\r
PeriodicSmiYield (\r
  VOID\r
  );\r
\r
/**\r
  This function is a prototype for a periodic SMI handler function\r
  that may be enabled with PeriodicSmiEnable() and disabled with\r
  PeriodicSmiDisable().\r
\r
  @param[in] Context      Content registered with PeriodicSmiEnable().\r
  @param[in] ElapsedTime  The actual time in 100ns units elapsed since\r
                          this function was called.  A value of 0 indicates\r
                          an unknown amount of time.\r
\r
**/\r
typedef\r
VOID\r
(EFIAPI *PERIODIC_SMI_LIBRARY_HANDLER) (\r
  IN CONST VOID  *Context OPTIONAL,\r
  IN UINT64      ElapsedTime\r
  );\r
\r
/**\r
  This function enables a periodic SMI handler.\r
\r
  @param[in, out] DispatchHandle   A pointer to the handle associated with the\r
                                   enabled periodic SMI handler.  This is an\r
                                   optional parameter that may be NULL.  If it is\r
                                   NULL, then the handle will not be returned,\r
                                   which means that the periodic SMI handler can\r
                                   never be disabled.\r
  @param[in]     DispatchFunction  A pointer to a periodic SMI handler function.\r
  @param[in]     Context           Optional content to pass into DispatchFunction.\r
  @param[in]     TickPeriod        The requested tick period in 100ns units that\r
                                   control should be givien to the periodic SMI\r
                                   handler.  Must be one of the supported values\r
                                   returned by PeriodicSmiSupportedPickPeriod().\r
  @param[in]     Cpu               Specifies the CPU that is required to execute\r
                                   the periodic SMI handler.  If Cpu is\r
                                   PERIODIC_SMI_LIBRARY_ANY_CPU, then the periodic\r
                                   SMI handler will always be executed on the SMST\r
                                   CurrentlyExecutingCpu, which may vary across\r
                                   periodic SMIs.  If Cpu is between 0 and the SMST\r
                                   NumberOfCpus, then the periodic SMI will always\r
                                   be executed on the requested CPU.\r
  @param[in]     StackSize         The size, in bytes, of the stack to allocate for\r
                                   use by the periodic SMI handler.  If 0, then the\r
                                   default stack will be used.\r
\r
  @retval EFI_INVALID_PARAMETER  DispatchFunction is NULL.\r
  @retval EFI_UNSUPPORTED        TickPeriod is not a supported tick period.  The\r
                                 supported tick periods can be retrieved using\r
                                 PeriodicSmiSupportedTickPeriod().\r
  @retval EFI_INVALID_PARAMETER  Cpu is not PERIODIC_SMI_LIBRARY_ANY_CPU or in\r
                                 the range 0 to SMST NumberOfCpus.\r
  @retval EFI_OUT_OF_RESOURCES   There are not enough resources to enable the\r
                                 periodic SMI handler.\r
  @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the\r
                                 stack speficied by StackSize.\r
  @retval EFI_SUCCESS            The periodic SMI handler was enabled.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
PeriodicSmiEnable (\r
  IN OUT EFI_HANDLE                    *DispatchHandle,    OPTIONAL\r
  IN     PERIODIC_SMI_LIBRARY_HANDLER  DispatchFunction,\r
  IN     CONST VOID                    *Context,           OPTIONAL\r
  IN     UINT64                        TickPeriod,\r
  IN     UINTN                         Cpu,\r
  IN     UINTN                         StackSize\r
  );\r
\r
/**\r
  This function disables a periodic SMI handler that has been previously\r
  enabled with PeriodicSmiEnable().\r
\r
  @param[in] DispatchHandle  A handle associated with a previously enabled periodic\r
                             SMI handler.  This is an optional parameter that may\r
                             be NULL.  If it is NULL, then the active periodic SMI\r
                             handlers is disabled.\r
\r
  @retval FALSE  DispatchHandle is NULL and there is no active periodic SMI handler.\r
  @retval FALSE  The periodic SMI handler specified by DispatchHandle has\r
                 not been enabled with PeriodicSmiEnable().\r
  @retval TRUE   The periodic SMI handler specified by DispatchHandle has\r
                 been disabled.  If DispatchHandle is NULL, then the active\r
                 periodic SMI handler has been disabled.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
PeriodicSmiDisable (\r
  IN EFI_HANDLE  DispatchHandle    OPTIONAL\r
  );\r
\r
#endif\r