Handle.c revision 4fd606d1f5abe38e1f42c38de1d2e895166bd0f4
/** @file
UEFI handle & protocol handling.
Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#include "DxeMain.h"
#include "Handle.h"
//
// mProtocolDatabase - A list of all protocols in the system. (simple list for now)
// gHandleList - A list of all the handles in the system
// gProtocolDatabaseLock - Lock to protect the mProtocolDatabase
//
UINT64 gHandleDatabaseKey = 0;
/**
Acquire lock on gProtocolDatabaseLock.
**/
)
{
}
/**
Release lock on gProtocolDatabaseLock.
**/
)
{
}
/**
Check whether a handle is a valid EFI_HANDLE
@param UserHandle The handle to check
@retval EFI_INVALID_PARAMETER The handle is NULL or not a valid EFI_HANDLE.
@retval EFI_SUCCESS The handle is valid EFI_HANDLE.
**/
)
{
return EFI_INVALID_PARAMETER;
}
return EFI_INVALID_PARAMETER;
}
return EFI_SUCCESS;
}
/**
Finds the protocol entry for the requested protocol.
The gProtocolDatabaseLock must be owned
@param Protocol The ID of the protocol
@param Create Create a new entry if not found
@return Protocol entry
**/
)
{
//
// Search the database for the matching GUID
//
Link != &mProtocolDatabase;
//
// This is the protocol entry
//
break;
}
}
//
// If the protocol entry was not found and Create is TRUE, then
// allocate a new entry
//
//
// Initialize new protocol entry structure
//
//
// Add it to protocol database
//
}
}
return ProtEntry;
}
/**
Finds the protocol instance for the requested handle and protocol.
Note: This function doesn't do parameters checking, it's caller's responsibility
to pass in valid parameters.
@param Handle The handle to search the protocol on
@param Protocol GUID of the protocol
@param Interface The interface for the protocol being searched
@return Protocol instance (NULL: Not found)
**/
)
{
//
// Lookup the protocol entry for this protocol ID
//
//
// Look at each protocol interface for any matches
//
//
// If this protocol interface matches, remove it
//
break;
}
}
}
return Prot;
}
/**
Removes an event from a register protocol notify list on a protocol.
@param Event The event to search for in the protocol
database.
@return EFI_SUCCESS if the event was found and removed.
@return EFI_NOT_FOUND if the event was not found in the protocl database.
**/
)
{
Link != &mProtocolDatabase;
return EFI_SUCCESS;
}
}
}
return EFI_NOT_FOUND;
}
/**
Removes all the events in the protocol database that match Event.
@param Event The event to search for in the protocol
database.
@return EFI_SUCCESS when done searching the entire database.
**/
)
{
do {
return EFI_SUCCESS;
}
/**
Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
Calls the private one which contains a BOOLEAN parameter for notifications
@param UserHandle The handle to install the protocol handler on,
or NULL if a new handle is to be allocated
@param Protocol The protocol to add to the handle
@param InterfaceType Indicates whether Interface is supplied in
native form.
@param Interface The interface for the protocol being added
@return Status code
**/
)
{
return CoreInstallProtocolInterfaceNotify (
);
}
/**
Installs a protocol interface into the boot services environment.
@param UserHandle The handle to install the protocol handler on,
or NULL if a new handle is to be allocated
@param Protocol The protocol to add to the handle
@param InterfaceType Indicates whether Interface is supplied in
native form.
@param Interface The interface for the protocol being added
@param Notify indicates whether notify the notification list
for this protocol
@retval EFI_INVALID_PARAMETER Invalid parameter
@retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
@retval EFI_SUCCESS Protocol interface successfully installed
**/
)
{
//
// returns EFI_INVALID_PARAMETER if InterfaceType is invalid.
// Also added check for invalid UserHandle and Protocol pointers.
//
return EFI_INVALID_PARAMETER;
}
if (InterfaceType != EFI_NATIVE_INTERFACE) {
return EFI_INVALID_PARAMETER;
}
//
// Print debug message
//
if (*UserHandle != NULL) {
return EFI_INVALID_PARAMETER;
}
}
//
// Lock the protocol database
//
//
// Lookup the Protocol Entry for the requested protocol
//
goto Done;
}
//
// Allocate a new protocol interface structure
//
goto Done;
}
//
// If caller didn't supply a handle, allocate a new one
//
goto Done;
}
//
// Initialize new handler structure
//
//
//
//
// Add this handle to the list global list of all handles
// in the system
//
}
goto Done;
}
//
// Each interface that is added must be unique
//
//
// Initialize the protocol interface structure
//
//
// Initalize OpenProtocol Data base
//
Prot->OpenListCount = 0;
//
// Add this protocol interface to the head of the supported
// protocol list for this handle
//
//
// Add this protocol interface to the tail of the
// protocol entry
//
//
// Notify the notification list for this protocol
//
if (Notify) {
}
Done:
//
// Done, unlock the database and return
//
//
// Return the new handle back to the caller
//
*UserHandle = Handle;
} else {
//
// There was an error, clean up
//
CoreFreePool (Prot);
}
}
return Status;
}
/**
Installs a list of protocol interface into the boot services environment.
This function calls InstallProtocolInterface() in a loop. If any error
occures all the protocols added by this function are removed. This is
basically a lib function to save space.
@param Handle The handle to install the protocol handlers on,
or NULL if a new handle is to be allocated
@param ... EFI_GUID followed by protocol instance. A NULL
terminates the list. The pairs are the
arguments to InstallProtocolInterface(). All the
protocols are added to Handle.
@retval EFI_INVALID_PARAMETER Handle is NULL.
@retval EFI_SUCCESS Protocol interfaces successfully installed.
**/
...
)
{
return EFI_INVALID_PARAMETER;
}
//
// Syncronize with notifcations.
//
//
// Check for duplicate device path and install the protocol interfaces
//
//
// If protocol is NULL, then it's the end of the list
//
break;
}
//
// Make sure you are installing on top a device path that has already been added.
//
DeviceHandle = NULL;
continue;
}
}
//
// Install it
//
}
//
// If there was an error, remove all the interfaces that were installed without any errors
//
//
// Reset the va_arg back to the first argument.
//
}
}
//
// Done
//
return Status;
}
/**
Attempts to disconnect all drivers that are using the protocol interface being queried.
If failed, reconnect all drivers disconnected.
Note: This function doesn't do parameters checking, it's caller's responsibility
to pass in valid parameters.
@param UserHandle The handle on which the protocol is installed
@param Prot The protocol to disconnect drivers from
@retval EFI_SUCCESS Drivers using the protocol interface are all
disconnected
@retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
**/
)
{
//
// Attempt to disconnect all drivers from this protocol interface
//
do {
break;
}
}
}
} while (ItemFound);
//
// Attempt to remove BY_HANDLE_PROTOOCL and GET_PROTOCOL and TEST_PROTOCOL Open List items
//
do {
if ((OpenData->Attributes &
(EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL | EFI_OPEN_PROTOCOL_GET_PROTOCOL | EFI_OPEN_PROTOCOL_TEST_PROTOCOL)) != 0) {
Prot->OpenListCount--;
}
}
} while (ItemFound);
}
//
// If there are errors or still has open items in the list, then reconnect all the drivers and return an error
//
}
return Status;
}
/**
Uninstalls all instances of a protocol:interfacer from a handle.
If the last protocol interface is remove from the handle, the
handle is freed.
@param UserHandle The handle to remove the protocol handler from
@param Protocol The protocol, of protocol:interface, to remove
@param Interface The interface, of protocol:interface, to remove
@retval EFI_INVALID_PARAMETER Protocol is NULL.
@retval EFI_SUCCESS Protocol interface successfully uninstalled.
**/
)
{
//
// Check that Protocol is valid
//
return EFI_INVALID_PARAMETER;
}
//
// Check that UserHandle is a valid handle
//
return Status;
}
//
// Lock the protocol database
//
//
// Check that Protocol exists on UserHandle, and Interface matches the interface in the database
//
goto Done;
}
//
// Attempt to disconnect all drivers that are using the protocol interface that is about to be removed
//
);
//
// One or more drivers refused to release, so return the error
//
goto Done;
}
//
// Remove the protocol interface from the protocol
//
//
//
//
// Remove the protocol interface from the handle
//
//
// Free the memory
//
CoreFreePool (Prot);
}
//
// If there are no more handlers for the handle, free the handle
//
}
Done:
//
// Done, unlock the database and return
//
return Status;
}
/**
Uninstalls a list of protocol interface in the boot services environment.
This function calls UnisatllProtocolInterface() in a loop. This is
basically a lib function to save space.
@param Handle The handle to uninstall the protocol
@param ... EFI_GUID followed by protocol instance. A NULL
terminates the list. The pairs are the
arguments to UninstallProtocolInterface(). All
the protocols are added to Handle.
@return Status code
**/
...
)
{
//
// If protocol is NULL, then it's the end of the list
//
break;
}
//
// Uninstall it
//
}
//
// If there was an error, add all the interfaces that were
// uninstalled without any errors
//
//
// Reset the va_arg back to the first argument.
//
}
}
return Status;
}
/**
Locate a certain GUID protocol interface in a Handle's protocols.
@param UserHandle The handle to obtain the protocol interface on
@param Protocol The GUID of the protocol
@return The requested protocol interface for the handle
**/
)
{
return NULL;
}
//
// Look at each protocol interface for a match
//
return Prot;
}
}
return NULL;
}
/**
Queries a handle to determine if it supports a specified protocol.
@param UserHandle The handle being queried.
@param Protocol The published unique identifier of the protocol.
@param Interface Supplies the address where a pointer to the
corresponding Protocol Interface is returned.
@retval EFI_SUCCESS The interface information for the specified protocol was returned.
@retval EFI_UNSUPPORTED The device does not support the specified protocol.
@retval EFI_INVALID_PARAMETER Handle is NULL..
@retval EFI_INVALID_PARAMETER Protocol is NULL.
@retval EFI_INVALID_PARAMETER Interface is NULL.
**/
)
{
return CoreOpenProtocol (
NULL,
);
}
/**
Locates the installed protocol handler for the handle, and
invokes it to obtain the protocol interface. Usage information
is registered in the protocol data base.
@param UserHandle The handle to obtain the protocol interface on
@param Protocol The ID of the protocol
@param Interface The location to return the protocol interface
@param ImageHandle The handle of the Image that is opening the
protocol interface specified by Protocol and
Interface.
@param ControllerHandle The controller handle that is requiring this
interface.
@param Attributes The open mode of the protocol interface
specified by Handle and Protocol.
@retval EFI_INVALID_PARAMETER Protocol is NULL.
@retval EFI_SUCCESS Get the protocol interface.
**/
)
{
//
// Check for invalid Protocol
//
return EFI_INVALID_PARAMETER;
}
//
// Check for invalid Interface
//
if (Attributes != EFI_OPEN_PROTOCOL_TEST_PROTOCOL) {
return EFI_INVALID_PARAMETER;
} else {
}
}
//
// Check for invalid UserHandle
//
return Status;
}
//
// Check for invalid Attributes
//
switch (Attributes) {
return Status;
}
return Status;
}
if (UserHandle == ControllerHandle) {
return EFI_INVALID_PARAMETER;
}
break;
case EFI_OPEN_PROTOCOL_BY_DRIVER :
return Status;
}
return Status;
}
break;
case EFI_OPEN_PROTOCOL_EXCLUSIVE :
return Status;
}
break;
break;
default:
return EFI_INVALID_PARAMETER;
}
//
// Lock the protocol database
//
//
// Look at each protocol interface for a match
//
goto Done;
}
//
// This is the protocol interface entry for this protocol
//
if (Attributes != EFI_OPEN_PROTOCOL_TEST_PROTOCOL) {
}
if (ExactMatch) {
goto Done;
}
}
} else if (ExactMatch) {
goto Done;
}
}
//
// ByDriver TRUE -> A driver is managing (UserHandle, Protocol)
// ByDriver FALSE -> There are no drivers managing (UserHandle, Protocol)
// Exclusive TRUE -> Something has exclusive access to (UserHandle, Protocol)
// Exclusive FALSE -> Nothing has exclusive access to (UserHandle, Protocol)
//
switch (Attributes) {
case EFI_OPEN_PROTOCOL_BY_DRIVER :
goto Done;
}
break;
case EFI_OPEN_PROTOCOL_EXCLUSIVE :
if (Exclusive) {
goto Done;
}
if (ByDriver) {
do {
Disconnect = FALSE;
for ( Link = Prot->OpenList.ForwardLink; (Link != &Prot->OpenList) && (!Disconnect); Link = Link->ForwardLink) {
Disconnect = TRUE;
goto Done;
}
}
}
} while (Disconnect);
}
break;
break;
}
if (ImageHandle == NULL) {
goto Done;
}
//
// Create new entry
//
} else {
Prot->OpenListCount++;
}
Done:
//
// Done. Release the database lock are return
//
return Status;
}
/**
Closes a protocol on a handle that was opened using OpenProtocol().
@param UserHandle The handle for the protocol interface that was
previously opened with OpenProtocol(), and is
now being closed.
@param Protocol The published unique identifier of the protocol.
It is the caller's responsibility to pass in a
valid GUID.
@param AgentHandle The handle of the agent that is closing the
protocol interface.
@param ControllerHandle If the agent that opened a protocol is a driver
that follows the EFI Driver Model, then this
parameter is the controller handle that required
the protocol interface. If the agent does not
follow the EFI Driver Model, then this parameter
is optional and may be NULL.
@retval EFI_SUCCESS The protocol instance was closed.
@retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
valid EFI_HANDLE.
@retval EFI_NOT_FOUND Can not find the specified protocol or
AgentHandle.
**/
)
{
//
// Check for invalid parameters
//
return Status;
}
return Status;
}
if (ControllerHandle != NULL) {
return Status;
}
}
return EFI_INVALID_PARAMETER;
}
//
// Lock the protocol database
//
//
// Look at each protocol interface for a match
//
if (ProtocolInterface == NULL) {
goto Done;
}
//
// Walk the Open data base looking for AgentHandle
//
}
}
Done:
//
// Done. Release the database lock and return.
//
return Status;
}
/**
Return information about Opened protocols in the system
@param UserHandle The handle to close the protocol interface on
@param Protocol The ID of the protocol
@param EntryBuffer A pointer to a buffer of open protocol information in the
form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
@param EntryCount Number of EntryBuffer entries
@retval EFI_SUCCESS The open protocol information was returned in EntryBuffer,
and the number of entries was returned EntryCount.
@retval EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
@retval EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.
**/
)
{
*EntryBuffer = NULL;
*EntryCount = 0;
//
// Lock the protocol database
//
//
// Look at each protocol interface for a match
//
if (ProtocolInterface == NULL) {
goto Done;
}
//
// Count the number of Open Entries
//
Count++;
}
if (Count == 0) {
Size = sizeof(EFI_OPEN_PROTOCOL_INFORMATION_ENTRY);
} else {
}
goto Done;
}
}
*EntryBuffer = Buffer;
*EntryCount = Count;
Done:
//
// Done. Release the database lock.
//
return Status;
}
/**
Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
from pool.
@param UserHandle The handle from which to retrieve the list of
protocol interface GUIDs.
@param ProtocolBuffer A pointer to the list of protocol interface GUID
pointers that are installed on Handle.
@param ProtocolBufferCount A pointer to the number of GUID pointers present
in ProtocolBuffer.
@retval EFI_SUCCESS The list of protocol interface GUIDs installed
on Handle was returned in ProtocolBuffer. The
number of protocol interface GUIDs was returned
in ProtocolBufferCount.
@retval EFI_INVALID_PARAMETER Handle is NULL.
@retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
@retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
@retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
@retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
results.
**/
)
{
return Status;
}
if (ProtocolBuffer == NULL) {
return EFI_INVALID_PARAMETER;
}
if (ProtocolBufferCount == NULL) {
return EFI_INVALID_PARAMETER;
}
*ProtocolBufferCount = 0;
ProtocolCount = 0;
}
//
// If there are no protocol interfaces installed on Handle, then Handle is not a valid EFI_HANDLE
//
if (ProtocolCount == 0) {
goto Done;
}
goto Done;
}
*ProtocolBuffer = Buffer;
}
Done:
return Status;
}
/**
return handle database key.
@return Handle database key.
**/
)
{
return gHandleDatabaseKey;
}
/**
Go connect any handles that were created or modified while a image executed.
@param Key The Key to show that the handle has been
**/
)
{
//
// Lock the protocol database
//
Count++;
}
}
if (HandleBuffer == NULL) {
return;
}
}
}
//
// Unlock the protocol database
//
//
// Connect all handles whose Key value is greater than Key
//
}
}