MdeModulePkg/Core/Dxe/Hand/Handle.h

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