IntelFrameworkPkg/Include/Protocol/SmmSwDispatch.h

   1 /** @file
   2   Provides the parent dispatch service for a given 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 for EFI SMM Core Interface Spec
   9   Version 0.9.
  10
  11 **/
  12
  13 #ifndef _EFI_SMM_SW_DISPATCH_H_
  14 #define _EFI_SMM_SW_DISPATCH_H_
  15
  16
  17 //
  18 // Global ID for the SW SMI Protocol
  19 //
  20 #define EFI_SMM_SW_DISPATCH_PROTOCOL_GUID \
  21   { \
  22     0xe541b773, 0xdd11, 0x420c, {0xb0, 0x26, 0xdf, 0x99, 0x36, 0x53, 0xf8, 0xbf } \
  23   }
  24
  25 typedef struct _EFI_SMM_SW_DISPATCH_PROTOCOL  EFI_SMM_SW_DISPATCH_PROTOCOL;
  26
  27 //
  28 // Related Definitions
  29 //
  30 //
  31 // A particular chipset may not support all possible software SMI input values.
  32 // For example, the ICH supports only values 00h to 0FFh.  The parent only allows a single
  33 // child registration for each SwSmiInputValue.
  34 //
  35 typedef struct {
  36   UINTN SwSmiInputValue;
  37 } EFI_SMM_SW_DISPATCH_CONTEXT;
  38
  39 //
  40 // Member functions
  41 //
  42 /**
  43   Dispatch function for a Software SMI handler.
  44
  45   @param  DispatchHandle        The handle of this dispatch function.
  46   @param  DispatchContext       The pointer to the dispatch function's context.
  47                                 The SwSmiInputValue field is filled in
  48                                 by the software dispatch driver prior to
  49                                 invoking this dispatch function.
  50                                 The dispatch function will only be called
  51                                 for input values for which it is registered.
  52
  53   @return None
  54
  55 **/
  56 typedef
  57 VOID
  58 (EFIAPI *EFI_SMM_SW_DISPATCH)(
  59   IN  EFI_HANDLE                    DispatchHandle,
  60   IN  EFI_SMM_SW_DISPATCH_CONTEXT   *DispatchContext
  61   );
  62
  63 /**
  64   Register a child SMI source dispatch function with a parent SMM driver.
  65
  66   @param  This                  The pointer to the EFI_SMM_SW_DISPATCH_PROTOCOL instance.
  67   @param  DispatchFunction      The function to install.
  68   @param  DispatchContext       The pointer to the dispatch function's context.
  69                                 Indicates to the register
  70                                 function the Software SMI input value for which
  71                                 to invoke the dispatch function.
  72   @param  DispatchHandle        The handle generated by the dispatcher to track
  73                                 the function instance.
  74
  75   @retval EFI_SUCCESS           The dispatch function has been successfully
  76                                 registered and the SMI source has been enabled.
  77   @retval EFI_DEVICE_ERROR      The SW driver could not enable the SMI source.
  78   @retval EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this
  79                                 child.
  80   @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The SW SMI input value
  81                                 is not within valid range.
  82
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_SMM_SW_REGISTER)(
  87   IN EFI_SMM_SW_DISPATCH_PROTOCOL          *This,
  88   IN EFI_SMM_SW_DISPATCH                   DispatchFunction,
  89   IN EFI_SMM_SW_DISPATCH_CONTEXT           *DispatchContext,
  90   OUT EFI_HANDLE                           *DispatchHandle
  91   );
  92
  93 /**
  94   Unregister a child SMI source dispatch function with a parent SMM driver
  95
  96   @param  This                  The pointer to the EFI_SMM_SW_DISPATCH_PROTOCOL instance.
  97   @param  DispatchHandle        The handle of the service to remove.
  98
  99   @retval EFI_SUCCESS           The dispatch function has been successfully
 100                                 unregistered and the SMI source has been disabled
 101                                 if there are no other registered child dispatch
 102                                 functions for this SMI source.
 103   @retval EFI_INVALID_PARAMETER The handle is invalid.
 104
 105 **/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *EFI_SMM_SW_UNREGISTER)(
 109   IN EFI_SMM_SW_DISPATCH_PROTOCOL          *This,
 110   IN EFI_HANDLE                            DispatchHandle
 111   );
 112
 113
 114 //
 115 // Interface structure for the SMM Software SMI Dispatch Protocol
 116 //
 117 /**
 118   Provides the parent dispatch service for a given SMI source generator.
 119 **/
 120 ///
 121 /// Inconsistent with the specification here:
 122 /// In The Framework specification SmmCis, this definition is named as
 123 /// _EFI_SMM_ICHN_DISPATCH_PROTOCOL by mistake.
 124 ///
 125 struct _EFI_SMM_SW_DISPATCH_PROTOCOL {
 126   ///
 127   /// Installs a child service to be dispatched by this protocol.
 128   ///
 129   EFI_SMM_SW_REGISTER   Register;
 130
 131   ///
 132   /// Removes a child service dispatched by this protocol.
 133   ///
 134   EFI_SMM_SW_UNREGISTER UnRegister;
 135
 136   ///
 137   /// A read-only field that describes the maximum value that can be used
 138   /// in the EFI_SMM_SW_DISPATCH_PROTOCOL.Register() service.
 139   ///
 140   UINTN                 MaximumSwiValue;
 141 };
 142
 143 extern EFI_GUID gEfiSmmSwDispatchProtocolGuid;
 144
 145 #endif