MdeModulePkg/Core/Dxe/hand.h

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