IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h

   1 /** @file
   2   Provides the parent dispatch service for the power button 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_POWER_BUTTON_DISPATCH_H_
  14 #define _EFI_SMM_POWER_BUTTON_DISPATCH_H_
  15
  16
  17 //
  18 // Global ID for the Power Button SMI Protocol
  19 //
  20 #define EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL_GUID \
  21   { \
  22     0xb709efa0, 0x47a6, 0x4b41, {0xb9, 0x31, 0x12, 0xec, 0xe7, 0xa8, 0xee, 0x56 } \
  23   }
  24
  25 typedef struct _EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL  EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL;
  26
  27 //
  28 // Related Definitions
  29 //
  30 //
  31 // Power Button. Example, Use for changing LEDs before ACPI OS is on.
  32 //    - DXE/BDS Phase
  33 //    - OS Install Phase
  34 //
  35 typedef enum {
  36   PowerButtonEntry,
  37   PowerButtonExit
  38 } EFI_POWER_BUTTON_PHASE;
  39
  40 typedef struct {
  41   EFI_POWER_BUTTON_PHASE  Phase;
  42 } EFI_SMM_POWER_BUTTON_DISPATCH_CONTEXT;
  43
  44 //
  45 // Member functions
  46 //
  47 /**
  48   Dispatch function for a Power Button SMI handler.
  49
  50   @param[in]  DispatchHandle        The handle of this dispatch function.
  51   @param[in]  DispatchContext       The pointer to the dispatch function's context.
  52                                     The DispatchContext fields are filled in
  53                                     by the dispatching driver prior to
  54                                     invoking this dispatch function.
  55
  56 **/
  57 typedef
  58 VOID
  59 (EFIAPI *EFI_SMM_POWER_BUTTON_DISPATCH)(
  60   IN  EFI_HANDLE                             DispatchHandle,
  61   IN  EFI_SMM_POWER_BUTTON_DISPATCH_CONTEXT  *DispatchContext
  62   );
  63
  64 /**
  65   Provides the parent dispatch service for a given SMI source generator
  66
  67   @param[in]   This                  The pointer to the
  68                                      EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.
  69   @param[in]   DispatchFunction      The function to install.
  70   @param[in]   DispatchContext       The pointer to the dispatch function's context.
  71                                      Indicates to the register
  72                                      function the Power Button SMI phase for which
  73                                      to invoke the dispatch function.
  74   @param[out]  DispatchHandle        Handle generated by the dispatcher to track
  75                                      the function instance.
  76
  77   @retval      EFI_SUCCESS           The dispatch function has been successfully
  78                                      registered and the SMI source has been enabled.
  79   @retval      EFI_DEVICE_ERROR      The driver was unable to enable the SMI source.
  80   @retval      EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this
  81                                      child.
  82   @retval      EFI_INVALID_PARAMETER DispatchContext is invalid. The Power Button SMI
  83                                      phase is not within valid range.
  84
  85 **/
  86 typedef
  87 EFI_STATUS
  88 (EFIAPI *EFI_SMM_POWER_BUTTON_REGISTER)(
  89   IN EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL           *This,
  90   IN EFI_SMM_POWER_BUTTON_DISPATCH                    DispatchFunction,
  91   IN EFI_SMM_POWER_BUTTON_DISPATCH_CONTEXT            *DispatchContext,
  92   OUT EFI_HANDLE                                      *DispatchHandle
  93   );
  94
  95 /**
  96   Unregisters a power-button service.
  97
  98   @param[in]  This                  The pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.
  99   @param[in]  DispatchHandle        The handle of the service to remove.
 100
 101   @retval     EFI_SUCCESS           The dispatch function has been successfully
 102                                     unregistered, and the SMI source has been
 103             disabled, if there are no other registered
 104             child dispatch functions for this SMI
 105             source.
 106   @retval     EFI_INVALID_PARAMETER The handle is invalid.
 107
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI *EFI_SMM_POWER_BUTTON_UNREGISTER)(
 112   IN EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL            *This,
 113   IN EFI_HANDLE                                        DispatchHandle
 114   );
 115
 116 /**
 117   @par Protocol Description:
 118   Provides the parent dispatch service for the SMM power button SMI source generator.
 119
 120 **/
 121 struct _EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL {
 122   ///
 123   ///  Installs a child service to be dispatched by this protocol.
 124   ///
 125   EFI_SMM_POWER_BUTTON_REGISTER   Register;
 126
 127   ///
 128   ///  Removes a child service dispatched by this protocol.
 129   ///
 130   EFI_SMM_POWER_BUTTON_UNREGISTER UnRegister;
 131 };
 132
 133 extern EFI_GUID gEfiSmmPowerButtonDispatchProtocolGuid;
 134
 135 #endif