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.
19 // mProtocolDatabase - A list of all protocols in the system. (simple list for now)
20 // gHandleList - A list of all the handles in the system
21 // gProtocolDatabaseLock - Lock to protect the mProtocolDatabase
22 // gHandleDatabaseKey - The Key to show that the handle has been created/modified
24 LIST_ENTRY mProtocolDatabase
= INITIALIZE_LIST_HEAD_VARIABLE (mProtocolDatabase
);
25 LIST_ENTRY gHandleList
= INITIALIZE_LIST_HEAD_VARIABLE (gHandleList
);
26 EFI_LOCK gProtocolDatabaseLock
= EFI_INITIALIZE_LOCK_VARIABLE (TPL_NOTIFY
);
27 UINT64 gHandleDatabaseKey
= 0;
32 Acquire lock on gProtocolDatabaseLock.
36 CoreAcquireProtocolLock (
40 CoreAcquireLock (&gProtocolDatabaseLock
);
46 Release lock on gProtocolDatabaseLock.
50 CoreReleaseProtocolLock (
54 CoreReleaseLock (&gProtocolDatabaseLock
);
60 Check whether a handle is a valid EFI_HANDLE
62 @param UserHandle The handle to check
64 @retval EFI_INVALID_PARAMETER The handle is NULL or not a valid EFI_HANDLE.
65 @retval EFI_SUCCESS The handle is valid EFI_HANDLE.
70 IN EFI_HANDLE UserHandle
75 Handle
= (IHANDLE
*)UserHandle
;
77 return EFI_INVALID_PARAMETER
;
79 if (Handle
->Signature
!= EFI_HANDLE_SIGNATURE
) {
80 return EFI_INVALID_PARAMETER
;
88 Finds the protocol entry for the requested protocol.
89 The gProtocolDatabaseLock must be owned
91 @param Protocol The ID of the protocol
92 @param Create Create a new entry if not found
94 @return Protocol entry
98 CoreFindProtocolEntry (
99 IN EFI_GUID
*Protocol
,
104 PROTOCOL_ENTRY
*Item
;
105 PROTOCOL_ENTRY
*ProtEntry
;
107 ASSERT_LOCKED(&gProtocolDatabaseLock
);
110 // Search the database for the matching GUID
114 for (Link
= mProtocolDatabase
.ForwardLink
;
115 Link
!= &mProtocolDatabase
;
116 Link
= Link
->ForwardLink
) {
118 Item
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
119 if (CompareGuid (&Item
->ProtocolID
, Protocol
)) {
122 // This is the protocol entry
131 // If the protocol entry was not found and Create is TRUE, then
132 // allocate a new entry
134 if ((ProtEntry
== NULL
) && Create
) {
135 ProtEntry
= AllocatePool (sizeof(PROTOCOL_ENTRY
));
137 if (ProtEntry
!= NULL
) {
139 // Initialize new protocol entry structure
141 ProtEntry
->Signature
= PROTOCOL_ENTRY_SIGNATURE
;
142 CopyGuid ((VOID
*)&ProtEntry
->ProtocolID
, Protocol
);
143 InitializeListHead (&ProtEntry
->Protocols
);
144 InitializeListHead (&ProtEntry
->Notify
);
147 // Add it to protocol database
149 InsertTailList (&mProtocolDatabase
, &ProtEntry
->AllEntries
);
159 Finds the protocol instance for the requested handle and protocol.
160 Note: This function doesn't do parameters checking, it's caller's responsibility
161 to pass in valid parameters.
163 @param Handle The handle to search the protocol on
164 @param Protocol GUID of the protocol
165 @param Interface The interface for the protocol being searched
167 @return Protocol instance (NULL: Not found)
171 CoreFindProtocolInterface (
173 IN EFI_GUID
*Protocol
,
177 PROTOCOL_INTERFACE
*Prot
;
178 PROTOCOL_ENTRY
*ProtEntry
;
181 ASSERT_LOCKED(&gProtocolDatabaseLock
);
185 // Lookup the protocol entry for this protocol ID
188 ProtEntry
= CoreFindProtocolEntry (Protocol
, FALSE
);
189 if (ProtEntry
!= NULL
) {
192 // Look at each protocol interface for any matches
194 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
=Link
->ForwardLink
) {
197 // If this protocol interface matches, remove it
199 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
200 if (Prot
->Interface
== Interface
&& Prot
->Protocol
== ProtEntry
) {
213 Removes an event from a register protocol notify list on a protocol.
215 @param Event The event to search for in the protocol
218 @return EFI_SUCCESS if the event was found and removed.
219 @return EFI_NOT_FOUND if the event was not found in the protocl database.
223 CoreUnregisterProtocolNotifyEvent (
228 PROTOCOL_ENTRY
*ProtEntry
;
229 LIST_ENTRY
*NotifyLink
;
230 PROTOCOL_NOTIFY
*ProtNotify
;
232 CoreAcquireProtocolLock ();
234 for ( Link
= mProtocolDatabase
.ForwardLink
;
235 Link
!= &mProtocolDatabase
;
236 Link
= Link
->ForwardLink
) {
238 ProtEntry
= CR(Link
, PROTOCOL_ENTRY
, AllEntries
, PROTOCOL_ENTRY_SIGNATURE
);
240 for ( NotifyLink
= ProtEntry
->Notify
.ForwardLink
;
241 NotifyLink
!= &ProtEntry
->Notify
;
242 NotifyLink
= NotifyLink
->ForwardLink
) {
244 ProtNotify
= CR(NotifyLink
, PROTOCOL_NOTIFY
, Link
, PROTOCOL_NOTIFY_SIGNATURE
);
246 if (ProtNotify
->Event
== Event
) {
247 RemoveEntryList(&ProtNotify
->Link
);
248 CoreFreePool(ProtNotify
);
249 CoreReleaseProtocolLock ();
255 CoreReleaseProtocolLock ();
256 return EFI_NOT_FOUND
;
262 Removes all the events in the protocol database that match Event.
264 @param Event The event to search for in the protocol
267 @return EFI_SUCCESS when done searching the entire database.
271 CoreUnregisterProtocolNotify (
278 Status
= CoreUnregisterProtocolNotifyEvent (Event
);
279 } while (!EFI_ERROR (Status
));
288 Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
289 Calls the private one which contains a BOOLEAN parameter for notifications
291 @param UserHandle The handle to install the protocol handler on,
292 or NULL if a new handle is to be allocated
293 @param Protocol The protocol to add to the handle
294 @param InterfaceType Indicates whether Interface is supplied in
296 @param Interface The interface for the protocol being added
303 CoreInstallProtocolInterface (
304 IN OUT EFI_HANDLE
*UserHandle
,
305 IN EFI_GUID
*Protocol
,
306 IN EFI_INTERFACE_TYPE InterfaceType
,
310 return CoreInstallProtocolInterfaceNotify (
321 Installs a protocol interface into the boot services environment.
323 @param UserHandle The handle to install the protocol handler on,
324 or NULL if a new handle is to be allocated
325 @param Protocol The protocol to add to the handle
326 @param InterfaceType Indicates whether Interface is supplied in
328 @param Interface The interface for the protocol being added
329 @param Notify indicates whether notify the notification list
332 @retval EFI_INVALID_PARAMETER Invalid parameter
333 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
334 @retval EFI_SUCCESS Protocol interface successfully installed
338 CoreInstallProtocolInterfaceNotify (
339 IN OUT EFI_HANDLE
*UserHandle
,
340 IN EFI_GUID
*Protocol
,
341 IN EFI_INTERFACE_TYPE InterfaceType
,
346 PROTOCOL_INTERFACE
*Prot
;
347 PROTOCOL_ENTRY
*ProtEntry
;
350 VOID
*ExistingInterface
;
353 // returns EFI_INVALID_PARAMETER if InterfaceType is invalid.
354 // Also added check for invalid UserHandle and Protocol pointers.
356 if (UserHandle
== NULL
|| Protocol
== NULL
) {
357 return EFI_INVALID_PARAMETER
;
360 if (InterfaceType
!= EFI_NATIVE_INTERFACE
) {
361 return EFI_INVALID_PARAMETER
;
365 // Print debug message
367 DEBUG((DEBUG_LOAD
| DEBUG_INFO
, "InstallProtocolInterface: %g %p\n", Protocol
, Interface
));
369 Status
= EFI_OUT_OF_RESOURCES
;
373 if (*UserHandle
!= NULL
) {
374 Status
= CoreHandleProtocol (*UserHandle
, Protocol
, (VOID
**)&ExistingInterface
);
375 if (!EFI_ERROR (Status
)) {
376 return EFI_INVALID_PARAMETER
;
381 // Lock the protocol database
383 CoreAcquireProtocolLock ();
386 // Lookup the Protocol Entry for the requested protocol
388 ProtEntry
= CoreFindProtocolEntry (Protocol
, TRUE
);
389 if (ProtEntry
== NULL
) {
394 // Allocate a new protocol interface structure
396 Prot
= AllocateZeroPool (sizeof(PROTOCOL_INTERFACE
));
398 Status
= EFI_OUT_OF_RESOURCES
;
403 // If caller didn't supply a handle, allocate a new one
405 Handle
= (IHANDLE
*)*UserHandle
;
406 if (Handle
== NULL
) {
407 Handle
= AllocateZeroPool (sizeof(IHANDLE
));
408 if (Handle
== NULL
) {
409 Status
= EFI_OUT_OF_RESOURCES
;
414 // Initialize new handler structure
416 Handle
->Signature
= EFI_HANDLE_SIGNATURE
;
417 InitializeListHead (&Handle
->Protocols
);
420 // Initialize the Key to show that the handle has been created/modified
422 gHandleDatabaseKey
++;
423 Handle
->Key
= gHandleDatabaseKey
;
426 // Add this handle to the list global list of all handles
429 InsertTailList (&gHandleList
, &Handle
->AllHandles
);
432 Status
= CoreValidateHandle (Handle
);
433 if (EFI_ERROR (Status
)) {
438 // Each interface that is added must be unique
440 ASSERT (CoreFindProtocolInterface (Handle
, Protocol
, Interface
) == NULL
);
443 // Initialize the protocol interface structure
445 Prot
->Signature
= PROTOCOL_INTERFACE_SIGNATURE
;
446 Prot
->Handle
= Handle
;
447 Prot
->Protocol
= ProtEntry
;
448 Prot
->Interface
= Interface
;
451 // Initalize OpenProtocol Data base
453 InitializeListHead (&Prot
->OpenList
);
454 Prot
->OpenListCount
= 0;
457 // Add this protocol interface to the head of the supported
458 // protocol list for this handle
460 InsertHeadList (&Handle
->Protocols
, &Prot
->Link
);
463 // Add this protocol interface to the tail of the
466 InsertTailList (&ProtEntry
->Protocols
, &Prot
->ByProtocol
);
469 // Notify the notification list for this protocol
472 CoreNotifyProtocolEntry (ProtEntry
);
474 Status
= EFI_SUCCESS
;
478 // Done, unlock the database and return
480 CoreReleaseProtocolLock ();
481 if (!EFI_ERROR (Status
)) {
483 // Return the new handle back to the caller
485 *UserHandle
= Handle
;
488 // There was an error, clean up
502 Installs a list of protocol interface into the boot services environment.
503 This function calls InstallProtocolInterface() in a loop. If any error
504 occures all the protocols added by this function are removed. This is
505 basically a lib function to save space.
507 @param Handle The handle to install the protocol handlers on,
508 or NULL if a new handle is to be allocated
509 @param ... EFI_GUID followed by protocol instance. A NULL
510 terminates the list. The pairs are the
511 arguments to InstallProtocolInterface(). All the
512 protocols are added to Handle.
514 @retval EFI_INVALID_PARAMETER Handle is NULL.
515 @retval EFI_SUCCESS Protocol interfaces successfully installed.
520 CoreInstallMultipleProtocolInterfaces (
521 IN OUT EFI_HANDLE
*Handle
,
531 EFI_HANDLE OldHandle
;
532 EFI_HANDLE DeviceHandle
;
533 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
535 if (Handle
== NULL
) {
536 return EFI_INVALID_PARAMETER
;
540 // Syncronize with notifcations.
542 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
546 // Check for duplicate device path and install the protocol interfaces
548 VA_START (Args
, Handle
);
549 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
551 // If protocol is NULL, then it's the end of the list
553 Protocol
= VA_ARG (Args
, EFI_GUID
*);
554 if (Protocol
== NULL
) {
558 Interface
= VA_ARG (Args
, VOID
*);
561 // Make sure you are installing on top a device path that has already been added.
563 if (CompareGuid (Protocol
, &gEfiDevicePathProtocolGuid
)) {
565 DevicePath
= Interface
;
566 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &DevicePath
, &DeviceHandle
);
567 if (!EFI_ERROR (Status
) && (DeviceHandle
!= NULL
) && IsDevicePathEnd(DevicePath
)) {
568 Status
= EFI_ALREADY_STARTED
;
576 Status
= CoreInstallProtocolInterface (Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
580 // If there was an error, remove all the interfaces that were installed without any errors
582 if (EFI_ERROR (Status
)) {
584 // Reset the va_arg back to the first argument.
586 VA_START (Args
, Handle
);
587 for (; Index
> 1; Index
--) {
588 Protocol
= VA_ARG (Args
, EFI_GUID
*);
589 Interface
= VA_ARG (Args
, VOID
*);
590 CoreUninstallProtocolInterface (*Handle
, Protocol
, Interface
);
598 CoreRestoreTpl (OldTpl
);
604 Attempts to disconnect all drivers that are using the protocol interface being queried.
605 If failed, reconnect all drivers disconnected.
606 Note: This function doesn't do parameters checking, it's caller's responsibility
607 to pass in valid parameters.
609 @param UserHandle The handle on which the protocol is installed
610 @param Prot The protocol to disconnect drivers from
612 @retval EFI_SUCCESS Drivers using the protocol interface are all
614 @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
618 CoreDisconnectControllersUsingProtocolInterface (
619 IN EFI_HANDLE UserHandle
,
620 IN PROTOCOL_INTERFACE
*Prot
626 OPEN_PROTOCOL_DATA
*OpenData
;
628 Status
= EFI_SUCCESS
;
631 // Attempt to disconnect all drivers from this protocol interface
635 for ( Link
= Prot
->OpenList
.ForwardLink
;
636 (Link
!= &Prot
->OpenList
) && !ItemFound
;
637 Link
= Link
->ForwardLink
) {
638 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
639 if (OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) {
641 CoreReleaseProtocolLock ();
642 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
643 CoreAcquireProtocolLock ();
644 if (EFI_ERROR (Status
)) {
652 if (!EFI_ERROR (Status
)) {
654 // Attempt to remove BY_HANDLE_PROTOOCL and GET_PROTOCOL and TEST_PROTOCOL Open List items
658 for ( Link
= Prot
->OpenList
.ForwardLink
;
659 (Link
!= &Prot
->OpenList
) && !ItemFound
;
660 Link
= Link
->ForwardLink
) {
661 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
662 if (OpenData
->Attributes
&
663 (EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
| EFI_OPEN_PROTOCOL_GET_PROTOCOL
| EFI_OPEN_PROTOCOL_TEST_PROTOCOL
)) {
665 RemoveEntryList (&OpenData
->Link
);
666 Prot
->OpenListCount
--;
667 CoreFreePool (OpenData
);
674 // If there are errors or still has open items in the list, then reconnect all the drivers and return an error
676 if (EFI_ERROR (Status
) || (Prot
->OpenListCount
> 0)) {
677 CoreReleaseProtocolLock ();
678 CoreConnectController (UserHandle
, NULL
, NULL
, TRUE
);
679 CoreAcquireProtocolLock ();
680 Status
= EFI_ACCESS_DENIED
;
689 Uninstalls all instances of a protocol:interfacer from a handle.
690 If the last protocol interface is remove from the handle, the
693 @param UserHandle The handle to remove the protocol handler from
694 @param Protocol The protocol, of protocol:interface, to remove
695 @param Interface The interface, of protocol:interface, to remove
697 @retval EFI_INVALID_PARAMETER Protocol is NULL.
698 @retval EFI_SUCCESS Protocol interface successfully uninstalled.
703 CoreUninstallProtocolInterface (
704 IN EFI_HANDLE UserHandle
,
705 IN EFI_GUID
*Protocol
,
711 PROTOCOL_INTERFACE
*Prot
;
714 // Check that Protocol is valid
716 if (Protocol
== NULL
) {
717 return EFI_INVALID_PARAMETER
;
721 // Check that UserHandle is a valid handle
723 Status
= CoreValidateHandle (UserHandle
);
724 if (EFI_ERROR (Status
)) {
729 // Lock the protocol database
731 CoreAcquireProtocolLock ();
734 // Check that Protocol exists on UserHandle, and Interface matches the interface in the database
736 Prot
= CoreFindProtocolInterface (UserHandle
, Protocol
, Interface
);
738 Status
= EFI_NOT_FOUND
;
743 // Attempt to disconnect all drivers that are using the protocol interface that is about to be removed
745 Status
= CoreDisconnectControllersUsingProtocolInterface (
749 if (EFI_ERROR (Status
)) {
751 // One or more drivers refused to release, so return the error
757 // Remove the protocol interface from the protocol
759 Status
= EFI_NOT_FOUND
;
760 Handle
= (IHANDLE
*)UserHandle
;
761 Prot
= CoreRemoveInterfaceFromProtocol (Handle
, Protocol
, Interface
);
765 // Update the Key to show that the handle has been created/modified
767 gHandleDatabaseKey
++;
768 Handle
->Key
= gHandleDatabaseKey
;
771 // Remove the protocol interface from the handle
773 RemoveEntryList (&Prot
->Link
);
780 Status
= EFI_SUCCESS
;
784 // If there are no more handlers for the handle, free the handle
786 if (IsListEmpty (&Handle
->Protocols
)) {
787 Handle
->Signature
= 0;
788 RemoveEntryList (&Handle
->AllHandles
);
789 CoreFreePool (Handle
);
794 // Done, unlock the database and return
796 CoreReleaseProtocolLock ();
804 Uninstalls a list of protocol interface in the boot services environment.
805 This function calls UnisatllProtocolInterface() in a loop. This is
806 basically a lib function to save space.
808 @param Handle The handle to uninstall the protocol
809 @param ... EFI_GUID followed by protocol instance. A NULL
810 terminates the list. The pairs are the
811 arguments to UninstallProtocolInterface(). All
812 the protocols are added to Handle.
819 CoreUninstallMultipleProtocolInterfaces (
820 IN EFI_HANDLE Handle
,
830 VA_START (Args
, Handle
);
831 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
833 // If protocol is NULL, then it's the end of the list
835 Protocol
= VA_ARG (Args
, EFI_GUID
*);
836 if (Protocol
== NULL
) {
840 Interface
= VA_ARG (Args
, VOID
*);
845 Status
= CoreUninstallProtocolInterface (Handle
, Protocol
, Interface
);
849 // If there was an error, add all the interfaces that were
850 // uninstalled without any errors
852 if (EFI_ERROR (Status
)) {
854 // Reset the va_arg back to the first argument.
856 VA_START (Args
, Handle
);
857 for (; Index
> 1; Index
--) {
858 Protocol
= VA_ARG(Args
, EFI_GUID
*);
859 Interface
= VA_ARG(Args
, VOID
*);
860 CoreInstallProtocolInterface (&Handle
, Protocol
, EFI_NATIVE_INTERFACE
, Interface
);
869 Locate a certain GUID protocol interface in a Handle's protocols.
871 @param UserHandle The handle to obtain the protocol interface on
872 @param Protocol The GUID of the protocol
874 @return The requested protocol interface for the handle
878 CoreGetProtocolInterface (
879 IN EFI_HANDLE UserHandle
,
880 IN EFI_GUID
*Protocol
884 PROTOCOL_ENTRY
*ProtEntry
;
885 PROTOCOL_INTERFACE
*Prot
;
889 Status
= CoreValidateHandle (UserHandle
);
890 if (EFI_ERROR (Status
)) {
894 Handle
= (IHANDLE
*)UserHandle
;
897 // Look at each protocol interface for a match
899 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
900 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
901 ProtEntry
= Prot
->Protocol
;
902 if (CompareGuid (&ProtEntry
->ProtocolID
, Protocol
)) {
912 Queries a handle to determine if it supports a specified protocol.
914 @param UserHandle The handle being queried.
915 @param Protocol The published unique identifier of the protocol.
916 @param Interface Supplies the address where a pointer to the
917 corresponding Protocol Interface is returned.
919 @retval EFI_SUCCESS The interface information for the specified protocol was returned.
920 @retval EFI_UNSUPPORTED The device does not support the specified protocol.
921 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE..
922 @retval EFI_INVALID_PARAMETER Protocol is NULL.
923 @retval EFI_INVALID_PARAMETER Interface is NULL.
929 IN EFI_HANDLE UserHandle
,
930 IN EFI_GUID
*Protocol
,
934 return CoreOpenProtocol (
940 EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
947 Locates the installed protocol handler for the handle, and
948 invokes it to obtain the protocol interface. Usage information
949 is registered in the protocol data base.
951 @param UserHandle The handle to obtain the protocol interface on
952 @param Protocol The ID of the protocol
953 @param Interface The location to return the protocol interface
954 @param ImageHandle The handle of the Image that is opening the
955 protocol interface specified by Protocol and
957 @param ControllerHandle The controller handle that is requiring this
959 @param Attributes The open mode of the protocol interface
960 specified by Handle and Protocol.
962 @retval EFI_INVALID_PARAMETER Protocol is NULL.
963 @retval EFI_SUCCESS Get the protocol interface.
969 IN EFI_HANDLE UserHandle
,
970 IN EFI_GUID
*Protocol
,
971 OUT VOID
**Interface OPTIONAL
,
972 IN EFI_HANDLE ImageHandle
,
973 IN EFI_HANDLE ControllerHandle
,
978 PROTOCOL_INTERFACE
*Prot
;
980 OPEN_PROTOCOL_DATA
*OpenData
;
987 // Check for invalid Protocol
989 if (Protocol
== NULL
) {
990 return EFI_INVALID_PARAMETER
;
994 // Check for invalid Interface
996 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
997 if (Interface
== NULL
) {
998 return EFI_INVALID_PARAMETER
;
1005 // Check for invalid UserHandle
1007 Status
= CoreValidateHandle (UserHandle
);
1008 if (EFI_ERROR (Status
)) {
1013 // Check for invalid Attributes
1015 switch (Attributes
) {
1016 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1017 Status
= CoreValidateHandle (ImageHandle
);
1018 if (EFI_ERROR (Status
)) {
1021 Status
= CoreValidateHandle (ControllerHandle
);
1022 if (EFI_ERROR (Status
)) {
1025 if (UserHandle
== ControllerHandle
) {
1026 return EFI_INVALID_PARAMETER
;
1029 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1030 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1031 Status
= CoreValidateHandle (ImageHandle
);
1032 if (EFI_ERROR (Status
)) {
1035 Status
= CoreValidateHandle (ControllerHandle
);
1036 if (EFI_ERROR (Status
)) {
1040 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1041 Status
= CoreValidateHandle (ImageHandle
);
1042 if (EFI_ERROR (Status
)) {
1046 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1047 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1048 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1051 return EFI_INVALID_PARAMETER
;
1055 // Lock the protocol database
1057 CoreAcquireProtocolLock ();
1060 // Look at each protocol interface for a match
1062 Prot
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1064 Status
= EFI_UNSUPPORTED
;
1069 // This is the protocol interface entry for this protocol
1071 if (Attributes
!= EFI_OPEN_PROTOCOL_TEST_PROTOCOL
) {
1072 *Interface
= Prot
->Interface
;
1074 Status
= EFI_SUCCESS
;
1078 for ( Link
= Prot
->OpenList
.ForwardLink
; Link
!= &Prot
->OpenList
; Link
= Link
->ForwardLink
) {
1079 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1080 ExactMatch
= (BOOLEAN
)((OpenData
->AgentHandle
== ImageHandle
) &&
1081 (OpenData
->Attributes
== Attributes
) &&
1082 (OpenData
->ControllerHandle
== ControllerHandle
));
1083 if (OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) {
1086 Status
= EFI_ALREADY_STARTED
;
1090 if (OpenData
->Attributes
& EFI_OPEN_PROTOCOL_EXCLUSIVE
) {
1092 } else if (ExactMatch
) {
1093 OpenData
->OpenCount
++;
1094 Status
= EFI_SUCCESS
;
1100 // ByDriver TRUE -> A driver is managing (UserHandle, Protocol)
1101 // ByDriver FALSE -> There are no drivers managing (UserHandle, Protocol)
1102 // Exclusive TRUE -> Something has exclusive access to (UserHandle, Protocol)
1103 // Exclusive FALSE -> Nothing has exclusive access to (UserHandle, Protocol)
1106 switch (Attributes
) {
1107 case EFI_OPEN_PROTOCOL_BY_DRIVER
:
1108 if (Exclusive
|| ByDriver
) {
1109 Status
= EFI_ACCESS_DENIED
;
1113 case EFI_OPEN_PROTOCOL_BY_DRIVER
| EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1114 case EFI_OPEN_PROTOCOL_EXCLUSIVE
:
1116 Status
= EFI_ACCESS_DENIED
;
1122 for ( Link
= Prot
->OpenList
.ForwardLink
; (Link
!= &Prot
->OpenList
) && (!Disconnect
); Link
= Link
->ForwardLink
) {
1123 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1124 if (OpenData
->Attributes
& EFI_OPEN_PROTOCOL_BY_DRIVER
) {
1126 CoreReleaseProtocolLock ();
1127 Status
= CoreDisconnectController (UserHandle
, OpenData
->AgentHandle
, NULL
);
1128 CoreAcquireProtocolLock ();
1129 if (EFI_ERROR (Status
)) {
1130 Status
= EFI_ACCESS_DENIED
;
1135 } while (Disconnect
);
1138 case EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
:
1139 case EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
:
1140 case EFI_OPEN_PROTOCOL_GET_PROTOCOL
:
1141 case EFI_OPEN_PROTOCOL_TEST_PROTOCOL
:
1145 if (ImageHandle
== NULL
) {
1146 Status
= EFI_SUCCESS
;
1152 OpenData
= AllocatePool (sizeof(OPEN_PROTOCOL_DATA
));
1153 if (OpenData
== NULL
) {
1154 Status
= EFI_OUT_OF_RESOURCES
;
1156 OpenData
->Signature
= OPEN_PROTOCOL_DATA_SIGNATURE
;
1157 OpenData
->AgentHandle
= ImageHandle
;
1158 OpenData
->ControllerHandle
= ControllerHandle
;
1159 OpenData
->Attributes
= Attributes
;
1160 OpenData
->OpenCount
= 1;
1161 InsertTailList (&Prot
->OpenList
, &OpenData
->Link
);
1162 Prot
->OpenListCount
++;
1163 Status
= EFI_SUCCESS
;
1168 // Done. Release the database lock are return
1170 CoreReleaseProtocolLock ();
1177 Closes a protocol on a handle that was opened using OpenProtocol().
1179 @param UserHandle The handle for the protocol interface that was
1180 previously opened with OpenProtocol(), and is
1182 @param Protocol The published unique identifier of the protocol.
1183 It is the caller's responsibility to pass in a
1185 @param AgentHandle The handle of the agent that is closing the
1187 @param ControllerHandle If the agent that opened a protocol is a driver
1188 that follows the EFI Driver Model, then this
1189 parameter is the controller handle that required
1190 the protocol interface. If the agent does not
1191 follow the EFI Driver Model, then this parameter
1192 is optional and may be NULL.
1194 @retval EFI_SUCCESS The protocol instance was closed.
1195 @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
1197 @retval EFI_NOT_FOUND Can not find the specified protocol or
1204 IN EFI_HANDLE UserHandle
,
1205 IN EFI_GUID
*Protocol
,
1206 IN EFI_HANDLE AgentHandle
,
1207 IN EFI_HANDLE ControllerHandle
1211 PROTOCOL_INTERFACE
*ProtocolInterface
;
1213 OPEN_PROTOCOL_DATA
*OpenData
;
1216 // Check for invalid parameters
1218 Status
= CoreValidateHandle (UserHandle
);
1219 if (EFI_ERROR (Status
)) {
1222 Status
= CoreValidateHandle (AgentHandle
);
1223 if (EFI_ERROR (Status
)) {
1226 if (ControllerHandle
!= NULL
) {
1227 Status
= CoreValidateHandle (ControllerHandle
);
1228 if (EFI_ERROR (Status
)) {
1232 if (Protocol
== NULL
) {
1233 return EFI_INVALID_PARAMETER
;
1237 // Lock the protocol database
1239 CoreAcquireProtocolLock ();
1242 // Look at each protocol interface for a match
1244 Status
= EFI_NOT_FOUND
;
1245 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1246 if (ProtocolInterface
== NULL
) {
1251 // Walk the Open data base looking for AgentHandle
1253 Link
= ProtocolInterface
->OpenList
.ForwardLink
;
1254 while (Link
!= &ProtocolInterface
->OpenList
) {
1255 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1256 Link
= Link
->ForwardLink
;
1257 if ((OpenData
->AgentHandle
== AgentHandle
) && (OpenData
->ControllerHandle
== ControllerHandle
)) {
1258 RemoveEntryList (&OpenData
->Link
);
1259 ProtocolInterface
->OpenListCount
--;
1260 CoreFreePool (OpenData
);
1261 Status
= EFI_SUCCESS
;
1267 // Done. Release the database lock and return.
1269 CoreReleaseProtocolLock ();
1277 Return information about Opened protocols in the system
1279 @param UserHandle The handle to close the protocol interface on
1280 @param Protocol The ID of the protocol
1281 @param EntryBuffer A pointer to a buffer of open protocol information in the
1282 form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
1283 @param EntryCount Number of EntryBuffer entries
1285 @retval EFI_SUCCESS The open protocol information was returned in EntryBuffer,
1286 and the number of entries was returned EntryCount.
1287 @retval EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
1288 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.
1293 CoreOpenProtocolInformation (
1294 IN EFI_HANDLE UserHandle
,
1295 IN EFI_GUID
*Protocol
,
1296 OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
**EntryBuffer
,
1297 OUT UINTN
*EntryCount
1301 PROTOCOL_INTERFACE
*ProtocolInterface
;
1303 OPEN_PROTOCOL_DATA
*OpenData
;
1304 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*Buffer
;
1308 *EntryBuffer
= NULL
;
1312 // Lock the protocol database
1314 CoreAcquireProtocolLock ();
1317 // Look at each protocol interface for a match
1319 Status
= EFI_NOT_FOUND
;
1320 ProtocolInterface
= CoreGetProtocolInterface (UserHandle
, Protocol
);
1321 if (ProtocolInterface
== NULL
) {
1326 // Count the number of Open Entries
1328 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1329 (Link
!= &ProtocolInterface
->OpenList
) ;
1330 Link
= Link
->ForwardLink
) {
1334 ASSERT (Count
== ProtocolInterface
->OpenListCount
);
1337 Size
= sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1339 Size
= Count
* sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
);
1342 Buffer
= AllocatePool (Size
);
1343 if (Buffer
== NULL
) {
1344 Status
= EFI_OUT_OF_RESOURCES
;
1348 Status
= EFI_SUCCESS
;
1349 for ( Link
= ProtocolInterface
->OpenList
.ForwardLink
, Count
= 0;
1350 (Link
!= &ProtocolInterface
->OpenList
);
1351 Link
= Link
->ForwardLink
, Count
++ ) {
1352 OpenData
= CR (Link
, OPEN_PROTOCOL_DATA
, Link
, OPEN_PROTOCOL_DATA_SIGNATURE
);
1354 Buffer
[Count
].AgentHandle
= OpenData
->AgentHandle
;
1355 Buffer
[Count
].ControllerHandle
= OpenData
->ControllerHandle
;
1356 Buffer
[Count
].Attributes
= OpenData
->Attributes
;
1357 Buffer
[Count
].OpenCount
= OpenData
->OpenCount
;
1360 *EntryBuffer
= Buffer
;
1361 *EntryCount
= Count
;
1365 // Done. Release the database lock.
1367 CoreReleaseProtocolLock ();
1375 Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
1378 @param UserHandle The handle from which to retrieve the list of
1379 protocol interface GUIDs.
1380 @param ProtocolBuffer A pointer to the list of protocol interface GUID
1381 pointers that are installed on Handle.
1382 @param ProtocolBufferCount A pointer to the number of GUID pointers present
1385 @retval EFI_SUCCESS The list of protocol interface GUIDs installed
1386 on Handle was returned in ProtocolBuffer. The
1387 number of protocol interface GUIDs was returned
1388 in ProtocolBufferCount.
1389 @retval EFI_INVALID_PARAMETER Handle is NULL.
1390 @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
1391 @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
1392 @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
1393 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
1399 CoreProtocolsPerHandle (
1400 IN EFI_HANDLE UserHandle
,
1401 OUT EFI_GUID
***ProtocolBuffer
,
1402 OUT UINTN
*ProtocolBufferCount
1407 PROTOCOL_INTERFACE
*Prot
;
1409 UINTN ProtocolCount
;
1412 Status
= CoreValidateHandle (UserHandle
);
1413 if (EFI_ERROR (Status
)) {
1417 Handle
= (IHANDLE
*)UserHandle
;
1419 if (ProtocolBuffer
== NULL
) {
1420 return EFI_INVALID_PARAMETER
;
1423 if (ProtocolBufferCount
== NULL
) {
1424 return EFI_INVALID_PARAMETER
;
1427 *ProtocolBufferCount
= 0;
1431 CoreAcquireProtocolLock ();
1433 for (Link
= Handle
->Protocols
.ForwardLink
; Link
!= &Handle
->Protocols
; Link
= Link
->ForwardLink
) {
1438 // If there are no protocol interfaces installed on Handle, then Handle is not a valid EFI_HANDLE
1440 if (ProtocolCount
== 0) {
1441 Status
= EFI_INVALID_PARAMETER
;
1445 Buffer
= AllocatePool (sizeof (EFI_GUID
*) * ProtocolCount
);
1446 if (Buffer
== NULL
) {
1447 Status
= EFI_OUT_OF_RESOURCES
;
1451 *ProtocolBuffer
= Buffer
;
1452 *ProtocolBufferCount
= ProtocolCount
;
1454 for ( Link
= Handle
->Protocols
.ForwardLink
, ProtocolCount
= 0;
1455 Link
!= &Handle
->Protocols
;
1456 Link
= Link
->ForwardLink
, ProtocolCount
++) {
1457 Prot
= CR(Link
, PROTOCOL_INTERFACE
, Link
, PROTOCOL_INTERFACE_SIGNATURE
);
1458 Buffer
[ProtocolCount
] = &(Prot
->Protocol
->ProtocolID
);
1460 Status
= EFI_SUCCESS
;
1463 CoreReleaseProtocolLock ();
1470 return handle database key.
1473 @return Handle database key.
1477 CoreGetHandleDatabaseKey (
1481 return gHandleDatabaseKey
;
1487 Go connect any handles that were created or modified while a image executed.
1489 @param Key The Key to show that the handle has been
1494 CoreConnectHandlesByKey (
1500 EFI_HANDLE
*HandleBuffer
;
1505 // Lock the protocol database
1507 CoreAcquireProtocolLock ();
1509 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1510 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1511 if (Handle
->Key
> Key
) {
1516 HandleBuffer
= AllocatePool (Count
* sizeof (EFI_HANDLE
));
1517 if (HandleBuffer
== NULL
) {
1518 CoreReleaseProtocolLock ();
1522 for (Link
= gHandleList
.ForwardLink
, Count
= 0; Link
!= &gHandleList
; Link
= Link
->ForwardLink
) {
1523 Handle
= CR (Link
, IHANDLE
, AllHandles
, EFI_HANDLE_SIGNATURE
);
1524 if (Handle
->Key
> Key
) {
1525 HandleBuffer
[Count
++] = Handle
;
1530 // Unlock the protocol database
1532 CoreReleaseProtocolLock ();
1535 // Connect all handles whose Key value is greater than Key
1537 for (Index
= 0; Index
< Count
; Index
++) {
1538 CoreConnectController (HandleBuffer
[Index
], NULL
, NULL
, TRUE
);
1541 CoreFreePool(HandleBuffer
);