1 /** @file 2 Support functions for managing protocol. 3 4 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 5 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 271