MdeModulePkg/Core/Dxe/hand.h

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