MdeModulePkg/Core/Dxe/Hand/Handle.h

   1 /** @file
   2   Support functions for managing protocol.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef  _HAND_H_
  10 #define  _HAND_H_
  11
  12
  13 #define EFI_HANDLE_SIGNATURE            SIGNATURE_32('h','n','d','l')
  14
  15 ///
  16 /// IHANDLE - contains a list of protocol handles
  17 ///
  18 typedef struct {
  19   UINTN               Signature;
  20   /// All handles list of IHANDLE
  21   LIST_ENTRY          AllHandles;
  22   /// List of PROTOCOL_INTERFACE's for this handle
  23   LIST_ENTRY          Protocols;
  24   UINTN               LocateRequest;
  25   /// The Handle Database Key value when this handle was last created or modified
  26   UINT64              Key;
  27 } IHANDLE;
  28
  29 #define ASSERT_IS_HANDLE(a)  ASSERT((a)->Signature == EFI_HANDLE_SIGNATURE)
  30
  31 #define PROTOCOL_ENTRY_SIGNATURE        SIGNATURE_32('p','r','t','e')
  32
  33 ///
  34 /// PROTOCOL_ENTRY - each different protocol has 1 entry in the protocol
  35 /// database.  Each handler that supports this protocol is listed, along
  36 /// with a list of registered notifies.
  37 ///
  38 typedef struct {
  39   UINTN               Signature;
  40   /// Link Entry inserted to mProtocolDatabase
  41   LIST_ENTRY          AllEntries;
  42   /// ID of the protocol
  43   EFI_GUID            ProtocolID;
  44   /// All protocol interfaces
  45   LIST_ENTRY          Protocols;
  46   /// Registerd notification handlers
  47   LIST_ENTRY          Notify;
  48 } PROTOCOL_ENTRY;
  49
  50
  51 #define PROTOCOL_INTERFACE_SIGNATURE  SIGNATURE_32('p','i','f','c')
  52
  53 ///
  54 /// PROTOCOL_INTERFACE - each protocol installed on a handle is tracked
  55 /// with a protocol interface structure
  56 ///
  57 typedef struct {
  58   UINTN                       Signature;
  59   /// Link on IHANDLE.Protocols
  60   LIST_ENTRY                  Link;
  61   /// Back pointer
  62   IHANDLE                     *Handle;
  63   /// Link on PROTOCOL_ENTRY.Protocols
  64   LIST_ENTRY                  ByProtocol;
  65   /// The protocol ID
  66   PROTOCOL_ENTRY              *Protocol;
  67   /// The interface value
  68   VOID                        *Interface;
  69   /// OPEN_PROTOCOL_DATA list
  70   LIST_ENTRY                  OpenList;
  71   UINTN                       OpenListCount;
  72
  73 } PROTOCOL_INTERFACE;
  74
  75 #define OPEN_PROTOCOL_DATA_SIGNATURE  SIGNATURE_32('p','o','d','l')
  76
  77 typedef struct {
  78   UINTN                       Signature;
  79   ///Link on PROTOCOL_INTERFACE.OpenList
  80   LIST_ENTRY                  Link;
  81
  82   EFI_HANDLE                  AgentHandle;
  83   EFI_HANDLE                  ControllerHandle;
  84   UINT32                      Attributes;
  85   UINT32                      OpenCount;
  86 } OPEN_PROTOCOL_DATA;
  87
  88
  89 #define PROTOCOL_NOTIFY_SIGNATURE       SIGNATURE_32('p','r','t','n')
  90
  91 ///
  92 /// PROTOCOL_NOTIFY - used for each register notification for a protocol
  93 ///
  94 typedef struct {
  95   UINTN               Signature;
  96   PROTOCOL_ENTRY      *Protocol;
  97   /// All notifications for this protocol
  98   LIST_ENTRY          Link;
  99   /// Event to notify
 100   EFI_EVENT           Event;
 101   /// Last position notified
 102   LIST_ENTRY          *Position;
 103 } PROTOCOL_NOTIFY;
 104
 105
 106
 107 /**
 108   Finds the protocol entry for the requested protocol.
 109   The gProtocolDatabaseLock must be owned
 110
 111   @param  Protocol               The ID of the protocol
 112   @param  Create                 Create a new entry if not found
 113
 114   @return Protocol entry
 115
 116 **/
 117 PROTOCOL_ENTRY  *
 118 CoreFindProtocolEntry (
 119   IN EFI_GUID   *Protocol,
 120   IN BOOLEAN    Create
 121   );
 122
 123
 124 /**
 125   Signal event for every protocol in protocol entry.
 126
 127   @param  ProtEntry              Protocol entry
 128
 129 **/
 130 VOID
 131 CoreNotifyProtocolEntry (
 132   IN PROTOCOL_ENTRY   *ProtEntry
 133   );
 134
 135
 136 /**
 137   Finds the protocol instance for the requested handle and protocol.
 138   Note: This function doesn't do parameters checking, it's caller's responsibility
 139   to pass in valid parameters.
 140
 141   @param  Handle                 The handle to search the protocol on
 142   @param  Protocol               GUID of the protocol
 143   @param  Interface              The interface for the protocol being searched
 144
 145   @return Protocol instance (NULL: Not found)
 146
 147 **/
 148 PROTOCOL_INTERFACE *
 149 CoreFindProtocolInterface (
 150   IN IHANDLE        *Handle,
 151   IN EFI_GUID       *Protocol,
 152   IN VOID           *Interface
 153   );
 154
 155
 156 /**
 157   Removes Protocol from the protocol list (but not the handle list).
 158
 159   @param  Handle                 The handle to remove protocol on.
 160   @param  Protocol               GUID of the protocol to be moved
 161   @param  Interface              The interface of the protocol
 162
 163   @return Protocol Entry
 164
 165 **/
 166 PROTOCOL_INTERFACE *
 167 CoreRemoveInterfaceFromProtocol (
 168   IN IHANDLE        *Handle,
 169   IN EFI_GUID       *Protocol,
 170   IN VOID           *Interface
 171   );
 172
 173
 174 /**
 175   Connects a controller to a driver.
 176
 177   @param  ControllerHandle                      Handle of the controller to be
 178                                                 connected.
 179   @param  ContextDriverImageHandles             DriverImageHandle A pointer to an
 180                                                 ordered list of driver image
 181                                                 handles.
 182   @param  RemainingDevicePath                   RemainingDevicePath A pointer to
 183                                                 the device path that specifies a
 184                                                 child  of the controller
 185                                                 specified by ControllerHandle.
 186
 187   @retval EFI_SUCCESS                           One or more drivers were
 188                                                 connected to ControllerHandle.
 189   @retval EFI_OUT_OF_RESOURCES                  No enough system resources to
 190                                                 complete the request.
 191   @retval EFI_NOT_FOUND                         No drivers were connected to
 192                                                 ControllerHandle.
 193
 194 **/
 195 EFI_STATUS
 196 CoreConnectSingleController (
 197   IN  EFI_HANDLE                ControllerHandle,
 198   IN  EFI_HANDLE                *ContextDriverImageHandles OPTIONAL,
 199   IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath       OPTIONAL
 200   );
 201
 202 /**
 203   Attempts to disconnect all drivers that are using the protocol interface being queried.
 204   If failed, reconnect all drivers disconnected.
 205   Note: This function doesn't do parameters checking, it's caller's responsibility
 206   to pass in valid parameters.
 207
 208   @param  UserHandle             The handle on which the protocol is installed
 209   @param  Prot                   The protocol to disconnect drivers from
 210
 211   @retval EFI_SUCCESS            Drivers using the protocol interface are all
 212                                  disconnected
 213   @retval EFI_ACCESS_DENIED      Failed to disconnect one or all of the drivers
 214
 215 **/
 216 EFI_STATUS
 217 CoreDisconnectControllersUsingProtocolInterface (
 218   IN EFI_HANDLE           UserHandle,
 219   IN PROTOCOL_INTERFACE   *Prot
 220   );
 221
 222
 223 /**
 224   Acquire lock on gProtocolDatabaseLock.
 225
 226 **/
 227 VOID
 228 CoreAcquireProtocolLock (
 229   VOID
 230   );
 231
 232
 233 /**
 234   Release lock on gProtocolDatabaseLock.
 235
 236 **/
 237 VOID
 238 CoreReleaseProtocolLock (
 239   VOID
 240   );
 241
 242
 243 /**
 244   Check whether a handle is a valid EFI_HANDLE
 245
 246   @param  UserHandle             The handle to check
 247
 248   @retval EFI_INVALID_PARAMETER  The handle is NULL or not a valid EFI_HANDLE.
 249   @retval EFI_SUCCESS            The handle is valid EFI_HANDLE.
 250
 251 **/
 252 EFI_STATUS
 253 CoreValidateHandle (
 254   IN  EFI_HANDLE                UserHandle
 255   );
 256
 257 //
 258 // Externs
 259 //
 260 extern EFI_LOCK         gProtocolDatabaseLock;
 261 extern LIST_ENTRY       gHandleList;
 262 extern UINT64           gHandleDatabaseKey;
 263
 264 #endif