MdePkg/Include/Protocol/MmSxDispatch.h

   1 /** @file
   2   MM Sx Dispatch Protocol as defined in PI 1.5 Specification
   3   Volume 4 Management Mode Core Interface.
   4
   5   Provides the parent dispatch service for a given Sx-state source generator.
   6
   7   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef _MM_SX_DISPATCH_H_
  13 #define _MM_SX_DISPATCH_H_
  14
  15 #include <Pi/PiMmCis.h>
  16
  17 #define EFI_MM_SX_DISPATCH_PROTOCOL_GUID \
  18   { \
  19     0x456d2859, 0xa84b, 0x4e47, {0xa2, 0xee, 0x32, 0x76, 0xd8, 0x86, 0x99, 0x7d } \
  20   }
  21
  22 ///
  23 /// Sleep states S0-S5
  24 ///
  25 typedef enum {
  26   SxS0,
  27   SxS1,
  28   SxS2,
  29   SxS3,
  30   SxS4,
  31   SxS5,
  32   EfiMaximumSleepType
  33 } EFI_SLEEP_TYPE;
  34
  35 ///
  36 /// Sleep state phase: entry or exit
  37 ///
  38 typedef enum {
  39   SxEntry,
  40   SxExit,
  41   EfiMaximumPhase
  42 } EFI_SLEEP_PHASE;
  43
  44 ///
  45 /// The dispatch function's context
  46 ///
  47 typedef struct {
  48   EFI_SLEEP_TYPE  Type;
  49   EFI_SLEEP_PHASE Phase;
  50 } EFI_MM_SX_REGISTER_CONTEXT;
  51
  52 typedef struct _EFI_MM_SX_DISPATCH_PROTOCOL  EFI_MM_SX_DISPATCH_PROTOCOL;
  53
  54 /**
  55   Provides the parent dispatch service for a given Sx source generator.
  56
  57   This service registers a function (DispatchFunction) which will be called when the sleep state
  58   event specified by RegisterContext is detected. On return, DispatchHandle contains a
  59   unique handle which may be used later to unregister the function using UnRegister().
  60   The DispatchFunction will be called with Context set to the same value as was passed into
  61   this function in RegisterContext and with CommBuffer and CommBufferSize set to
  62   NULL and 0 respectively.
  63
  64   @param[in] This                Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance.
  65   @param[in] DispatchFunction    Function to register for handler when the specified sleep state event occurs.
  66   @param[in] RegisterContext     Pointer to the dispatch function's context.
  67                                  The caller fills this context in before calling
  68                                  the register function to indicate to the register
  69                                  function which Sx state type and phase the caller
  70                                  wishes to be called back on. For this intertace,
  71                                  the Sx driver will call the registered handlers for
  72                                  all Sx type and phases, so the Sx state handler(s)
  73                                  must check the Type and Phase field of the Dispatch
  74                                  context and act accordingly.
  75   @param[out]  DispatchHandle    Handle of dispatch function, for when interfacing
  76                                  with the parent Sx state MM driver.
  77
  78   @retval EFI_SUCCESS            The dispatch function has been successfully
  79                                  registered and the MMI source has been enabled.
  80   @retval EFI_UNSUPPORTED        The Sx driver or hardware does not support that
  81                                  Sx Type/Phase.
  82   @retval EFI_DEVICE_ERROR       The Sx driver was unable to enable the MMI source.
  83   @retval EFI_INVALID_PARAMETER  RegisterContext is invalid. Type & Phase are not
  84                                  within valid range.
  85   @retval EFI_OUT_OF_RESOURCES   There is not enough memory (system or MM) to manage this
  86                                  child.
  87 **/
  88 typedef
  89 EFI_STATUS
  90 (EFIAPI *EFI_MM_SX_REGISTER)(
  91   IN  CONST EFI_MM_SX_DISPATCH_PROTOCOL  *This,
  92   IN        EFI_MM_HANDLER_ENTRY_POINT   DispatchFunction,
  93   IN  CONST EFI_MM_SX_REGISTER_CONTEXT   *RegisterContext,
  94   OUT       EFI_HANDLE                   *DispatchHandle
  95   );
  96
  97 /**
  98   Unregisters an Sx-state service.
  99
 100   This service removes the handler associated with DispatchHandle so that it will no longer be
 101   called in response to sleep event.
 102
 103   @param[in] This                Pointer to the EFI_MM_SX_DISPATCH_PROTOCOL instance.
 104   @param[in] DispatchHandle      Handle of the service to remove.
 105
 106   @retval EFI_SUCCESS            The service has been successfully removed.
 107   @retval EFI_INVALID_PARAMETER  The DispatchHandle was not valid.
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI *EFI_MM_SX_UNREGISTER)(
 112   IN CONST EFI_MM_SX_DISPATCH_PROTOCOL  *This,
 113   IN       EFI_HANDLE                   DispatchHandle
 114   );
 115
 116 ///
 117 /// Interface structure for the MM Sx Dispatch Protocol
 118 ///
 119 /// The EFI_MM_SX_DISPATCH_PROTOCOL provides the ability to install child handlers to
 120 /// respond to sleep state related events.
 121 ///
 122 struct _EFI_MM_SX_DISPATCH_PROTOCOL {
 123   EFI_MM_SX_REGISTER    Register;
 124   EFI_MM_SX_UNREGISTER  UnRegister;
 125 };
 126
 127 extern EFI_GUID gEfiMmSxDispatchProtocolGuid;
 128
 129 #endif