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 PROTOCOL_ENTRY  *
 104 CoreFindProtocolEntry (
 105   IN EFI_GUID     *Protocol,
 106   IN BOOLEAN      Create
 107   )
 108 /*++
 109
 110 Routine Description:
 111
 112   Finds the protocol entry for the requested protocol.
 113
 114   The gProtocolDatabaseLock must be owned
 115
 116 Arguments:
 117
 118   Protocol  - The ID of the protocol
 119
 120   Create    - Create a new entry if not found
 121
 122 Returns:
 123
 124   Protocol entry
 125
 126 --*/
 127 ;
 128
 129 VOID
 130 CoreNotifyProtocolEntry (
 131   IN PROTOCOL_ENTRY       *ProtEntry
 132   )
 133 /*++
 134
 135 Routine Description:
 136
 137   Signal event for every protocol in protocol entry.
 138
 139 Arguments:
 140
 141   ProtEntry     - Protocol entry
 142
 143 Returns:
 144
 145 --*/
 146 ;
 147
 148 PROTOCOL_INTERFACE *
 149 CoreFindProtocolInterface (
 150   IN IHANDLE              *Handle,
 151   IN EFI_GUID             *Protocol,
 152   IN VOID                 *Interface
 153   )
 154 /*++
 155
 156 Routine Description:
 157
 158   Finds the protocol instance for the requested handle and protocol.
 159
 160   Note: This function doesn't do parameters checking, it's caller's responsibility
 161         to pass in valid parameters.
 162
 163 Arguments:
 164
 165   Handle    - The handle to search the protocol on
 166
 167   Protocol  - GUID of the protocol
 168
 169   Interface - The interface for the protocol being searched
 170
 171 Returns:
 172
 173   Protocol instance (NULL: Not found)
 174
 175 --*/
 176 ;
 177
 178 PROTOCOL_INTERFACE *
 179 CoreRemoveInterfaceFromProtocol (
 180   IN IHANDLE              *Handle,
 181   IN EFI_GUID             *Protocol,
 182   IN VOID                 *Interface
 183   )
 184 /*++
 185
 186 Routine Description:
 187
 188   Removes Protocol from the protocol list (but not the handle list).
 189
 190 Arguments:
 191
 192   Handle -  The handle to remove protocol on.
 193
 194   Protocol  -  GUID of the protocol to be moved
 195
 196   Interface - The interface of the protocol
 197
 198 Returns:
 199
 200   Protocol Entry
 201
 202 --*/
 203 ;
 204
 205 EFI_STATUS
 206 CoreUnregisterProtocolNotify (
 207   IN EFI_EVENT            Event
 208   )
 209 /*++
 210
 211 Routine Description:
 212
 213   Removes all the events in the protocol database that match Event.
 214
 215 Arguments:
 216
 217   Event   - The event to search for in the protocol database.
 218
 219 Returns:
 220
 221   EFI_SUCCESS when done searching the entire database.
 222
 223 --*/
 224 ;
 225
 226 EFI_STATUS
 227 CoreDisconnectControllersUsingProtocolInterface (
 228   IN EFI_HANDLE           UserHandle,
 229   IN PROTOCOL_INTERFACE   *Prot
 230   )
 231 /*++
 232
 233 Routine Description:
 234
 235   Attempts to disconnect all drivers that are using the protocol interface being queried.
 236   If failed, reconnect all drivers disconnected.
 237
 238   Note: This function doesn't do parameters checking, it's caller's responsibility
 239         to pass in valid parameters.
 240
 241 Arguments:
 242
 243   UserHandle  - The handle on which the protocol is installed
 244   Prot        - The protocol to disconnect drivers from
 245
 246 Returns:
 247
 248   EFI_SUCCESS       - Drivers using the protocol interface are all disconnected
 249   EFI_ACCESS_DENIED - Failed to disconnect one or all of the drivers
 250
 251 --*/
 252 ;
 253
 254 VOID
 255 CoreAcquireProtocolLock (
 256   VOID
 257   )
 258 /*++
 259
 260 Routine Description:
 261
 262   Acquire lock on gProtocolDatabaseLock.
 263
 264 Arguments:
 265
 266   None
 267
 268 Returns:
 269
 270   None
 271
 272 --*/
 273 ;
 274
 275 VOID
 276 CoreReleaseProtocolLock (
 277   VOID
 278   )
 279 /*++
 280
 281 Routine Description:
 282
 283   Release lock on gProtocolDatabaseLock.
 284
 285 Arguments:
 286
 287   None
 288
 289 Returns:
 290
 291   None
 292
 293 --*/
 294 ;
 295
 296 EFI_STATUS
 297 CoreValidateHandle (
 298   IN  EFI_HANDLE                UserHandle
 299   )
 300 /*++
 301
 302 Routine Description:
 303
 304   Check whether a handle is a valid EFI_HANDLE
 305
 306 Arguments:
 307
 308   UserHandle            -       The handle to check
 309
 310 Returns:
 311
 312   EFI_INVALID_PARAMETER         -       The handle is NULL or not a valid EFI_HANDLE.
 313
 314   EFI_SUCCESS                                                   -       The handle is valid EFI_HANDLE.
 315
 316 --*/
 317 ;
 318
 319 //
 320 // Externs
 321 //
 322
 323 extern EFI_LOCK         gProtocolDatabaseLock;
 324 extern LIST_ENTRY       gHandleList;
 325 extern UINT64           gHandleDatabaseKey;
 326
 327 #endif