MdeModulePkg/Core/Dxe/Hand.h

   1 /** @file
   2   Support functions for managing protocol.
   3
   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
   9
  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.
  12
  13 **/
  14
  15 #ifndef  _HAND_H_
  16 #define  _HAND_H_
  17
  18
  19 //
  20 // IHANDLE - contains a list of protocol handles
  21 //
  22
  23 #define EFI_HANDLE_SIGNATURE            EFI_SIGNATURE_32('h','n','d','l')
  24 typedef struct {
  25   UINTN               Signature;
  26   LIST_ENTRY          AllHandles;     // All handles list of IHANDLE
  27   LIST_ENTRY          Protocols;      // List of PROTOCOL_INTERFACE's for this handle
  28   UINTN               LocateRequest;  //
  29   UINT64              Key;            // The Handle Database Key value when this handle was last created or modified
  30 } IHANDLE;
  31
  32 #define ASSERT_IS_HANDLE(a)  ASSERT((a)->Signature == EFI_HANDLE_SIGNATURE)
  33
  34
  35 //
  36 // PROTOCOL_ENTRY - each different protocol has 1 entry in the protocol
  37 // database.  Each handler that supports this protocol is listed, along
  38 // with a list of registered notifies.
  39 //
  40
  41 #define PROTOCOL_ENTRY_SIGNATURE        EFI_SIGNATURE_32('p','r','t','e')
  42 typedef struct {
  43   UINTN               Signature;
  44   LIST_ENTRY          AllEntries;             // All entries
  45   EFI_GUID            ProtocolID;             // ID of the protocol
  46   LIST_ENTRY          Protocols;              // All protocol interfaces
  47   LIST_ENTRY          Notify;                 // Registerd notification handlers
  48 } PROTOCOL_ENTRY;
  49
  50 //
  51 // PROTOCOL_INTERFACE - each protocol installed on a handle is tracked
  52 // with a protocol interface structure
  53 //
  54
  55 #define PROTOCOL_INTERFACE_SIGNATURE  EFI_SIGNATURE_32('p','i','f','c')
  56 typedef struct {
  57   UINTN                       Signature;
  58   EFI_HANDLE                  Handle;     // Back pointer
  59   LIST_ENTRY                  Link;       // Link on IHANDLE.Protocols
  60   LIST_ENTRY                  ByProtocol; // Link on PROTOCOL_ENTRY.Protocols
  61   PROTOCOL_ENTRY              *Protocol;  // The protocol ID
  62   VOID                        *Interface; // The interface value
  63
  64   LIST_ENTRY                  OpenList;       // OPEN_PROTOCOL_DATA list.
  65   UINTN                       OpenListCount;
  66
  67   EFI_HANDLE                  ControllerHandle;
  68
  69 } PROTOCOL_INTERFACE;
  70
  71 #define OPEN_PROTOCOL_DATA_SIGNATURE  EFI_SIGNATURE_32('p','o','d','l')
  72
  73 typedef struct {
  74   UINTN                       Signature;
  75   LIST_ENTRY                  Link;
  76
  77   EFI_HANDLE                  AgentHandle;
  78   EFI_HANDLE                  ControllerHandle;
  79   UINT32                      Attributes;
  80   UINT32                      OpenCount;
  81 } OPEN_PROTOCOL_DATA;
  82
  83
  84 //
  85 // PROTOCOL_NOTIFY - used for each register notification for a protocol
  86 //
  87
  88 #define PROTOCOL_NOTIFY_SIGNATURE       EFI_SIGNATURE_32('p','r','t','n')
  89 typedef struct {
  90   UINTN               Signature;
  91   PROTOCOL_ENTRY      *Protocol;
  92   LIST_ENTRY          Link;                   // All notifications for this protocol
  93   EFI_EVENT           Event;                  // Event to notify
  94   LIST_ENTRY          *Position;              // Last position notified
  95 } PROTOCOL_NOTIFY;
  96
  97 //
  98 // Internal prototypes
  99 //
 100
 101
 102
 103 /**
 104   Finds the protocol entry for the requested protocol.
 105   The gProtocolDatabaseLock must be owned
 106
 107   @param  Protocol               The ID of the protocol
 108   @param  Create                 Create a new entry if not found
 109
 110   @return Protocol entry
 111
 112 **/
 113 PROTOCOL_ENTRY  *
 114 CoreFindProtocolEntry (
 115   IN EFI_GUID   *Protocol,
 116   IN BOOLEAN    Create
 117   );
 118
 119
 120 /**
 121   Signal event for every protocol in protocol entry.
 122
 123   @param  ProtEntry              Protocol entry
 124
 125 **/
 126 VOID
 127 CoreNotifyProtocolEntry (
 128   IN PROTOCOL_ENTRY   *ProtEntry
 129   );
 130
 131
 132 /**
 133   Finds the protocol instance for the requested handle and protocol.
 134   Note: This function doesn't do parameters checking, it's caller's responsibility
 135   to pass in valid parameters.
 136
 137   @param  Handle                 The handle to search the protocol on
 138   @param  Protocol               GUID of the protocol
 139   @param  Interface              The interface for the protocol being searched
 140
 141   @return Protocol instance (NULL: Not found)
 142
 143 **/
 144 PROTOCOL_INTERFACE *
 145 CoreFindProtocolInterface (
 146   IN IHANDLE        *Handle,
 147   IN EFI_GUID       *Protocol,
 148   IN VOID           *Interface
 149   );
 150
 151
 152 /**
 153   Removes Protocol from the protocol list (but not the handle list).
 154
 155   @param  Handle                 The handle to remove protocol on.
 156   @param  Protocol               GUID of the protocol to be moved
 157   @param  Interface              The interface of the protocol
 158
 159   @return Protocol Entry
 160
 161 **/
 162 PROTOCOL_INTERFACE *
 163 CoreRemoveInterfaceFromProtocol (
 164   IN IHANDLE        *Handle,
 165   IN EFI_GUID       *Protocol,
 166   IN VOID           *Interface
 167   );
 168
 169
 170 /**
 171   Removes all the events in the protocol database that match Event.
 172
 173   @param  Event                  The event to search for in the protocol
 174                                  database.
 175
 176   @return EFI_SUCCESS when done searching the entire database.
 177
 178 **/
 179 EFI_STATUS
 180 CoreUnregisterProtocolNotify (
 181   IN EFI_EVENT      Event
 182   );
 183
 184
 185 /**
 186   Attempts to disconnect all drivers that are using the protocol interface being queried.
 187   If failed, reconnect all drivers disconnected.
 188   Note: This function doesn't do parameters checking, it's caller's responsibility
 189   to pass in valid parameters.
 190
 191   @param  UserHandle             The handle on which the protocol is installed
 192   @param  Prot                   The protocol to disconnect drivers from
 193
 194   @retval EFI_SUCCESS            Drivers using the protocol interface are all
 195                                  disconnected
 196   @retval EFI_ACCESS_DENIED      Failed to disconnect one or all of the drivers
 197
 198 **/
 199 EFI_STATUS
 200 CoreDisconnectControllersUsingProtocolInterface (
 201   IN EFI_HANDLE           UserHandle,
 202   IN PROTOCOL_INTERFACE   *Prot
 203   );
 204
 205
 206 /**
 207   Acquire lock on gProtocolDatabaseLock.
 208
 209 **/
 210 VOID
 211 CoreAcquireProtocolLock (
 212   VOID
 213   );
 214
 215
 216 /**
 217   Release lock on gProtocolDatabaseLock.
 218
 219 **/
 220 VOID
 221 CoreReleaseProtocolLock (
 222   VOID
 223   );
 224
 225
 226 /**
 227   Check whether a handle is a valid EFI_HANDLE
 228
 229   @param  UserHandle             The handle to check
 230
 231   @retval EFI_INVALID_PARAMETER  The handle is NULL or not a valid EFI_HANDLE.
 232   @retval EFI_SUCCESS            The handle is valid EFI_HANDLE.
 233
 234 **/
 235 EFI_STATUS
 236 CoreValidateHandle (
 237   IN  EFI_HANDLE                UserHandle
 238   );
 239
 240 //
 241 // Externs
 242 //
 243
 244 extern EFI_LOCK         gProtocolDatabaseLock;
 245 extern LIST_ENTRY       gHandleList;
 246 extern UINT64           gHandleDatabaseKey;
 247
 248 #endif