2 UEFI handle & protocol handling.
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
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.
20 // mProtocolDatabase - A list of all protocols in the system. (simple list for now)
21 // gHandleList - A list of all the handles in the system
22 // gProtocolDatabaseLock - Lock to protect the mProtocolDatabase
23 // gHandleDatabaseKey - The Key to show that the handle has been created/modified
25 LIST_ENTRY mProtocolDatabase
= INITIALIZE_LIST_HEAD_VARIABLE (mProtocolDatabase
);
26 LIST_ENTRY gHandleList
= INITIALIZE_LIST_HEAD_VARIABLE (gHandleList
);
27 EFI_LOCK gProtocolDatabaseLock
= EFI_INITIALIZE_LOCK_VARIABLE (TPL_NOTIFY
);
28 UINT64 gHandleDatabaseKey
= 0;
33 Acquire lock on gProtocolDatabaseLock.
37 CoreAcquireProtocolLock (
41 CoreAcquireLock (&gProtocolDatabaseLock
);
47 Release lock on gProtocolDatabaseLock.
51 CoreReleaseProtocolLock (
55 CoreReleaseLock (&gProtocolDatabaseLock
);
61 Check whether a handle is a valid EFI_HANDLE
63 @param UserHandle The handle to check
65 @retval EFI_INVALID_PARAMETER The handle is NULL or not a valid EFI_HANDLE.
66 @retval EFI_SUCCESS The handle is valid EFI_HANDLE.
71 IN EFI_HANDLE UserHandle
76 Handle
= (IHANDLE
*)UserHandle
;
78 return EFI_INVALID_PARAMETER
;
80 if (Handle
->Signature
!= EFI_HANDLE_SIGNATURE
) {
81 return EFI_INVALID_PARAMETER
;
89 Finds the protocol entry for the requested protocol.
90 The gProtocolDatabaseLock must be owned
92 @param Protocol The ID of the protocol
93 @param Create Create a new entry if not found
95 @return Protocol entry
99 CoreFindProtocolEntry (
100 IN EFI_GUID
*Protocol
,
105 PROTOCOL_ENTRY
*Item
;
106 PROTOCOL_ENTRY
*ProtEntry
;
108 ASSERT_LOCKED(&gProtocolDatabaseLock
);
111 // Search the database for the matching GUID
115 for (Link
= mProtocolDatabase
.ForwardLink
;
116 Link
!= &mProtocolDatabase
;
117 Link
= Link
->ForwardLink
) {
119 Item
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
120 if (CompareGuid (&Item
->ProtocolID
, Protocol
)) {
123 // This is the protocol entry
132 // If the protocol entry was not found and Create is TRUE, then
133 // allocate a new entry
135 if ((ProtEntry
== NULL
) && Create
) {
136 ProtEntry
= AllocatePool (sizeof(PROTOCOL_ENTRY
));
138 if (ProtEntry
!= NULL
) {
140 // Initialize new protocol entry structure
142 ProtEntry
->Signature
= PROTOCOL_ENTRY_SIGNATURE
;
143 CopyGuid ((VOID
*)&ProtEntry
->ProtocolID
, Protocol
);
144 InitializeListHead (&ProtEntry
->Protocols
);
145 InitializeListHead (&ProtEntry
->Notify
);
148 // Add it to protocol database
150 InsertTailList (&mProtocolDatabase
, &ProtEntry
->AllEntries
);
160 Finds the protocol instance for the requested handle and protocol.
161 Note: This function doesn't do parameters checking, it's caller's responsibility
162 to pass in valid parameters.
164 @param Handle The handle to search the protocol on
165 @param Protocol GUID of the protocol
166 @param Interface The interface for the protocol being searched
168 @return Protocol instance (NULL: Not found)
172 CoreFindProtocolInterface (
174 IN EFI_GUID
*Protocol
,
178 PROTOCOL_INTERFACE
*Prot
;
179 PROTOCOL_ENTRY
*ProtEntry
;
182 ASSERT_LOCKED(&gProtocolDatabaseLock
);
186 // Lookup the protocol entry for this protocol ID
189 ProtEntry
= CoreFindProtocolEntry (Protocol
, FALSE
);
190 if (ProtEntry
!= NULL
) {
193 // Look at each protocol interface for any matches
195 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
=Link
->ForwardLink
) {
198 // If this protocol interface matches, remove it
200 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
201 if (Prot
->Interface
== Interface
&& Prot
->Protocol
== ProtEntry
) {
214 Removes an event from a register protocol notify list on a protocol.
216 @param Event The event to search for in the protocol
219 @return EFI_SUCCESS if the event was found and removed.
220 @return EFI_NOT_FOUND if the event was not found in the protocl database.
224 CoreUnregisterProtocolNotifyEvent (
229 PROTOCOL_ENTRY
*ProtEntry
;
230 LIST_ENTRY
*NotifyLink
;
231 PROTOCOL_NOTIFY
*ProtNotify
;
233 CoreAcquireProtocolLock ();
235 for ( Link
= mProtocolDatabase
.ForwardLink
;
236 Link
!= &mProtocolDatabase
;
237 Link
= Link
->ForwardLink
) {
239 ProtEntry
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
241 for ( NotifyLink
= ProtEntry
->Notify
.ForwardLink
;
242 NotifyLink
!= &ProtEntry
->Notify
;
243 NotifyLink
= NotifyLink
->ForwardLink
) {
245 ProtNotify
= CR(NotifyLink
, PROTOCOL_NOTIFY
, Link
, PROTOCOL_NOTIFY_SIGNATURE
);
247 if (ProtNotify
->Event
== Event
) {
248 RemoveEntryList(&ProtNotify
->Link
);
249 CoreFreePool(ProtNotify
);
250 CoreReleaseProtocolLock ();
256 CoreReleaseProtocolLock ();
257 return EFI_NOT_FOUND
;
263 Removes all the events in the protocol database that match Event.
265 @param Event The event to search for in the protocol
268 @return EFI_SUCCESS when done searching the entire database.
272 CoreUnregisterProtocolNotify (
279 Status
= CoreUnregisterProtocolNotifyEvent (Event
);
280 } while (!EFI_ERROR (Status
));
289 Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
290 Calls the private one which contains a BOOLEAN parameter for notifications
292 @param UserHandle The handle to install the protocol handler on,
293 or NULL if a new handle is to be allocated
294 @param Protocol The protocol to add to the handle
295 @param InterfaceType Indicates whether Interface is supplied in
297 @param Interface The interface for the protocol being added
304 CoreInstallProtocolInterface (
305 IN OUT EFI_HANDLE
*UserHandle
,
306 IN EFI_GUID
*Protocol
,
307 IN EFI_INTERFACE_TYPE InterfaceType
,
311 return CoreInstallProtocolInterfaceNotify (
322 Installs a protocol interface into the boot services environment.
324 @param UserHandle The handle to install the protocol handler on,
325 or NULL if a new handle is to be allocated
326 @param Protocol The protocol to add to the handle
327 @param InterfaceType Indicates whether Interface is supplied in
329 @param Interface The interface for the protocol being added
330 @param Notify indicates whether notify the notification list
333 @retval EFI_INVALID_PARAMETER Invalid parameter
334 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
335 @retval EFI_SUCCESS Protocol interface successfully installed
339 CoreInstallProtocolInterfaceNotify (
340 IN OUT EFI_HANDLE
*UserHandle
,
341 IN EFI_GUID
*Protocol
,
342 IN EFI_INTERFACE_TYPE InterfaceType
,
347 PROTOCOL_INTERFACE
*Prot
;
348 PROTOCOL_ENTRY
*ProtEntry
;
351 VOID
*ExistingInterface
;
354 // returns EFI_INVALID_PARAMETER if InterfaceType is invalid.
355 // Also added check for invalid UserHandle and Protocol pointers.
357 if (UserHandle
== NULL
|| Protocol
== NULL
) {
358 return EFI_INVALID_PARAMETER
;
361 if (InterfaceType
!= EFI_NATIVE_INTERFACE
) {
362 return EFI_INVALID_PARAMETER
;
366 // Print debug message
368 DEBUG((DEBUG_LOAD
| DEBUG_INFO
, "InstallProtocolInterface: %g %p\n", Protocol
, Interface
));
370 Status
= EFI_OUT_OF_RESOURCES
;
374 if (*UserHandle
!= NULL
) {
375 Status
= CoreHandleProtocol (*UserHandle
, Protocol
, (VOID
**)&ExistingInterface
);
376 if (!EFI_ERROR (Status
)) {
377 return EFI_INVALID_PARAMETER
;
382 // Lock the protocol database
384 CoreAcquireProtocolLock ();
387 // Lookup the Protocol Entry for the requested protocol
389 ProtEntry
= CoreFindProtocolEntry (Protocol
, TRUE
);
390 if (ProtEntry
== NULL
) {
395 // Allocate a new protocol interface structure
397 Prot
= AllocateZeroPool (sizeof(PROTOCOL_INTERFACE
));
399 Status
= EFI_OUT_OF_RESOURCES
;
404 // If caller didn't supply a handle, allocate a new one
406 Handle
= (IHANDLE
*)*UserHandle
;
407 if (Handle
== NULL
) {
408 Handle
= AllocateZeroPool (sizeof(IHANDLE
));
409 if (Handle
== NULL
) {
410 Status
= EFI_OUT_OF_RESOURCES
;
415 // Initialize new handler structure
417 Handle
->Signature
= EFI_HANDLE_SIGNATURE
;
418 InitializeListHead (&Handle
->Protocols
);
421 // Initialize the Key to show that the handle has been created/modified
423 gHandleDatabaseKey
++;
424 Handle
->Key
= gHandleDatabaseKey
;
427 // Add this handle to the list global list of all handles
430 InsertTailList (&gHandleList
, &Handle
->AllHandles
);
433 Status
= CoreValidateHandle (Handle
);
434 if (EFI_ERROR (Status
)) {
439 // Each interface that is added must be unique
441 ASSERT (CoreFindProtocolInterface (Handle
, Protocol
, Interface
) == NULL
);
444 // Initialize the protocol interface structure
446 Prot
->Signature
= PROTOCOL_INTERFACE_SIGNATURE
;
447 Prot
->Handle
= Handle
;
448 Prot
->Protocol
= ProtEntry
;
449 Prot
->Interface
= Interface
;
452 // Initalize OpenProtocol Data base
454 InitializeListHead (&Prot
->OpenList
);
455 Prot
->OpenListCount
= 0;
458 // Add this protocol interface to the head of the supported
459 // protocol list for this handle
461 InsertHeadList (&Handle
->Protocols
, &Prot
->Link
);
464 // Add this protocol interface to the tail of the
467 InsertTailList (&ProtEntry
->Protocols
, &Prot
->ByProtocol
);
470 // Notify the notification list for this protocol
473 CoreNotifyProtocolEntry (ProtEntry
);
475 Status
= EFI_SUCCESS
;
479 // Done, unlock the database and return
481 CoreReleaseProtocolLock ();
482 if (!EFI_ERROR (Status
)) {
484 // Return the new handle back to the caller
486 *UserHandle
= Handle
;
489 // There was an error, clean up
503 Installs a list of protocol interface into the boot services environment.
504 This function calls InstallProtocolInterface() in a loop. If any error
505 occures all the protocols added by this function are removed. This is
506 basically a lib function to save space.
508 @param Handle The handle to install the protocol handlers on,
509 or NULL if a new handle is to be allocated
510 @param ... EFI_GUID followed by protocol instance. A NULL
511 terminates the list. The pairs are the
512 arguments to InstallProtocolInterface(). All the
513 protocols are added to Handle.
515 @retval EFI_INVALID_PARAMETER Handle is NULL.
516 @retval EFI_SUCCESS Protocol interfaces successfully installed.
521 CoreInstallMultipleProtocolInterfaces (
522 IN OUT EFI_HANDLE
*Handle
,
532 EFI_HANDLE OldHandle
;
533 EFI_HANDLE DeviceHandle
;
534 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
536 if (Handle
== NULL
) {
537 return EFI_INVALID_PARAMETER
;
541 // Syncronize with notifcations.
543 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
547 // Check for duplicate device path and install the protocol interfaces
549 VA_START (Args
, Handle
);
550 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
552 // If protocol is NULL, then it's the end of the list
554 Protocol
= VA_ARG (Args
, EFI_GUID
*);
555 if (Protocol
== NULL
) {
559 Interface
= VA_ARG (Args
, VOID
*);
562 // Make sure you are installing on top a device path that has already been added.
564 if (CompareGuid (Protocol
, &gEfiDevicePathProtocolGuid
)) {
566 DevicePath
= Interface
;
567 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &DevicePath
, &DeviceHandle
);
568 if (!EFI_ERROR (Status
) && (DeviceHandle
!= NULL
) && IsDevicePathEnd(DevicePath
)) {
569 Status
= EFI_ALREADY_STARTED
;
577 Status
= CoreInstallProtocolInterface (Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
582 // If there was an error, remove all the interfaces that were installed without any errors
584 if (EFI_ERROR (Status
)) {
586 // Reset the va_arg back to the first argument.
588 VA_START (Args
, Handle
);
589 for (; Index
> 1; Index
--) {
590 Protocol
= VA_ARG (Args
, EFI_GUID
*);
591 Interface
= VA_ARG (Args
, VOID
*);
592 CoreUninstallProtocolInterface (*Handle
, Protocol
, Interface
);
602 CoreRestoreTpl (OldTpl
);
608 Attempts to disconnect all drivers that are using the protocol interface being queried.
609 If failed, reconnect all drivers disconnected.
610 Note: This function doesn't do parameters checking, it's caller's responsibility
611 to pass in valid parameters.
613 @param UserHandle The handle on which the protocol is installed
614 @param Prot The protocol to disconnect drivers from
616 @retval EFI_SUCCESS Drivers using the protocol interface are all
618 @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
622 CoreDisconnectControllersUsingProtocolInterface (
623 IN EFI_HANDLE UserHandle
,
624 IN PROTOCOL_INTERFACE
*Prot
630 OPEN_PROTOCOL_DATA
*OpenData
;
632 Status
= EFI_SUCCESS
;
635 // Attempt to disconnect all drivers from this protocol interface
639 for ( Link
= Prot
->OpenList
.ForwardLink
;
640 (Link
!= &Prot
->OpenList
) && !ItemFound
;
641 Link
= Link
->ForwardLink
) {
642 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
643 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
645 CoreReleaseProtocolLock ();
646 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
647 CoreAcquireProtocolLock ();
648 if (EFI_ERROR (Status
)) {
656 if (!EFI_ERROR (Status
)) {
658 // Attempt to remove BY_HANDLE_PROTOOCL and GET_PROTOCOL and TEST_PROTOCOL Open List items
662 for ( Link
= Prot
->OpenList
.ForwardLink
;
663 (Link
!= &Prot
->OpenList
) && !ItemFound
;
664 Link
= Link
->ForwardLink
) {
665 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
666 if ((OpenData
->Attributes
&
667 (EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
| EFI_OPEN_PROTOCOL_GET_PROTOCOL
| EFI_OPEN_PROTOCOL_TEST_PROTOCOL
)) != 0) {
669 RemoveEntryList (&OpenData
->Link
);
670 Prot
->OpenListCount
--;
671 CoreFreePool (OpenData
);
678 // If there are errors or still has open items in the list, then reconnect all the drivers and return an error
680 if (EFI_ERROR (Status
) || (Prot
->OpenListCount
> 0)) {
681 CoreReleaseProtocolLock ();
682 CoreConnectController (UserHandle
, NULL
, NULL
, TRUE
);
683 CoreAcquireProtocolLock ();
684 Status
= EFI_ACCESS_DENIED
;
693 Uninstalls all instances of a protocol:interfacer from a handle.
694 If the last protocol interface is remove from the handle, the
697 @param UserHandle The handle to remove the protocol handler from
698 @param Protocol The protocol, of protocol:interface, to remove
699 @param Interface The interface, of protocol:interface, to remove
701 @retval EFI_INVALID_PARAMETER Protocol is NULL.
702 @retval EFI_SUCCESS Protocol interface successfully uninstalled.
707 CoreUninstallProtocolInterface (
708 IN EFI_HANDLE UserHandle
,
709 IN EFI_GUID
*Protocol
,
715 PROTOCOL_INTERFACE
*Prot
;
718 // Check that Protocol is valid
720 if (Protocol
== NULL
) {
721 return EFI_INVALID_PARAMETER
;
725 // Check that UserHandle is a valid handle
727 Status
= CoreValidateHandle (UserHandle
);
728 if (EFI_ERROR (Status
)) {
733 // Lock the protocol database
735 CoreAcquireProtocolLock ();
738 // Check that Protocol exists on UserHandle, and Interface matches the interface in the database
740 Prot
= CoreFindProtocolInterface (UserHandle
, Protocol
, Interface
);
742 Status
= EFI_NOT_FOUND
;
747 // Attempt to disconnect all drivers that are using the protocol interface that is about to be removed
749 Status
= CoreDisconnectControllersUsingProtocolInterface (
753 if (EFI_ERROR (Status
)) {
755 // One or more drivers refused to release, so return the error
761 // Remove the protocol interface from the protocol
763 Status
= EFI_NOT_FOUND
;
764 Handle
= (IHANDLE
*)UserHandle
;
765 Prot
= CoreRemoveInterfaceFromProtocol (Handle
, Protocol
, Interface
);
769 // Update the Key to show that the handle has been created/modified
771 gHandleDatabaseKey
++;
772 Handle
->Key
= gHandleDatabaseKey
;
775 // Remove the protocol interface from the handle
777 RemoveEntryList (&Prot
->Link
);
784 Status
= EFI_SUCCESS
;
788 // If there are no more handlers for the handle, free the handle
790 if (IsListEmpty (&Handle
->Protocols
)) {
791 Handle
->Signature
= 0;
792 RemoveEntryList (&Handle
->AllHandles
);
793 CoreFreePool (Handle
);
798 // Done, unlock the database and return
800 CoreReleaseProtocolLock ();
808 Uninstalls a list of protocol interface in the boot services environment.
809 This function calls UnisatllProtocolInterface() in a loop. This is
810 basically a lib function to save space.
812 @param Handle The handle to uninstall the protocol
813 @param ... EFI_GUID followed by protocol instance. A NULL
814 terminates the list. The pairs are the
815 arguments to UninstallProtocolInterface(). All
816 the protocols are added to Handle.
823 CoreUninstallMultipleProtocolInterfaces (
824 IN EFI_HANDLE Handle
,
834 VA_START (Args
, Handle
);
835 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
837 // If protocol is NULL, then it's the end of the list
839 Protocol
= VA_ARG (Args
, EFI_GUID
*);
840 if (Protocol
== NULL
) {
844 Interface
= VA_ARG (Args
, VOID
*);
849 Status
= CoreUninstallProtocolInterface (Handle
, Protocol
, Interface
);
854 // If there was an error, add all the interfaces that were
855 // uninstalled without any errors
857 if (EFI_ERROR (Status
)) {
859 // Reset the va_arg back to the first argument.
861 VA_START (Args
, Handle
);
862 for (; Index
> 1; Index
--) {
863 Protocol
= VA_ARG(Args
, EFI_GUID
*);
864 Interface
= VA_ARG(Args
, VOID
*);
865 CoreInstallProtocolInterface (&Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
875 Locate a certain GUID protocol interface in a Handle's protocols.
877 @param UserHandle The handle to obtain the protocol interface on
878 @param Protocol The GUID of the protocol
880 @return The requested protocol interface for the handle
884 CoreGetProtocolInterface (
885 IN EFI_HANDLE UserHandle
,
886 IN EFI_GUID
*Protocol
890 PROTOCOL_ENTRY
*ProtEntry
;
891 PROTOCOL_INTERFACE
*Prot
;
895 Status
= CoreValidateHandle (UserHandle
);
896 if (EFI_ERROR (Status
)) {
900 Handle
= (IHANDLE
*)UserHandle
;
903 // Look at each protocol interface for a match
905 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
906 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
907 ProtEntry
= Prot
->Protocol
;
908 if (CompareGuid (&ProtEntry
->ProtocolID
, Protocol
)) {
918 Queries a handle to determine if it supports a specified protocol.
920 @param UserHandle The handle being queried.
921 @param Protocol The published unique identifier of the protocol.
922 @param Interface Supplies the address where a pointer to the
923 corresponding Protocol Interface is returned.
925 @retval EFI_SUCCESS The interface information for the specified protocol was returned.
926 @retval EFI_UNSUPPORTED The device does not support the specified protocol.
927 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE..
928 @retval EFI_INVALID_PARAMETER Protocol is NULL.
929 @retval EFI_INVALID_PARAMETER Interface is NULL.
935 IN EFI_HANDLE UserHandle
,
936 IN EFI_GUID
*Protocol
,
940 return CoreOpenProtocol (
946 EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
953 Locates the installed protocol handler for the handle, and
954 invokes it to obtain the protocol interface. Usage information
955 is registered in the protocol data base.
957 @param UserHandle The handle to obtain the protocol interface on
958 @param Protocol The ID of the protocol
959 @param Interface The location to return the protocol interface
960 @param ImageHandle The handle of the Image that is opening the
961 protocol interface specified by Protocol and
963 @param ControllerHandle The controller handle that is requiring this
965 @param Attributes The open mode of the protocol interface
966 specified by Handle and Protocol.
968 @retval EFI_INVALID_PARAMETER Protocol is NULL.
969 @retval EFI_SUCCESS Get the protocol interface.
975 IN EFI_HANDLE UserHandle
,
976 IN EFI_GUID
*Protocol
,
977 OUT VOID
**Interface OPTIONAL
,
978 IN EFI_HANDLE ImageHandle
,
979 IN EFI_HANDLE ControllerHandle
,
984 PROTOCOL_INTERFACE
*Prot
;
986 OPEN_PROTOCOL_DATA
*OpenData
;
993 // Check for invalid Protocol
995 if (Protocol
== NULL
) {
996 return EFI_INVALID_PARAMETER
;
1000 // Check for invalid Interface
1002 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1003 if (Interface
== NULL
) {
1004 return EFI_INVALID_PARAMETER
;
1011 // Check for invalid UserHandle
1013 Status
= CoreValidateHandle (UserHandle
);
1014 if (EFI_ERROR (Status
)) {
1019 // Check for invalid Attributes
1021 switch (Attributes
) {
1022 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1023 Status
= CoreValidateHandle (ImageHandle
);
1024 if (EFI_ERROR (Status
)) {
1027 Status
= CoreValidateHandle (ControllerHandle
);
1028 if (EFI_ERROR (Status
)) {
1031 if (UserHandle
== ControllerHandle
) {
1032 return EFI_INVALID_PARAMETER
;
1035 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1036 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1037 Status
= CoreValidateHandle (ImageHandle
);
1038 if (EFI_ERROR (Status
)) {
1041 Status
= CoreValidateHandle (ControllerHandle
);
1042 if (EFI_ERROR (Status
)) {
1046 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1047 Status
= CoreValidateHandle (ImageHandle
);
1048 if (EFI_ERROR (Status
)) {
1052 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1053 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1054 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1057 return EFI_INVALID_PARAMETER
;
1061 // Lock the protocol database
1063 CoreAcquireProtocolLock ();
1066 // Look at each protocol interface for a match
1068 Prot
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1070 Status
= EFI_UNSUPPORTED
;
1075 // This is the protocol interface entry for this protocol
1077 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1078 *Interface
= Prot
->Interface
;
1080 Status
= EFI_SUCCESS
;
1084 for ( Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
1085 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1086 ExactMatch
= (BOOLEAN
)((OpenData
->AgentHandle
== ImageHandle
) &&
1087 (OpenData
->Attributes
== Attributes
) &&
1088 (OpenData
->ControllerHandle
== ControllerHandle
));
1089 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1092 Status
= EFI_ALREADY_STARTED
;
1096 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_EXCLUSIVE
) != 0) {
1098 } else if (ExactMatch
) {
1099 OpenData
->OpenCount
++;
1100 Status
= EFI_SUCCESS
;
1106 // ByDriver TRUE -> A driver is managing (UserHandle, Protocol)
1107 // ByDriver FALSE -> There are no drivers managing (UserHandle, Protocol)
1108 // Exclusive TRUE -> Something has exclusive access to (UserHandle, Protocol)
1109 // Exclusive FALSE -> Nothing has exclusive access to (UserHandle, Protocol)
1112 switch (Attributes
) {
1113 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1114 if (Exclusive
|| ByDriver
) {
1115 Status
= EFI_ACCESS_DENIED
;
1119 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1120 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1122 Status
= EFI_ACCESS_DENIED
;
1128 for ( Link
= Prot
->OpenList
.ForwardLink
; (Link
!= &Prot
->OpenList
) && (!Disconnect
); Link
= Link
->ForwardLink
) {
1129 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1130 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1132 CoreReleaseProtocolLock ();
1133 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
1134 CoreAcquireProtocolLock ();
1135 if (EFI_ERROR (Status
)) {
1136 Status
= EFI_ACCESS_DENIED
;
1141 } while (Disconnect
);
1144 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1145 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1146 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1147 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1151 if (ImageHandle
== NULL
) {
1152 Status
= EFI_SUCCESS
;
1158 OpenData
= AllocatePool (sizeof(OPEN_PROTOCOL_DATA
));
1159 if (OpenData
== NULL
) {
1160 Status
= EFI_OUT_OF_RESOURCES
;
1162 OpenData
->Signature
= OPEN_PROTOCOL_DATA_SIGNATURE
;
1163 OpenData
->AgentHandle
= ImageHandle
;
1164 OpenData
->ControllerHandle
= ControllerHandle
;
1165 OpenData
->Attributes
= Attributes
;
1166 OpenData
->OpenCount
= 1;
1167 InsertTailList (&Prot
->OpenList
, &OpenData
->Link
);
1168 Prot
->OpenListCount
++;
1169 Status
= EFI_SUCCESS
;
1174 // Done. Release the database lock are return
1176 CoreReleaseProtocolLock ();
1183 Closes a protocol on a handle that was opened using OpenProtocol().
1185 @param UserHandle The handle for the protocol interface that was
1186 previously opened with OpenProtocol(), and is
1188 @param Protocol The published unique identifier of the protocol.
1189 It is the caller's responsibility to pass in a
1191 @param AgentHandle The handle of the agent that is closing the
1193 @param ControllerHandle If the agent that opened a protocol is a driver
1194 that follows the EFI Driver Model, then this
1195 parameter is the controller handle that required
1196 the protocol interface. If the agent does not
1197 follow the EFI Driver Model, then this parameter
1198 is optional and may be NULL.
1200 @retval EFI_SUCCESS The protocol instance was closed.
1201 @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
1203 @retval EFI_NOT_FOUND Can not find the specified protocol or
1210 IN EFI_HANDLE UserHandle
,
1211 IN EFI_GUID
*Protocol
,
1212 IN EFI_HANDLE AgentHandle
,
1213 IN EFI_HANDLE ControllerHandle
1217 PROTOCOL_INTERFACE
*ProtocolInterface
;
1219 OPEN_PROTOCOL_DATA
*OpenData
;
1222 // Check for invalid parameters
1224 Status
= CoreValidateHandle (UserHandle
);
1225 if (EFI_ERROR (Status
)) {
1228 Status
= CoreValidateHandle (AgentHandle
);
1229 if (EFI_ERROR (Status
)) {
1232 if (ControllerHandle
!= NULL
) {
1233 Status
= CoreValidateHandle (ControllerHandle
);
1234 if (EFI_ERROR (Status
)) {
1238 if (Protocol
== NULL
) {
1239 return EFI_INVALID_PARAMETER
;
1243 // Lock the protocol database
1245 CoreAcquireProtocolLock ();
1248 // Look at each protocol interface for a match
1250 Status
= EFI_NOT_FOUND
;
1251 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1252 if (ProtocolInterface
== NULL
) {
1257 // Walk the Open data base looking for AgentHandle
1259 Link
= ProtocolInterface
->OpenList
.ForwardLink
;
1260 while (Link
!= &ProtocolInterface
->OpenList
) {
1261 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1262 Link
= Link
->ForwardLink
;
1263 if ((OpenData
->AgentHandle
== AgentHandle
) && (OpenData
->ControllerHandle
== ControllerHandle
)) {
1264 RemoveEntryList (&OpenData
->Link
);
1265 ProtocolInterface
->OpenListCount
--;
1266 CoreFreePool (OpenData
);
1267 Status
= EFI_SUCCESS
;
1273 // Done. Release the database lock and return.
1275 CoreReleaseProtocolLock ();
1283 Return information about Opened protocols in the system
1285 @param UserHandle The handle to close the protocol interface on
1286 @param Protocol The ID of the protocol
1287 @param EntryBuffer A pointer to a buffer of open protocol information in the
1288 form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
1289 @param EntryCount Number of EntryBuffer entries
1291 @retval EFI_SUCCESS The open protocol information was returned in EntryBuffer,
1292 and the number of entries was returned EntryCount.
1293 @retval EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
1294 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.
1299 CoreOpenProtocolInformation (
1300 IN EFI_HANDLE UserHandle
,
1301 IN EFI_GUID
*Protocol
,
1302 OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
**EntryBuffer
,
1303 OUT UINTN
*EntryCount
1307 PROTOCOL_INTERFACE
*ProtocolInterface
;
1309 OPEN_PROTOCOL_DATA
*OpenData
;
1310 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*Buffer
;
1314 *EntryBuffer
= NULL
;
1318 // Lock the protocol database
1320 CoreAcquireProtocolLock ();
1323 // Look at each protocol interface for a match
1325 Status
= EFI_NOT_FOUND
;
1326 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1327 if (ProtocolInterface
== NULL
) {
1332 // Count the number of Open Entries
1334 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1335 (Link
!= &ProtocolInterface
->OpenList
) ;
1336 Link
= Link
->ForwardLink
) {
1340 ASSERT (Count
== ProtocolInterface
->OpenListCount
);
1343 Size
= sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1345 Size
= Count
* sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1348 Buffer
= AllocatePool (Size
);
1349 if (Buffer
== NULL
) {
1350 Status
= EFI_OUT_OF_RESOURCES
;
1354 Status
= EFI_SUCCESS
;
1355 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1356 (Link
!= &ProtocolInterface
->OpenList
);
1357 Link
= Link
->ForwardLink
, Count
++ ) {
1358 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1360 Buffer
[Count
].AgentHandle
= OpenData
->AgentHandle
;
1361 Buffer
[Count
].ControllerHandle
= OpenData
->ControllerHandle
;
1362 Buffer
[Count
].Attributes
= OpenData
->Attributes
;
1363 Buffer
[Count
].OpenCount
= OpenData
->OpenCount
;
1366 *EntryBuffer
= Buffer
;
1367 *EntryCount
= Count
;
1371 // Done. Release the database lock.
1373 CoreReleaseProtocolLock ();
1381 Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
1384 @param UserHandle The handle from which to retrieve the list of
1385 protocol interface GUIDs.
1386 @param ProtocolBuffer A pointer to the list of protocol interface GUID
1387 pointers that are installed on Handle.
1388 @param ProtocolBufferCount A pointer to the number of GUID pointers present
1391 @retval EFI_SUCCESS The list of protocol interface GUIDs installed
1392 on Handle was returned in ProtocolBuffer. The
1393 number of protocol interface GUIDs was returned
1394 in ProtocolBufferCount.
1395 @retval EFI_INVALID_PARAMETER Handle is NULL.
1396 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
1397 @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
1398 @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
1399 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1405 CoreProtocolsPerHandle (
1406 IN EFI_HANDLE UserHandle
,
1407 OUT EFI_GUID
***ProtocolBuffer
,
1408 OUT UINTN
*ProtocolBufferCount
1413 PROTOCOL_INTERFACE
*Prot
;
1415 UINTN ProtocolCount
;
1418 Status
= CoreValidateHandle (UserHandle
);
1419 if (EFI_ERROR (Status
)) {
1423 Handle
= (IHANDLE
*)UserHandle
;
1425 if (ProtocolBuffer
== NULL
) {
1426 return EFI_INVALID_PARAMETER
;
1429 if (ProtocolBufferCount
== NULL
) {
1430 return EFI_INVALID_PARAMETER
;
1433 *ProtocolBufferCount
= 0;
1437 CoreAcquireProtocolLock ();
1439 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
1444 // If there are no protocol interfaces installed on Handle, then Handle is not a valid EFI_HANDLE
1446 if (ProtocolCount
== 0) {
1447 Status
= EFI_INVALID_PARAMETER
;
1451 Buffer
= AllocatePool (sizeof (EFI_GUID
*) * ProtocolCount
);
1452 if (Buffer
== NULL
) {
1453 Status
= EFI_OUT_OF_RESOURCES
;
1457 *ProtocolBuffer
= Buffer
;
1458 *ProtocolBufferCount
= ProtocolCount
;
1460 for ( Link
= Handle
->Protocols
.ForwardLink
, ProtocolCount
= 0;
1461 Link
!= &Handle
->Protocols
;
1462 Link
= Link
->ForwardLink
, ProtocolCount
++) {
1463 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
1464 Buffer
[ProtocolCount
] = &(Prot
->Protocol
->ProtocolID
);
1466 Status
= EFI_SUCCESS
;
1469 CoreReleaseProtocolLock ();
1476 return handle database key.
1479 @return Handle database key.
1483 CoreGetHandleDatabaseKey (
1487 return gHandleDatabaseKey
;
1493 Go connect any handles that were created or modified while a image executed.
1495 @param Key The Key to show that the handle has been
1500 CoreConnectHandlesByKey (
1506 EFI_HANDLE
*HandleBuffer
;
1511 // Lock the protocol database
1513 CoreAcquireProtocolLock ();
1515 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1516 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1517 if (Handle
->Key
> Key
) {
1522 HandleBuffer
= AllocatePool (Count
* sizeof (EFI_HANDLE
));
1523 if (HandleBuffer
== NULL
) {
1524 CoreReleaseProtocolLock ();
1528 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1529 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1530 if (Handle
->Key
> Key
) {
1531 HandleBuffer
[Count
++] = Handle
;
1536 // Unlock the protocol database
1538 CoreReleaseProtocolLock ();
1541 // Connect all handles whose Key value is greater than Key
1543 for (Index
= 0; Index
< Count
; Index
++) {
1544 CoreConnectController (HandleBuffer
[Index
], NULL
, NULL
, TRUE
);
1547 CoreFreePool(HandleBuffer
);