2 UEFI handle & protocol handling.
4 Copyright (c) 2006 - 2018, 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
77 if (UserHandle
== NULL
) {
78 return EFI_INVALID_PARAMETER
;
81 for (Link
= gHandleList
.BackLink
; Link
!= &gHandleList
; Link
= Link
->BackLink
) {
82 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
83 if (Handle
== (IHANDLE
*) UserHandle
) {
88 return EFI_INVALID_PARAMETER
;
94 Finds the protocol entry for the requested protocol.
95 The gProtocolDatabaseLock must be owned
97 @param Protocol The ID of the protocol
98 @param Create Create a new entry if not found
100 @return Protocol entry
104 CoreFindProtocolEntry (
105 IN EFI_GUID
*Protocol
,
110 PROTOCOL_ENTRY
*Item
;
111 PROTOCOL_ENTRY
*ProtEntry
;
113 ASSERT_LOCKED(&gProtocolDatabaseLock
);
116 // Search the database for the matching GUID
120 for (Link
= mProtocolDatabase
.ForwardLink
;
121 Link
!= &mProtocolDatabase
;
122 Link
= Link
->ForwardLink
) {
124 Item
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
125 if (CompareGuid (&Item
->ProtocolID
, Protocol
)) {
128 // This is the protocol entry
137 // If the protocol entry was not found and Create is TRUE, then
138 // allocate a new entry
140 if ((ProtEntry
== NULL
) && Create
) {
141 ProtEntry
= AllocatePool (sizeof(PROTOCOL_ENTRY
));
143 if (ProtEntry
!= NULL
) {
145 // Initialize new protocol entry structure
147 ProtEntry
->Signature
= PROTOCOL_ENTRY_SIGNATURE
;
148 CopyGuid ((VOID
*)&ProtEntry
->ProtocolID
, Protocol
);
149 InitializeListHead (&ProtEntry
->Protocols
);
150 InitializeListHead (&ProtEntry
->Notify
);
153 // Add it to protocol database
155 InsertTailList (&mProtocolDatabase
, &ProtEntry
->AllEntries
);
165 Finds the protocol instance for the requested handle and protocol.
166 Note: This function doesn't do parameters checking, it's caller's responsibility
167 to pass in valid parameters.
169 @param Handle The handle to search the protocol on
170 @param Protocol GUID of the protocol
171 @param Interface The interface for the protocol being searched
173 @return Protocol instance (NULL: Not found)
177 CoreFindProtocolInterface (
179 IN EFI_GUID
*Protocol
,
183 PROTOCOL_INTERFACE
*Prot
;
184 PROTOCOL_ENTRY
*ProtEntry
;
187 ASSERT_LOCKED(&gProtocolDatabaseLock
);
191 // Lookup the protocol entry for this protocol ID
194 ProtEntry
= CoreFindProtocolEntry (Protocol
, FALSE
);
195 if (ProtEntry
!= NULL
) {
198 // Look at each protocol interface for any matches
200 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
=Link
->ForwardLink
) {
203 // If this protocol interface matches, remove it
205 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
206 if (Prot
->Interface
== Interface
&& Prot
->Protocol
== ProtEntry
) {
219 Removes an event from a register protocol notify list on a protocol.
221 @param Event The event to search for in the protocol
224 @return EFI_SUCCESS if the event was found and removed.
225 @return EFI_NOT_FOUND if the event was not found in the protocl database.
229 CoreUnregisterProtocolNotifyEvent (
234 PROTOCOL_ENTRY
*ProtEntry
;
235 LIST_ENTRY
*NotifyLink
;
236 PROTOCOL_NOTIFY
*ProtNotify
;
238 CoreAcquireProtocolLock ();
240 for ( Link
= mProtocolDatabase
.ForwardLink
;
241 Link
!= &mProtocolDatabase
;
242 Link
= Link
->ForwardLink
) {
244 ProtEntry
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
246 for ( NotifyLink
= ProtEntry
->Notify
.ForwardLink
;
247 NotifyLink
!= &ProtEntry
->Notify
;
248 NotifyLink
= NotifyLink
->ForwardLink
) {
250 ProtNotify
= CR(NotifyLink
, PROTOCOL_NOTIFY
, Link
, PROTOCOL_NOTIFY_SIGNATURE
);
252 if (ProtNotify
->Event
== Event
) {
253 RemoveEntryList(&ProtNotify
->Link
);
254 CoreFreePool(ProtNotify
);
255 CoreReleaseProtocolLock ();
261 CoreReleaseProtocolLock ();
262 return EFI_NOT_FOUND
;
268 Removes all the events in the protocol database that match Event.
270 @param Event The event to search for in the protocol
273 @return EFI_SUCCESS when done searching the entire database.
277 CoreUnregisterProtocolNotify (
284 Status
= CoreUnregisterProtocolNotifyEvent (Event
);
285 } while (!EFI_ERROR (Status
));
294 Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
295 Calls the private one which contains a BOOLEAN parameter for notifications
297 @param UserHandle The handle to install the protocol handler on,
298 or NULL if a new handle is to be allocated
299 @param Protocol The protocol to add to the handle
300 @param InterfaceType Indicates whether Interface is supplied in
302 @param Interface The interface for the protocol being added
309 CoreInstallProtocolInterface (
310 IN OUT EFI_HANDLE
*UserHandle
,
311 IN EFI_GUID
*Protocol
,
312 IN EFI_INTERFACE_TYPE InterfaceType
,
316 return CoreInstallProtocolInterfaceNotify (
327 Installs a protocol interface into the boot services environment.
329 @param UserHandle The handle to install the protocol handler on,
330 or NULL if a new handle is to be allocated
331 @param Protocol The protocol to add to the handle
332 @param InterfaceType Indicates whether Interface is supplied in
334 @param Interface The interface for the protocol being added
335 @param Notify indicates whether notify the notification list
338 @retval EFI_INVALID_PARAMETER Invalid parameter
339 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
340 @retval EFI_SUCCESS Protocol interface successfully installed
344 CoreInstallProtocolInterfaceNotify (
345 IN OUT EFI_HANDLE
*UserHandle
,
346 IN EFI_GUID
*Protocol
,
347 IN EFI_INTERFACE_TYPE InterfaceType
,
352 PROTOCOL_INTERFACE
*Prot
;
353 PROTOCOL_ENTRY
*ProtEntry
;
356 VOID
*ExistingInterface
;
359 // returns EFI_INVALID_PARAMETER if InterfaceType is invalid.
360 // Also added check for invalid UserHandle and Protocol pointers.
362 if (UserHandle
== NULL
|| Protocol
== NULL
) {
363 return EFI_INVALID_PARAMETER
;
366 if (InterfaceType
!= EFI_NATIVE_INTERFACE
) {
367 return EFI_INVALID_PARAMETER
;
371 // Print debug message
373 DEBUG((DEBUG_INFO
, "InstallProtocolInterface: %g %p\n", Protocol
, Interface
));
375 Status
= EFI_OUT_OF_RESOURCES
;
379 if (*UserHandle
!= NULL
) {
380 Status
= CoreHandleProtocol (*UserHandle
, Protocol
, (VOID
**)&ExistingInterface
);
381 if (!EFI_ERROR (Status
)) {
382 return EFI_INVALID_PARAMETER
;
387 // Lock the protocol database
389 CoreAcquireProtocolLock ();
392 // Lookup the Protocol Entry for the requested protocol
394 ProtEntry
= CoreFindProtocolEntry (Protocol
, TRUE
);
395 if (ProtEntry
== NULL
) {
400 // Allocate a new protocol interface structure
402 Prot
= AllocateZeroPool (sizeof(PROTOCOL_INTERFACE
));
404 Status
= EFI_OUT_OF_RESOURCES
;
409 // If caller didn't supply a handle, allocate a new one
411 Handle
= (IHANDLE
*)*UserHandle
;
412 if (Handle
== NULL
) {
413 Handle
= AllocateZeroPool (sizeof(IHANDLE
));
414 if (Handle
== NULL
) {
415 Status
= EFI_OUT_OF_RESOURCES
;
420 // Initialize new handler structure
422 Handle
->Signature
= EFI_HANDLE_SIGNATURE
;
423 InitializeListHead (&Handle
->Protocols
);
426 // Initialize the Key to show that the handle has been created/modified
428 gHandleDatabaseKey
++;
429 Handle
->Key
= gHandleDatabaseKey
;
432 // Add this handle to the list global list of all handles
435 InsertTailList (&gHandleList
, &Handle
->AllHandles
);
437 Status
= CoreValidateHandle (Handle
);
438 if (EFI_ERROR (Status
)) {
439 DEBUG((DEBUG_ERROR
, "InstallProtocolInterface: input handle at 0x%x is invalid\n", Handle
));
445 // Each interface that is added must be unique
447 ASSERT (CoreFindProtocolInterface (Handle
, Protocol
, Interface
) == NULL
);
450 // Initialize the protocol interface structure
452 Prot
->Signature
= PROTOCOL_INTERFACE_SIGNATURE
;
453 Prot
->Handle
= Handle
;
454 Prot
->Protocol
= ProtEntry
;
455 Prot
->Interface
= Interface
;
458 // Initalize OpenProtocol Data base
460 InitializeListHead (&Prot
->OpenList
);
461 Prot
->OpenListCount
= 0;
464 // Add this protocol interface to the head of the supported
465 // protocol list for this handle
467 InsertHeadList (&Handle
->Protocols
, &Prot
->Link
);
470 // Add this protocol interface to the tail of the
473 InsertTailList (&ProtEntry
->Protocols
, &Prot
->ByProtocol
);
476 // Notify the notification list for this protocol
479 CoreNotifyProtocolEntry (ProtEntry
);
481 Status
= EFI_SUCCESS
;
485 // Done, unlock the database and return
487 CoreReleaseProtocolLock ();
488 if (!EFI_ERROR (Status
)) {
490 // Return the new handle back to the caller
492 *UserHandle
= Handle
;
495 // There was an error, clean up
500 DEBUG((DEBUG_ERROR
, "InstallProtocolInterface: %g %p failed with %r\n", Protocol
, Interface
, Status
));
510 Installs a list of protocol interface into the boot services environment.
511 This function calls InstallProtocolInterface() in a loop. If any error
512 occures all the protocols added by this function are removed. This is
513 basically a lib function to save space.
515 @param Handle The pointer to a handle to install the new
516 protocol interfaces on, or a pointer to NULL
517 if a new handle is to be allocated.
518 @param ... EFI_GUID followed by protocol instance. A NULL
519 terminates the list. The pairs are the
520 arguments to InstallProtocolInterface(). All the
521 protocols are added to Handle.
523 @retval EFI_SUCCESS All the protocol interface was installed.
524 @retval EFI_OUT_OF_RESOURCES There was not enough memory in pool to install all the protocols.
525 @retval EFI_ALREADY_STARTED A Device Path Protocol instance was passed in that is already present in
527 @retval EFI_INVALID_PARAMETER Handle is NULL.
528 @retval EFI_INVALID_PARAMETER Protocol is already installed on the handle specified by Handle.
533 CoreInstallMultipleProtocolInterfaces (
534 IN OUT EFI_HANDLE
*Handle
,
544 EFI_HANDLE OldHandle
;
545 EFI_HANDLE DeviceHandle
;
546 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
548 if (Handle
== NULL
) {
549 return EFI_INVALID_PARAMETER
;
553 // Syncronize with notifcations.
555 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
559 // Check for duplicate device path and install the protocol interfaces
561 VA_START (Args
, Handle
);
562 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
564 // If protocol is NULL, then it's the end of the list
566 Protocol
= VA_ARG (Args
, EFI_GUID
*);
567 if (Protocol
== NULL
) {
571 Interface
= VA_ARG (Args
, VOID
*);
574 // Make sure you are installing on top a device path that has already been added.
576 if (CompareGuid (Protocol
, &gEfiDevicePathProtocolGuid
)) {
578 DevicePath
= Interface
;
579 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &DevicePath
, &DeviceHandle
);
580 if (!EFI_ERROR (Status
) && (DeviceHandle
!= NULL
) && IsDevicePathEnd(DevicePath
)) {
581 Status
= EFI_ALREADY_STARTED
;
589 Status
= CoreInstallProtocolInterface (Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
594 // If there was an error, remove all the interfaces that were installed without any errors
596 if (EFI_ERROR (Status
)) {
598 // Reset the va_arg back to the first argument.
600 VA_START (Args
, Handle
);
601 for (; Index
> 1; Index
--) {
602 Protocol
= VA_ARG (Args
, EFI_GUID
*);
603 Interface
= VA_ARG (Args
, VOID
*);
604 CoreUninstallProtocolInterface (*Handle
, Protocol
, Interface
);
614 CoreRestoreTpl (OldTpl
);
620 Attempts to disconnect all drivers that are using the protocol interface being queried.
621 If failed, reconnect all drivers disconnected.
622 Note: This function doesn't do parameters checking, it's caller's responsibility
623 to pass in valid parameters.
625 @param UserHandle The handle on which the protocol is installed
626 @param Prot The protocol to disconnect drivers from
628 @retval EFI_SUCCESS Drivers using the protocol interface are all
630 @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
634 CoreDisconnectControllersUsingProtocolInterface (
635 IN EFI_HANDLE UserHandle
,
636 IN PROTOCOL_INTERFACE
*Prot
642 OPEN_PROTOCOL_DATA
*OpenData
;
644 Status
= EFI_SUCCESS
;
647 // Attempt to disconnect all drivers from this protocol interface
651 for (Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
652 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
653 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
654 CoreReleaseProtocolLock ();
655 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
656 CoreAcquireProtocolLock ();
657 if (!EFI_ERROR (Status
)) {
665 if (!EFI_ERROR (Status
)) {
667 // Attempt to remove BY_HANDLE_PROTOOCL and GET_PROTOCOL and TEST_PROTOCOL Open List items
669 for (Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
;) {
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) {
673 Link
= RemoveEntryList (&OpenData
->Link
);
674 Prot
->OpenListCount
--;
675 CoreFreePool (OpenData
);
677 Link
= Link
->ForwardLink
;
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
) && (Interface
== NULL
)) {
1008 return EFI_INVALID_PARAMETER
;
1012 // Check for invalid UserHandle
1014 Status
= CoreValidateHandle (UserHandle
);
1015 if (EFI_ERROR (Status
)) {
1020 // Check for invalid Attributes
1022 switch (Attributes
) {
1023 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1024 Status
= CoreValidateHandle (ImageHandle
);
1025 if (EFI_ERROR (Status
)) {
1028 Status
= CoreValidateHandle (ControllerHandle
);
1029 if (EFI_ERROR (Status
)) {
1032 if (UserHandle
== ControllerHandle
) {
1033 return EFI_INVALID_PARAMETER
;
1036 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1037 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1038 Status
= CoreValidateHandle (ImageHandle
);
1039 if (EFI_ERROR (Status
)) {
1042 Status
= CoreValidateHandle (ControllerHandle
);
1043 if (EFI_ERROR (Status
)) {
1047 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1048 Status
= CoreValidateHandle (ImageHandle
);
1049 if (EFI_ERROR (Status
)) {
1053 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1054 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1055 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1058 return EFI_INVALID_PARAMETER
;
1062 // Lock the protocol database
1064 CoreAcquireProtocolLock ();
1067 // Look at each protocol interface for a match
1069 Prot
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1071 Status
= EFI_UNSUPPORTED
;
1075 Status
= EFI_SUCCESS
;
1079 for ( Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
1080 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1081 ExactMatch
= (BOOLEAN
)((OpenData
->AgentHandle
== ImageHandle
) &&
1082 (OpenData
->Attributes
== Attributes
) &&
1083 (OpenData
->ControllerHandle
== ControllerHandle
));
1084 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1087 Status
= EFI_ALREADY_STARTED
;
1091 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_EXCLUSIVE
) != 0) {
1093 } else if (ExactMatch
) {
1094 OpenData
->OpenCount
++;
1095 Status
= EFI_SUCCESS
;
1101 // ByDriver TRUE -> A driver is managing (UserHandle, Protocol)
1102 // ByDriver FALSE -> There are no drivers managing (UserHandle, Protocol)
1103 // Exclusive TRUE -> Something has exclusive access to (UserHandle, Protocol)
1104 // Exclusive FALSE -> Nothing has exclusive access to (UserHandle, Protocol)
1107 switch (Attributes
) {
1108 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1109 if (Exclusive
|| ByDriver
) {
1110 Status
= EFI_ACCESS_DENIED
;
1114 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1115 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1117 Status
= EFI_ACCESS_DENIED
;
1123 for (Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
1124 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1125 if ((OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) != 0) {
1127 CoreReleaseProtocolLock ();
1128 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
1129 CoreAcquireProtocolLock ();
1130 if (EFI_ERROR (Status
)) {
1131 Status
= EFI_ACCESS_DENIED
;
1138 } while (Disconnect
);
1141 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1142 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1143 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1144 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1148 if (ImageHandle
== NULL
) {
1149 Status
= EFI_SUCCESS
;
1155 OpenData
= AllocatePool (sizeof(OPEN_PROTOCOL_DATA
));
1156 if (OpenData
== NULL
) {
1157 Status
= EFI_OUT_OF_RESOURCES
;
1159 OpenData
->Signature
= OPEN_PROTOCOL_DATA_SIGNATURE
;
1160 OpenData
->AgentHandle
= ImageHandle
;
1161 OpenData
->ControllerHandle
= ControllerHandle
;
1162 OpenData
->Attributes
= Attributes
;
1163 OpenData
->OpenCount
= 1;
1164 InsertTailList (&Prot
->OpenList
, &OpenData
->Link
);
1165 Prot
->OpenListCount
++;
1166 Status
= EFI_SUCCESS
;
1171 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1173 // Keep Interface unmodified in case of any Error
1174 // except EFI_ALREADY_STARTED and EFI_UNSUPPORTED.
1176 if (!EFI_ERROR (Status
) || Status
== EFI_ALREADY_STARTED
) {
1178 // According to above logic, if 'Prot' is NULL, then the 'Status' must be
1179 // EFI_UNSUPPORTED. Here the 'Status' is not EFI_UNSUPPORTED, so 'Prot'
1180 // must be not NULL.
1182 // The ASSERT here is for addressing a false positive NULL pointer
1183 // dereference issue raised from static analysis.
1185 ASSERT (Prot
!= NULL
);
1187 // EFI_ALREADY_STARTED is not an error for bus driver.
1188 // Return the corresponding protocol interface.
1190 *Interface
= Prot
->Interface
;
1191 } else if (Status
== EFI_UNSUPPORTED
) {
1193 // Return NULL Interface if Unsupported Protocol.
1200 // Done. Release the database lock and return
1202 CoreReleaseProtocolLock ();
1209 Closes a protocol on a handle that was opened using OpenProtocol().
1211 @param UserHandle The handle for the protocol interface that was
1212 previously opened with OpenProtocol(), and is
1214 @param Protocol The published unique identifier of the protocol.
1215 It is the caller's responsibility to pass in a
1217 @param AgentHandle The handle of the agent that is closing the
1219 @param ControllerHandle If the agent that opened a protocol is a driver
1220 that follows the EFI Driver Model, then this
1221 parameter is the controller handle that required
1222 the protocol interface. If the agent does not
1223 follow the EFI Driver Model, then this parameter
1224 is optional and may be NULL.
1226 @retval EFI_SUCCESS The protocol instance was closed.
1227 @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
1229 @retval EFI_NOT_FOUND Can not find the specified protocol or
1236 IN EFI_HANDLE UserHandle
,
1237 IN EFI_GUID
*Protocol
,
1238 IN EFI_HANDLE AgentHandle
,
1239 IN EFI_HANDLE ControllerHandle
1243 PROTOCOL_INTERFACE
*ProtocolInterface
;
1245 OPEN_PROTOCOL_DATA
*OpenData
;
1248 // Check for invalid parameters
1250 Status
= CoreValidateHandle (UserHandle
);
1251 if (EFI_ERROR (Status
)) {
1254 Status
= CoreValidateHandle (AgentHandle
);
1255 if (EFI_ERROR (Status
)) {
1258 if (ControllerHandle
!= NULL
) {
1259 Status
= CoreValidateHandle (ControllerHandle
);
1260 if (EFI_ERROR (Status
)) {
1264 if (Protocol
== NULL
) {
1265 return EFI_INVALID_PARAMETER
;
1269 // Lock the protocol database
1271 CoreAcquireProtocolLock ();
1274 // Look at each protocol interface for a match
1276 Status
= EFI_NOT_FOUND
;
1277 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1278 if (ProtocolInterface
== NULL
) {
1283 // Walk the Open data base looking for AgentHandle
1285 Link
= ProtocolInterface
->OpenList
.ForwardLink
;
1286 while (Link
!= &ProtocolInterface
->OpenList
) {
1287 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1288 Link
= Link
->ForwardLink
;
1289 if ((OpenData
->AgentHandle
== AgentHandle
) && (OpenData
->ControllerHandle
== ControllerHandle
)) {
1290 RemoveEntryList (&OpenData
->Link
);
1291 ProtocolInterface
->OpenListCount
--;
1292 CoreFreePool (OpenData
);
1293 Status
= EFI_SUCCESS
;
1299 // Done. Release the database lock and return.
1301 CoreReleaseProtocolLock ();
1309 Return information about Opened protocols in the system
1311 @param UserHandle The handle to close the protocol interface on
1312 @param Protocol The ID of the protocol
1313 @param EntryBuffer A pointer to a buffer of open protocol information in the
1314 form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
1315 @param EntryCount Number of EntryBuffer entries
1317 @retval EFI_SUCCESS The open protocol information was returned in EntryBuffer,
1318 and the number of entries was returned EntryCount.
1319 @retval EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
1320 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.
1325 CoreOpenProtocolInformation (
1326 IN EFI_HANDLE UserHandle
,
1327 IN EFI_GUID
*Protocol
,
1328 OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
**EntryBuffer
,
1329 OUT UINTN
*EntryCount
1333 PROTOCOL_INTERFACE
*ProtocolInterface
;
1335 OPEN_PROTOCOL_DATA
*OpenData
;
1336 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*Buffer
;
1340 *EntryBuffer
= NULL
;
1344 // Lock the protocol database
1346 CoreAcquireProtocolLock ();
1349 // Look at each protocol interface for a match
1351 Status
= EFI_NOT_FOUND
;
1352 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1353 if (ProtocolInterface
== NULL
) {
1358 // Count the number of Open Entries
1360 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1361 (Link
!= &ProtocolInterface
->OpenList
) ;
1362 Link
= Link
->ForwardLink
) {
1366 ASSERT (Count
== ProtocolInterface
->OpenListCount
);
1369 Size
= sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1371 Size
= Count
* sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1374 Buffer
= AllocatePool (Size
);
1375 if (Buffer
== NULL
) {
1376 Status
= EFI_OUT_OF_RESOURCES
;
1380 Status
= EFI_SUCCESS
;
1381 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1382 (Link
!= &ProtocolInterface
->OpenList
);
1383 Link
= Link
->ForwardLink
, Count
++ ) {
1384 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1386 Buffer
[Count
].AgentHandle
= OpenData
->AgentHandle
;
1387 Buffer
[Count
].ControllerHandle
= OpenData
->ControllerHandle
;
1388 Buffer
[Count
].Attributes
= OpenData
->Attributes
;
1389 Buffer
[Count
].OpenCount
= OpenData
->OpenCount
;
1392 *EntryBuffer
= Buffer
;
1393 *EntryCount
= Count
;
1397 // Done. Release the database lock.
1399 CoreReleaseProtocolLock ();
1407 Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
1410 @param UserHandle The handle from which to retrieve the list of
1411 protocol interface GUIDs.
1412 @param ProtocolBuffer A pointer to the list of protocol interface GUID
1413 pointers that are installed on Handle.
1414 @param ProtocolBufferCount A pointer to the number of GUID pointers present
1417 @retval EFI_SUCCESS The list of protocol interface GUIDs installed
1418 on Handle was returned in ProtocolBuffer. The
1419 number of protocol interface GUIDs was returned
1420 in ProtocolBufferCount.
1421 @retval EFI_INVALID_PARAMETER Handle is NULL.
1422 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
1423 @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
1424 @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
1425 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1431 CoreProtocolsPerHandle (
1432 IN EFI_HANDLE UserHandle
,
1433 OUT EFI_GUID
***ProtocolBuffer
,
1434 OUT UINTN
*ProtocolBufferCount
1439 PROTOCOL_INTERFACE
*Prot
;
1441 UINTN ProtocolCount
;
1444 Status
= CoreValidateHandle (UserHandle
);
1445 if (EFI_ERROR (Status
)) {
1449 Handle
= (IHANDLE
*)UserHandle
;
1451 if (ProtocolBuffer
== NULL
) {
1452 return EFI_INVALID_PARAMETER
;
1455 if (ProtocolBufferCount
== NULL
) {
1456 return EFI_INVALID_PARAMETER
;
1459 *ProtocolBufferCount
= 0;
1463 CoreAcquireProtocolLock ();
1465 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
1470 // If there are no protocol interfaces installed on Handle, then Handle is not a valid EFI_HANDLE
1472 if (ProtocolCount
== 0) {
1473 Status
= EFI_INVALID_PARAMETER
;
1477 Buffer
= AllocatePool (sizeof (EFI_GUID
*) * ProtocolCount
);
1478 if (Buffer
== NULL
) {
1479 Status
= EFI_OUT_OF_RESOURCES
;
1483 *ProtocolBuffer
= Buffer
;
1484 *ProtocolBufferCount
= ProtocolCount
;
1486 for ( Link
= Handle
->Protocols
.ForwardLink
, ProtocolCount
= 0;
1487 Link
!= &Handle
->Protocols
;
1488 Link
= Link
->ForwardLink
, ProtocolCount
++) {
1489 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
1490 Buffer
[ProtocolCount
] = &(Prot
->Protocol
->ProtocolID
);
1492 Status
= EFI_SUCCESS
;
1495 CoreReleaseProtocolLock ();
1502 return handle database key.
1505 @return Handle database key.
1509 CoreGetHandleDatabaseKey (
1513 return gHandleDatabaseKey
;
1519 Go connect any handles that were created or modified while a image executed.
1521 @param Key The Key to show that the handle has been
1526 CoreConnectHandlesByKey (
1532 EFI_HANDLE
*HandleBuffer
;
1537 // Lock the protocol database
1539 CoreAcquireProtocolLock ();
1541 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1542 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1543 if (Handle
->Key
> Key
) {
1548 HandleBuffer
= AllocatePool (Count
* sizeof (EFI_HANDLE
));
1549 if (HandleBuffer
== NULL
) {
1550 CoreReleaseProtocolLock ();
1554 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1555 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1556 if (Handle
->Key
> Key
) {
1557 HandleBuffer
[Count
++] = Handle
;
1562 // Unlock the protocol database
1564 CoreReleaseProtocolLock ();
1567 // Connect all handles whose Key value is greater than Key
1569 for (Index
= 0; Index
< Count
; Index
++) {
1570 CoreConnectController (HandleBuffer
[Index
], NULL
, NULL
, TRUE
);
1573 CoreFreePool(HandleBuffer
);