IntelFrameworkPkg/Include/Protocol/SmmUsbDispatch.h

   1 /** @file
   2   Provides the parent dispatch service for the USB 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_USB_DISPATCH_H_
  14 #define _EFI_SMM_USB_DISPATCH_H_
  15
  16 //
  17 // Share some common definitions with PI SMM
  18 //
  19 #include <Protocol/SmmUsbDispatch2.h>
  20
  21 //
  22 // Global ID for the USB Protocol
  23 //
  24 #define EFI_SMM_USB_DISPATCH_PROTOCOL_GUID \
  25   { \
  26     0xa05b6ffd, 0x87af, 0x4e42, {0x95, 0xc9, 0x62, 0x28, 0xb6, 0x3c, 0xf3, 0xf3 } \
  27   }
  28
  29 typedef struct _EFI_SMM_USB_DISPATCH_PROTOCOL  EFI_SMM_USB_DISPATCH_PROTOCOL;
  30
  31 typedef struct {
  32   ///
  33   /// Describes whether this child handler will be invoked in response to a USB legacy
  34   /// emulation event, such as port-trap on the PS/2* keyboard control registers, or to a
  35   /// USB wake event, such as resumption from a sleep state.
  36   ///
  37   EFI_USB_SMI_TYPE          Type;
  38   ///
  39   /// The device path is part of the context structure and describes the location of the
  40   /// particular USB host controller in the system for which this register event will occur.
  41   /// This location is important because of the possible integration of several USB host
  42   /// controllers in a system.
  43   ///
  44   EFI_DEVICE_PATH_PROTOCOL  *Device;
  45 } EFI_SMM_USB_DISPATCH_CONTEXT;
  46
  47 //
  48 // Member functions
  49 //
  50 /**
  51   Dispatch function for a USB SMI handler.
  52
  53   @param[in]  DispatchHandle    Handle of this dispatch function.
  54   @param[in]  DispatchContext   Pointer to the dispatch function's context.
  55                                 The DispatchContext fields are filled in
  56                                 by the dispatching driver prior to
  57                                 invoking this dispatch function.
  58
  59 **/
  60 typedef
  61 VOID
  62 (EFIAPI *EFI_SMM_USB_DISPATCH)(
  63   IN  EFI_HANDLE                    DispatchHandle,
  64   IN  EFI_SMM_USB_DISPATCH_CONTEXT  *DispatchContext
  65   );
  66
  67 /**
  68   Register a child SMI source dispatch function with a parent SMM driver.
  69
  70   @param[in]  This              The pointer to the EFI_SMM_USB_DISPATCH_PROTOCOL instance.
  71   @param[in]  DispatchFunction  The pointer to dispatch function to be invoked
  72                                 for this SMI source.
  73   @param[in]  DispatchContext   The pointer to the dispatch function's context.
  74                                 The caller fills this context in before calling
  75                                 the register function to indicate to the register
  76                                 function the USB SMI types for which the dispatch
  77                                 function should be invoked.
  78   @param[out] DispatchHandle    The handle generated by the dispatcher to track the
  79                                 function instance.
  80
  81   @retval EFI_SUCCESS           The dispatch function has been successfully
  82                                 registered and the SMI source has been enabled.
  83   @retval EFI_DEVICE_ERROR      The driver was unable to enable the SMI source.
  84   @retval EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this
  85                                 child.
  86   @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The USB SMI type
  87                                 is not within valid range.
  88
  89 **/
  90 typedef
  91 EFI_STATUS
  92 (EFIAPI *EFI_SMM_USB_REGISTER)(
  93   IN  EFI_SMM_USB_DISPATCH_PROTOCOL           *This,
  94   IN  EFI_SMM_USB_DISPATCH                    DispatchFunction,
  95   IN  EFI_SMM_USB_DISPATCH_CONTEXT            *DispatchContext,
  96   OUT EFI_HANDLE                              *DispatchHandle
  97   );
  98
  99 /**
 100   Unregisters a USB service.
 101
 102   @param[in]  This              The pointer to the EFI_SMM_USB_DISPATCH_PROTOCOL instance.
 103   @param[in]  DispatchHandle    Handle of the service to remove.
 104
 105   @retval EFI_SUCCESS           The dispatch function has been successfully
 106                                 unregistered and the SMI source has been disabled
 107                                 if there are no other registered child dispatch
 108                                 functions for this SMI source.
 109   @retval EFI_INVALID_PARAMETER The DispatchHandle was not valid.
 110
 111 **/
 112 typedef
 113 EFI_STATUS
 114 (EFIAPI *EFI_SMM_USB_UNREGISTER)(
 115   IN EFI_SMM_USB_DISPATCH_PROTOCOL            *This,
 116   IN EFI_HANDLE                               DispatchHandle
 117   );
 118
 119 ///
 120 /// The EFI_SMM_USB_DISPATCH_PROTOCOL provides the ability to install child handlers for the
 121 /// given event types.
 122 ///
 123 struct _EFI_SMM_USB_DISPATCH_PROTOCOL {
 124   EFI_SMM_USB_REGISTER    Register;
 125   EFI_SMM_USB_UNREGISTER  UnRegister;
 126 };
 127
 128 extern EFI_GUID gEfiSmmUsbDispatchProtocolGuid;
 129
 130 #endif