2 UEFI handle & protocol handling.
4 Copyright (c) 2006 - 2013, 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
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_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 pointer to a handle to install the new
509 protocol interfaces on, or a pointer to NULL
510 if a new handle is to be allocated.
511 @param ... EFI_GUID followed by protocol instance. A NULL
512 terminates the list. The pairs are the
513 arguments to InstallProtocolInterface(). All the
514 protocols are added to Handle.
516 @retval EFI_SUCCESS All the protocol interface was installed.
517 @retval EFI_OUT_OF_RESOURCES There was not enough memory in pool to install all the protocols.
518 @retval EFI_ALREADY_STARTED A Device Path Protocol instance was passed in that is already present in
520 @retval EFI_INVALID_PARAMETER Handle is NULL.
521 @retval EFI_INVALID_PARAMETER Protocol is already installed on the handle specified by Handle.
526 CoreInstallMultipleProtocolInterfaces (
527 IN OUT EFI_HANDLE
*Handle
,
537 EFI_HANDLE OldHandle
;
538 EFI_HANDLE DeviceHandle
;
539 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
541 if (Handle
== NULL
) {
542 return EFI_INVALID_PARAMETER
;
546 // Syncronize with notifcations.
548 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
552 // Check for duplicate device path and install the protocol interfaces
554 VA_START (Args
, Handle
);
555 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
557 // If protocol is NULL, then it's the end of the list
559 Protocol
= VA_ARG (Args
, EFI_GUID
*);
560 if (Protocol
== NULL
) {
564 Interface
= VA_ARG (Args
, VOID
*);
567 // Make sure you are installing on top a device path that has already been added.
569 if (CompareGuid (Protocol
, &gEfiDevicePathProtocolGuid
)) {
571 DevicePath
= Interface
;
572 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &DevicePath
, &DeviceHandle
);
573 if (!EFI_ERROR (Status
) && (DeviceHandle
!= NULL
) && IsDevicePathEnd(DevicePath
)) {
574 Status
= EFI_ALREADY_STARTED
;
582 Status
= CoreInstallProtocolInterface (Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
587 // If there was an error, remove all the interfaces that were installed without any errors
589 if (EFI_ERROR (Status
)) {
591 // Reset the va_arg back to the first argument.
593 VA_START (Args
, Handle
);
594 for (; Index
> 1; Index
--) {
595 Protocol
= VA_ARG (Args
, EFI_GUID
*);
596 Interface
= VA_ARG (Args
, VOID
*);
597 CoreUninstallProtocolInterface (*Handle
, Protocol
, Interface
);
607 CoreRestoreTpl (OldTpl
);
613 Attempts to disconnect all drivers that are using the protocol interface being queried.
614 If failed, reconnect all drivers disconnected.
615 Note: This function doesn't do parameters checking, it's caller's responsibility
616 to pass in valid parameters.
618 @param UserHandle The handle on which the protocol is installed
619 @param Prot The protocol to disconnect drivers from
621 @retval EFI_SUCCESS Drivers using the protocol interface are all
623 @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
627 CoreDisconnectControllersUsingProtocolInterface (
628 IN EFI_HANDLE UserHandle
,
629 IN PROTOCOL_INTERFACE
*Prot
635 OPEN_PROTOCOL_DATA
*OpenData
;
637 Status
= EFI_SUCCESS
;
640 // Attempt to disconnect all drivers from this protocol interface
644 for ( Link
= Prot
->OpenList
.ForwardLink
;
645 (Link
!= &Prot
->OpenList
) && !ItemFound
;
646 Link
= Link
->ForwardLink
) {
647 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
648 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
650 CoreReleaseProtocolLock ();
651 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
652 CoreAcquireProtocolLock ();
653 if (EFI_ERROR (Status
)) {
661 if (!EFI_ERROR (Status
)) {
663 // Attempt to remove BY_HANDLE_PROTOOCL and GET_PROTOCOL and TEST_PROTOCOL Open List items
667 for ( Link
= Prot
->OpenList
.ForwardLink
;
668 (Link
!= &Prot
->OpenList
) && !ItemFound
;
669 Link
= Link
->ForwardLink
) {
670 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
671 if ((OpenData
->Attributes
&
672 (EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
| EFI_OPEN_PROTOCOL_GET_PROTOCOL
| EFI_OPEN_PROTOCOL_TEST_PROTOCOL
)) != 0) {
674 RemoveEntryList (&OpenData
->Link
);
675 Prot
->OpenListCount
--;
676 CoreFreePool (OpenData
);
683 // If there are errors or still has open items in the list, then reconnect all the drivers and return an error
685 if (EFI_ERROR (Status
) || (Prot
->OpenListCount
> 0)) {
686 CoreReleaseProtocolLock ();
687 CoreConnectController (UserHandle
, NULL
, NULL
, TRUE
);
688 CoreAcquireProtocolLock ();
689 Status
= EFI_ACCESS_DENIED
;
698 Uninstalls all instances of a protocol:interfacer from a handle.
699 If the last protocol interface is remove from the handle, the
702 @param UserHandle The handle to remove the protocol handler from
703 @param Protocol The protocol, of protocol:interface, to remove
704 @param Interface The interface, of protocol:interface, to remove
706 @retval EFI_INVALID_PARAMETER Protocol is NULL.
707 @retval EFI_SUCCESS Protocol interface successfully uninstalled.
712 CoreUninstallProtocolInterface (
713 IN EFI_HANDLE UserHandle
,
714 IN EFI_GUID
*Protocol
,
720 PROTOCOL_INTERFACE
*Prot
;
723 // Check that Protocol is valid
725 if (Protocol
== NULL
) {
726 return EFI_INVALID_PARAMETER
;
730 // Check that UserHandle is a valid handle
732 Status
= CoreValidateHandle (UserHandle
);
733 if (EFI_ERROR (Status
)) {
738 // Lock the protocol database
740 CoreAcquireProtocolLock ();
743 // Check that Protocol exists on UserHandle, and Interface matches the interface in the database
745 Prot
= CoreFindProtocolInterface (UserHandle
, Protocol
, Interface
);
747 Status
= EFI_NOT_FOUND
;
752 // Attempt to disconnect all drivers that are using the protocol interface that is about to be removed
754 Status
= CoreDisconnectControllersUsingProtocolInterface (
758 if (EFI_ERROR (Status
)) {
760 // One or more drivers refused to release, so return the error
766 // Remove the protocol interface from the protocol
768 Status
= EFI_NOT_FOUND
;
769 Handle
= (IHANDLE
*)UserHandle
;
770 Prot
= CoreRemoveInterfaceFromProtocol (Handle
, Protocol
, Interface
);
774 // Update the Key to show that the handle has been created/modified
776 gHandleDatabaseKey
++;
777 Handle
->Key
= gHandleDatabaseKey
;
780 // Remove the protocol interface from the handle
782 RemoveEntryList (&Prot
->Link
);
789 Status
= EFI_SUCCESS
;
793 // If there are no more handlers for the handle, free the handle
795 if (IsListEmpty (&Handle
->Protocols
)) {
796 Handle
->Signature
= 0;
797 RemoveEntryList (&Handle
->AllHandles
);
798 CoreFreePool (Handle
);
803 // Done, unlock the database and return
805 CoreReleaseProtocolLock ();
813 Uninstalls a list of protocol interface in the boot services environment.
814 This function calls UnisatllProtocolInterface() in a loop. This is
815 basically a lib function to save space.
817 @param Handle The handle to uninstall the protocol
818 @param ... EFI_GUID followed by protocol instance. A NULL
819 terminates the list. The pairs are the
820 arguments to UninstallProtocolInterface(). All
821 the protocols are added to Handle.
828 CoreUninstallMultipleProtocolInterfaces (
829 IN EFI_HANDLE Handle
,
839 VA_START (Args
, Handle
);
840 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
842 // If protocol is NULL, then it's the end of the list
844 Protocol
= VA_ARG (Args
, EFI_GUID
*);
845 if (Protocol
== NULL
) {
849 Interface
= VA_ARG (Args
, VOID
*);
854 Status
= CoreUninstallProtocolInterface (Handle
, Protocol
, Interface
);
859 // If there was an error, add all the interfaces that were
860 // uninstalled without any errors
862 if (EFI_ERROR (Status
)) {
864 // Reset the va_arg back to the first argument.
866 VA_START (Args
, Handle
);
867 for (; Index
> 1; Index
--) {
868 Protocol
= VA_ARG(Args
, EFI_GUID
*);
869 Interface
= VA_ARG(Args
, VOID
*);
870 CoreInstallProtocolInterface (&Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
880 Locate a certain GUID protocol interface in a Handle's protocols.
882 @param UserHandle The handle to obtain the protocol interface on
883 @param Protocol The GUID of the protocol
885 @return The requested protocol interface for the handle
889 CoreGetProtocolInterface (
890 IN EFI_HANDLE UserHandle
,
891 IN EFI_GUID
*Protocol
895 PROTOCOL_ENTRY
*ProtEntry
;
896 PROTOCOL_INTERFACE
*Prot
;
900 Status
= CoreValidateHandle (UserHandle
);
901 if (EFI_ERROR (Status
)) {
905 Handle
= (IHANDLE
*)UserHandle
;
908 // Look at each protocol interface for a match
910 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
911 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
912 ProtEntry
= Prot
->Protocol
;
913 if (CompareGuid (&ProtEntry
->ProtocolID
, Protocol
)) {
923 Queries a handle to determine if it supports a specified protocol.
925 @param UserHandle The handle being queried.
926 @param Protocol The published unique identifier of the protocol.
927 @param Interface Supplies the address where a pointer to the
928 corresponding Protocol Interface is returned.
930 @retval EFI_SUCCESS The interface information for the specified protocol was returned.
931 @retval EFI_UNSUPPORTED The device does not support the specified protocol.
932 @retval EFI_INVALID_PARAMETER Handle is NULL..
933 @retval EFI_INVALID_PARAMETER Protocol is NULL.
934 @retval EFI_INVALID_PARAMETER Interface is NULL.
940 IN EFI_HANDLE UserHandle
,
941 IN EFI_GUID
*Protocol
,
945 return CoreOpenProtocol (
951 EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
958 Locates the installed protocol handler for the handle, and
959 invokes it to obtain the protocol interface. Usage information
960 is registered in the protocol data base.
962 @param UserHandle The handle to obtain the protocol interface on
963 @param Protocol The ID of the protocol
964 @param Interface The location to return the protocol interface
965 @param ImageHandle The handle of the Image that is opening the
966 protocol interface specified by Protocol and
968 @param ControllerHandle The controller handle that is requiring this
970 @param Attributes The open mode of the protocol interface
971 specified by Handle and Protocol.
973 @retval EFI_INVALID_PARAMETER Protocol is NULL.
974 @retval EFI_SUCCESS Get the protocol interface.
980 IN EFI_HANDLE UserHandle
,
981 IN EFI_GUID
*Protocol
,
982 OUT VOID
**Interface OPTIONAL
,
983 IN EFI_HANDLE ImageHandle
,
984 IN EFI_HANDLE ControllerHandle
,
989 PROTOCOL_INTERFACE
*Prot
;
991 OPEN_PROTOCOL_DATA
*OpenData
;
998 // Check for invalid Protocol
1000 if (Protocol
== NULL
) {
1001 return EFI_INVALID_PARAMETER
;
1005 // Check for invalid Interface
1007 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1008 if (Interface
== NULL
) {
1009 return EFI_INVALID_PARAMETER
;
1016 // Check for invalid UserHandle
1018 Status
= CoreValidateHandle (UserHandle
);
1019 if (EFI_ERROR (Status
)) {
1024 // Check for invalid Attributes
1026 switch (Attributes
) {
1027 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1028 Status
= CoreValidateHandle (ImageHandle
);
1029 if (EFI_ERROR (Status
)) {
1032 Status
= CoreValidateHandle (ControllerHandle
);
1033 if (EFI_ERROR (Status
)) {
1036 if (UserHandle
== ControllerHandle
) {
1037 return EFI_INVALID_PARAMETER
;
1040 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1041 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1042 Status
= CoreValidateHandle (ImageHandle
);
1043 if (EFI_ERROR (Status
)) {
1046 Status
= CoreValidateHandle (ControllerHandle
);
1047 if (EFI_ERROR (Status
)) {
1051 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1052 Status
= CoreValidateHandle (ImageHandle
);
1053 if (EFI_ERROR (Status
)) {
1057 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1058 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1059 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1062 return EFI_INVALID_PARAMETER
;
1066 // Lock the protocol database
1068 CoreAcquireProtocolLock ();
1071 // Look at each protocol interface for a match
1073 Prot
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1075 Status
= EFI_UNSUPPORTED
;
1080 // This is the protocol interface entry for this protocol
1082 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1083 *Interface
= Prot
->Interface
;
1085 Status
= EFI_SUCCESS
;
1089 for ( Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
1090 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1091 ExactMatch
= (BOOLEAN
)((OpenData
->AgentHandle
== ImageHandle
) &&
1092 (OpenData
->Attributes
== Attributes
) &&
1093 (OpenData
->ControllerHandle
== ControllerHandle
));
1094 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1097 Status
= EFI_ALREADY_STARTED
;
1101 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_EXCLUSIVE
) != 0) {
1103 } else if (ExactMatch
) {
1104 OpenData
->OpenCount
++;
1105 Status
= EFI_SUCCESS
;
1111 // ByDriver TRUE -> A driver is managing (UserHandle, Protocol)
1112 // ByDriver FALSE -> There are no drivers managing (UserHandle, Protocol)
1113 // Exclusive TRUE -> Something has exclusive access to (UserHandle, Protocol)
1114 // Exclusive FALSE -> Nothing has exclusive access to (UserHandle, Protocol)
1117 switch (Attributes
) {
1118 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1119 if (Exclusive
|| ByDriver
) {
1120 Status
= EFI_ACCESS_DENIED
;
1124 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1125 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1127 Status
= EFI_ACCESS_DENIED
;
1133 for ( Link
= Prot
->OpenList
.ForwardLink
; (Link
!= &Prot
->OpenList
) && (!Disconnect
); Link
= Link
->ForwardLink
) {
1134 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1135 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1137 CoreReleaseProtocolLock ();
1138 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
1139 CoreAcquireProtocolLock ();
1140 if (EFI_ERROR (Status
)) {
1141 Status
= EFI_ACCESS_DENIED
;
1146 } while (Disconnect
);
1149 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1150 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1151 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1152 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1156 if (ImageHandle
== NULL
) {
1157 Status
= EFI_SUCCESS
;
1163 OpenData
= AllocatePool (sizeof(OPEN_PROTOCOL_DATA
));
1164 if (OpenData
== NULL
) {
1165 Status
= EFI_OUT_OF_RESOURCES
;
1167 OpenData
->Signature
= OPEN_PROTOCOL_DATA_SIGNATURE
;
1168 OpenData
->AgentHandle
= ImageHandle
;
1169 OpenData
->ControllerHandle
= ControllerHandle
;
1170 OpenData
->Attributes
= Attributes
;
1171 OpenData
->OpenCount
= 1;
1172 InsertTailList (&Prot
->OpenList
, &OpenData
->Link
);
1173 Prot
->OpenListCount
++;
1174 Status
= EFI_SUCCESS
;
1179 // Done. Release the database lock are return
1181 CoreReleaseProtocolLock ();
1188 Closes a protocol on a handle that was opened using OpenProtocol().
1190 @param UserHandle The handle for the protocol interface that was
1191 previously opened with OpenProtocol(), and is
1193 @param Protocol The published unique identifier of the protocol.
1194 It is the caller's responsibility to pass in a
1196 @param AgentHandle The handle of the agent that is closing the
1198 @param ControllerHandle If the agent that opened a protocol is a driver
1199 that follows the EFI Driver Model, then this
1200 parameter is the controller handle that required
1201 the protocol interface. If the agent does not
1202 follow the EFI Driver Model, then this parameter
1203 is optional and may be NULL.
1205 @retval EFI_SUCCESS The protocol instance was closed.
1206 @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
1208 @retval EFI_NOT_FOUND Can not find the specified protocol or
1215 IN EFI_HANDLE UserHandle
,
1216 IN EFI_GUID
*Protocol
,
1217 IN EFI_HANDLE AgentHandle
,
1218 IN EFI_HANDLE ControllerHandle
1222 PROTOCOL_INTERFACE
*ProtocolInterface
;
1224 OPEN_PROTOCOL_DATA
*OpenData
;
1227 // Check for invalid parameters
1229 Status
= CoreValidateHandle (UserHandle
);
1230 if (EFI_ERROR (Status
)) {
1233 Status
= CoreValidateHandle (AgentHandle
);
1234 if (EFI_ERROR (Status
)) {
1237 if (ControllerHandle
!= NULL
) {
1238 Status
= CoreValidateHandle (ControllerHandle
);
1239 if (EFI_ERROR (Status
)) {
1243 if (Protocol
== NULL
) {
1244 return EFI_INVALID_PARAMETER
;
1248 // Lock the protocol database
1250 CoreAcquireProtocolLock ();
1253 // Look at each protocol interface for a match
1255 Status
= EFI_NOT_FOUND
;
1256 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1257 if (ProtocolInterface
== NULL
) {
1262 // Walk the Open data base looking for AgentHandle
1264 Link
= ProtocolInterface
->OpenList
.ForwardLink
;
1265 while (Link
!= &ProtocolInterface
->OpenList
) {
1266 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1267 Link
= Link
->ForwardLink
;
1268 if ((OpenData
->AgentHandle
== AgentHandle
) && (OpenData
->ControllerHandle
== ControllerHandle
)) {
1269 RemoveEntryList (&OpenData
->Link
);
1270 ProtocolInterface
->OpenListCount
--;
1271 CoreFreePool (OpenData
);
1272 Status
= EFI_SUCCESS
;
1278 // Done. Release the database lock and return.
1280 CoreReleaseProtocolLock ();
1288 Return information about Opened protocols in the system
1290 @param UserHandle The handle to close the protocol interface on
1291 @param Protocol The ID of the protocol
1292 @param EntryBuffer A pointer to a buffer of open protocol information in the
1293 form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
1294 @param EntryCount Number of EntryBuffer entries
1296 @retval EFI_SUCCESS The open protocol information was returned in EntryBuffer,
1297 and the number of entries was returned EntryCount.
1298 @retval EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
1299 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.
1304 CoreOpenProtocolInformation (
1305 IN EFI_HANDLE UserHandle
,
1306 IN EFI_GUID
*Protocol
,
1307 OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
**EntryBuffer
,
1308 OUT UINTN
*EntryCount
1312 PROTOCOL_INTERFACE
*ProtocolInterface
;
1314 OPEN_PROTOCOL_DATA
*OpenData
;
1315 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*Buffer
;
1319 *EntryBuffer
= NULL
;
1323 // Lock the protocol database
1325 CoreAcquireProtocolLock ();
1328 // Look at each protocol interface for a match
1330 Status
= EFI_NOT_FOUND
;
1331 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1332 if (ProtocolInterface
== NULL
) {
1337 // Count the number of Open Entries
1339 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1340 (Link
!= &ProtocolInterface
->OpenList
) ;
1341 Link
= Link
->ForwardLink
) {
1345 ASSERT (Count
== ProtocolInterface
->OpenListCount
);
1348 Size
= sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1350 Size
= Count
* sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1353 Buffer
= AllocatePool (Size
);
1354 if (Buffer
== NULL
) {
1355 Status
= EFI_OUT_OF_RESOURCES
;
1359 Status
= EFI_SUCCESS
;
1360 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1361 (Link
!= &ProtocolInterface
->OpenList
);
1362 Link
= Link
->ForwardLink
, Count
++ ) {
1363 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1365 Buffer
[Count
].AgentHandle
= OpenData
->AgentHandle
;
1366 Buffer
[Count
].ControllerHandle
= OpenData
->ControllerHandle
;
1367 Buffer
[Count
].Attributes
= OpenData
->Attributes
;
1368 Buffer
[Count
].OpenCount
= OpenData
->OpenCount
;
1371 *EntryBuffer
= Buffer
;
1372 *EntryCount
= Count
;
1376 // Done. Release the database lock.
1378 CoreReleaseProtocolLock ();
1386 Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
1389 @param UserHandle The handle from which to retrieve the list of
1390 protocol interface GUIDs.
1391 @param ProtocolBuffer A pointer to the list of protocol interface GUID
1392 pointers that are installed on Handle.
1393 @param ProtocolBufferCount A pointer to the number of GUID pointers present
1396 @retval EFI_SUCCESS The list of protocol interface GUIDs installed
1397 on Handle was returned in ProtocolBuffer. The
1398 number of protocol interface GUIDs was returned
1399 in ProtocolBufferCount.
1400 @retval EFI_INVALID_PARAMETER Handle is NULL.
1401 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
1402 @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
1403 @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
1404 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1410 CoreProtocolsPerHandle (
1411 IN EFI_HANDLE UserHandle
,
1412 OUT EFI_GUID
***ProtocolBuffer
,
1413 OUT UINTN
*ProtocolBufferCount
1418 PROTOCOL_INTERFACE
*Prot
;
1420 UINTN ProtocolCount
;
1423 Status
= CoreValidateHandle (UserHandle
);
1424 if (EFI_ERROR (Status
)) {
1428 Handle
= (IHANDLE
*)UserHandle
;
1430 if (ProtocolBuffer
== NULL
) {
1431 return EFI_INVALID_PARAMETER
;
1434 if (ProtocolBufferCount
== NULL
) {
1435 return EFI_INVALID_PARAMETER
;
1438 *ProtocolBufferCount
= 0;
1442 CoreAcquireProtocolLock ();
1444 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
1449 // If there are no protocol interfaces installed on Handle, then Handle is not a valid EFI_HANDLE
1451 if (ProtocolCount
== 0) {
1452 Status
= EFI_INVALID_PARAMETER
;
1456 Buffer
= AllocatePool (sizeof (EFI_GUID
*) * ProtocolCount
);
1457 if (Buffer
== NULL
) {
1458 Status
= EFI_OUT_OF_RESOURCES
;
1462 *ProtocolBuffer
= Buffer
;
1463 *ProtocolBufferCount
= ProtocolCount
;
1465 for ( Link
= Handle
->Protocols
.ForwardLink
, ProtocolCount
= 0;
1466 Link
!= &Handle
->Protocols
;
1467 Link
= Link
->ForwardLink
, ProtocolCount
++) {
1468 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
1469 Buffer
[ProtocolCount
] = &(Prot
->Protocol
->ProtocolID
);
1471 Status
= EFI_SUCCESS
;
1474 CoreReleaseProtocolLock ();
1481 return handle database key.
1484 @return Handle database key.
1488 CoreGetHandleDatabaseKey (
1492 return gHandleDatabaseKey
;
1498 Go connect any handles that were created or modified while a image executed.
1500 @param Key The Key to show that the handle has been
1505 CoreConnectHandlesByKey (
1511 EFI_HANDLE
*HandleBuffer
;
1516 // Lock the protocol database
1518 CoreAcquireProtocolLock ();
1520 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1521 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1522 if (Handle
->Key
> Key
) {
1527 HandleBuffer
= AllocatePool (Count
* sizeof (EFI_HANDLE
));
1528 if (HandleBuffer
== NULL
) {
1529 CoreReleaseProtocolLock ();
1533 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1534 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1535 if (Handle
->Key
> Key
) {
1536 HandleBuffer
[Count
++] = Handle
;
1541 // Unlock the protocol database
1543 CoreReleaseProtocolLock ();
1546 // Connect all handles whose Key value is greater than Key
1548 for (Index
= 0; Index
< Count
; Index
++) {
1549 CoreConnectController (HandleBuffer
[Index
], NULL
, NULL
, TRUE
);
1552 CoreFreePool(HandleBuffer
);