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   Connects a controller to a driver.
 186
 187   @param  ControllerHandle                      Handle of the controller to be
 188                                                 connected.
 189   @param  ContextDriverImageHandles             DriverImageHandle A pointer to an
 190                                                 ordered list of driver image
 191                                                 handles.
 192   @param  RemainingDevicePath                   RemainingDevicePath A pointer to
 193                                                 the device path that specifies a
 194                                                 child  of the controller
 195                                                 specified by ControllerHandle.
 196
 197   @retval EFI_SUCCESS                           One or more drivers were
 198                                                 connected to ControllerHandle.
 199   @retval EFI_OUT_OF_RESOURCES                  No enough system resources to
 200                                                 complete the request.
 201   @retval EFI_NOT_FOUND                         No drivers were connected to
 202                                                 ControllerHandle.
 203
 204 **/
 205 EFI_STATUS
 206 CoreConnectSingleController (
 207   IN  EFI_HANDLE                ControllerHandle,
 208   IN  EFI_HANDLE                *ContextDriverImageHandles OPTIONAL,
 209   IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath       OPTIONAL
 210   );
 211
 212 /**
 213   Attempts to disconnect all drivers that are using the protocol interface being queried.
 214   If failed, reconnect all drivers disconnected.
 215   Note: This function doesn't do parameters checking, it's caller's responsibility
 216   to pass in valid parameters.
 217
 218   @param  UserHandle             The handle on which the protocol is installed
 219   @param  Prot                   The protocol to disconnect drivers from
 220
 221   @retval EFI_SUCCESS            Drivers using the protocol interface are all
 222                                  disconnected
 223   @retval EFI_ACCESS_DENIED      Failed to disconnect one or all of the drivers
 224
 225 **/
 226 EFI_STATUS
 227 CoreDisconnectControllersUsingProtocolInterface (
 228   IN EFI_HANDLE           UserHandle,
 229   IN PROTOCOL_INTERFACE   *Prot
 230   );
 231
 232
 233 /**
 234   Acquire lock on gProtocolDatabaseLock.
 235
 236 **/
 237 VOID
 238 CoreAcquireProtocolLock (
 239   VOID
 240   );
 241
 242
 243 /**
 244   Release lock on gProtocolDatabaseLock.
 245
 246 **/
 247 VOID
 248 CoreReleaseProtocolLock (
 249   VOID
 250   );
 251
 252
 253 /**
 254   Check whether a handle is a valid EFI_HANDLE
 255
 256   @param  UserHandle             The handle to check
 257
 258   @retval EFI_INVALID_PARAMETER  The handle is NULL or not a valid EFI_HANDLE.
 259   @retval EFI_SUCCESS            The handle is valid EFI_HANDLE.
 260
 261 **/
 262 EFI_STATUS
 263 CoreValidateHandle (
 264   IN  EFI_HANDLE                UserHandle
 265   );
 266
 267 //
 268 // Externs
 269 //
 270
 271 extern EFI_LOCK         gProtocolDatabaseLock;
 272 extern LIST_ENTRY       gHandleList;
 273 extern UINT64           gHandleDatabaseKey;
 274
 275 #endif