Add comments and DoxyGen format for these files.

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / hand.h

/** @file \r
\r
  Support functions for managing protocol.\r
\r
Copyright (c) 2006 - 2008, Intel Corporation                                                         \r
All rights reserved. This program and the accompanying materials                          \r
are licensed and made available under the terms and conditions of the BSD License         \r
which accompanies this distribution.  The full text of the license may be found at        \r
http://opensource.org/licenses/bsd-license.php                                            \r
                                                                                          \r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
**/\r
\r
#ifndef  _HAND_H_\r
#define  _HAND_H_\r
\r
\r
//\r
// IHANDLE - contains a list of protocol handles\r
//\r
\r
#define EFI_HANDLE_SIGNATURE            EFI_SIGNATURE_32('h','n','d','l')\r
typedef struct {\r
  UINTN               Signature;\r
  LIST_ENTRY          AllHandles;     // All handles list of IHANDLE\r
  LIST_ENTRY          Protocols;      // List of PROTOCOL_INTERFACE's for this handle\r
  UINTN               LocateRequest;  // \r
  UINT64              Key;            // The Handle Database Key value when this handle was last created or modified\r
} IHANDLE;\r
\r
#define ASSERT_IS_HANDLE(a)  ASSERT((a)->Signature == EFI_HANDLE_SIGNATURE)\r
\r
\r
//\r
// PROTOCOL_ENTRY - each different protocol has 1 entry in the protocol \r
// database.  Each handler that supports this protocol is listed, along\r
// with a list of registered notifies.\r
//\r
\r
#define PROTOCOL_ENTRY_SIGNATURE        EFI_SIGNATURE_32('p','r','t','e')\r
typedef struct {\r
  UINTN               Signature;\r
  LIST_ENTRY          AllEntries;             // All entries\r
  EFI_GUID            ProtocolID;             // ID of the protocol\r
  LIST_ENTRY          Protocols;              // All protocol interfaces\r
  LIST_ENTRY          Notify;                 // Registerd notification handlers\r
} PROTOCOL_ENTRY;\r
\r
//\r
// PROTOCOL_INTERFACE - each protocol installed on a handle is tracked\r
// with a protocol interface structure\r
//\r
\r
#define PROTOCOL_INTERFACE_SIGNATURE  EFI_SIGNATURE_32('p','i','f','c')\r
typedef struct {\r
  UINTN                       Signature;\r
  EFI_HANDLE                  Handle;     // Back pointer\r
  LIST_ENTRY                  Link;       // Link on IHANDLE.Protocols\r
  LIST_ENTRY                  ByProtocol; // Link on PROTOCOL_ENTRY.Protocols\r
  PROTOCOL_ENTRY              *Protocol;  // The protocol ID\r
  VOID                        *Interface; // The interface value\r
                                          \r
  LIST_ENTRY                  OpenList;       // OPEN_PROTOCOL_DATA list.\r
  UINTN                       OpenListCount;  \r
  \r
  EFI_HANDLE                  ControllerHandle;\r
\r
} PROTOCOL_INTERFACE;\r
\r
#define OPEN_PROTOCOL_DATA_SIGNATURE  EFI_SIGNATURE_32('p','o','d','l')\r
\r
typedef struct {\r
  UINTN                       Signature;\r
  LIST_ENTRY                  Link;\r
\r
  EFI_HANDLE                  AgentHandle;\r
  EFI_HANDLE                  ControllerHandle;\r
  UINT32                      Attributes;\r
  UINT32                      OpenCount;\r
} OPEN_PROTOCOL_DATA;\r
\r
\r
//\r
// PROTOCOL_NOTIFY - used for each register notification for a protocol\r
//\r
\r
#define PROTOCOL_NOTIFY_SIGNATURE       EFI_SIGNATURE_32('p','r','t','n')\r
typedef struct {\r
  UINTN               Signature;\r
  PROTOCOL_ENTRY      *Protocol;\r
  LIST_ENTRY          Link;                   // All notifications for this protocol\r
  EFI_EVENT           Event;                  // Event to notify\r
  LIST_ENTRY          *Position;              // Last position notified\r
} PROTOCOL_NOTIFY;\r
\r
//\r
// Internal prototypes\r
//\r
\r
\r
PROTOCOL_ENTRY  *\r
CoreFindProtocolEntry (\r
  IN EFI_GUID     *Protocol,\r
  IN BOOLEAN      Create\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Finds the protocol entry for the requested protocol.\r
  \r
  The gProtocolDatabaseLock must be owned\r
\r
Arguments:\r
  \r
  Protocol  - The ID of the protocol \r
\r
  Create    - Create a new entry if not found\r
\r
Returns:\r
\r
  Protocol entry\r
\r
--*/\r
;\r
\r
VOID\r
CoreNotifyProtocolEntry (\r
  IN PROTOCOL_ENTRY       *ProtEntry\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Signal event for every protocol in protocol entry.\r
\r
Arguments:\r
\r
  ProtEntry     - Protocol entry\r
\r
Returns:\r
\r
--*/\r
;\r
\r
PROTOCOL_INTERFACE *\r
CoreFindProtocolInterface (\r
  IN IHANDLE              *Handle,\r
  IN EFI_GUID             *Protocol,\r
  IN VOID                 *Interface\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Finds the protocol instance for the requested handle and protocol.\r
  \r
  Note: This function doesn't do parameters checking, it's caller's responsibility \r
        to pass in valid parameters.\r
  \r
Arguments:\r
  \r
  Handle    - The handle to search the protocol on\r
  \r
  Protocol  - GUID of the protocol\r
\r
  Interface - The interface for the protocol being searched\r
\r
Returns:\r
\r
  Protocol instance (NULL: Not found)\r
\r
--*/\r
;\r
\r
PROTOCOL_INTERFACE *\r
CoreRemoveInterfaceFromProtocol (\r
  IN IHANDLE              *Handle,\r
  IN EFI_GUID             *Protocol,\r
  IN VOID                 *Interface\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Removes Protocol from the protocol list (but not the handle list).\r
\r
Arguments:\r
\r
  Handle -  The handle to remove protocol on.\r
\r
  Protocol  -  GUID of the protocol to be moved\r
\r
  Interface - The interface of the protocol\r
\r
Returns:\r
\r
  Protocol Entry\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
CoreUnregisterProtocolNotify (\r
  IN EFI_EVENT            Event\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Removes all the events in the protocol database that match Event.\r
\r
Arguments:\r
  \r
  Event   - The event to search for in the protocol database.\r
\r
Returns:\r
\r
  EFI_SUCCESS when done searching the entire database.\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
CoreDisconnectControllersUsingProtocolInterface (\r
  IN EFI_HANDLE           UserHandle,\r
  IN PROTOCOL_INTERFACE   *Prot\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Attempts to disconnect all drivers that are using the protocol interface being queried.\r
  If failed, reconnect all drivers disconnected.\r
  \r
  Note: This function doesn't do parameters checking, it's caller's responsibility \r
        to pass in valid parameters.\r
\r
Arguments:\r
\r
  UserHandle  - The handle on which the protocol is installed \r
  Prot        - The protocol to disconnect drivers from\r
\r
Returns:\r
\r
  EFI_SUCCESS       - Drivers using the protocol interface are all disconnected\r
  EFI_ACCESS_DENIED - Failed to disconnect one or all of the drivers\r
\r
--*/\r
;\r
\r
VOID\r
CoreAcquireProtocolLock (\r
  VOID\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Acquire lock on gProtocolDatabaseLock.\r
  \r
Arguments:\r
\r
  None\r
  \r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
VOID\r
CoreReleaseProtocolLock (\r
  VOID\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Release lock on gProtocolDatabaseLock.\r
  \r
Arguments:\r
\r
  None\r
  \r
Returns:\r
\r
  None\r
\r
--*/\r
;\r
\r
EFI_STATUS\r
CoreValidateHandle (\r
  IN  EFI_HANDLE                UserHandle\r
  )\r
/*++\r
\r
Routine Description:\r
\r
  Check whether a handle is a valid EFI_HANDLE\r
  \r
Arguments:\r
\r
  UserHandle		-	The handle to check\r
  \r
Returns:\r
\r
  EFI_INVALID_PARAMETER		-	The handle is NULL or not a valid EFI_HANDLE.\r
  \r
  EFI_SUCCESS							-	The handle is valid EFI_HANDLE.\r
\r
--*/\r
;\r
\r
//\r
// Externs\r
//\r
\r
extern EFI_LOCK         gProtocolDatabaseLock;\r
extern LIST_ENTRY       gHandleList;\r
extern UINT64           gHandleDatabaseKey;\r
\r
#endif\r