MdeModulePkg/Core/Dxe/Handle.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;             // Link Entry inserted to mProtocolDatabase
  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   LIST_ENTRY                  Link;       // Link on IHANDLE.Protocols
  59   IHANDLE                     *Handle;    // Back pointer
  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 } PROTOCOL_INTERFACE;
  68
  69 #define OPEN_PROTOCOL_DATA_SIGNATURE  EFI_SIGNATURE_32('p','o','d','l')
  70
  71 typedef struct {
  72   UINTN                       Signature;
  73   LIST_ENTRY                  Link;      //Link on PROTOCOL_INTERFACE.OpenList
  74
  75   EFI_HANDLE                  AgentHandle;
  76   EFI_HANDLE                  ControllerHandle;
  77   UINT32                      Attributes;
  78   UINT32                      OpenCount;
  79 } OPEN_PROTOCOL_DATA;
  80
  81
  82 //
  83 // PROTOCOL_NOTIFY - used for each register notification for a protocol
  84 //
  85
  86 #define PROTOCOL_NOTIFY_SIGNATURE       EFI_SIGNATURE_32('p','r','t','n')
  87 typedef struct {
  88   UINTN               Signature;
  89   PROTOCOL_ENTRY      *Protocol;
  90   LIST_ENTRY          Link;                   // All notifications for this protocol
  91   EFI_EVENT           Event;                  // Event to notify
  92   LIST_ENTRY          *Position;              // Last position notified
  93 } PROTOCOL_NOTIFY;
  94
  95 //
  96 // Internal prototypes
  97 //
  98
  99
 100
 101 /**
 102   Finds the protocol entry for the requested protocol.
 103   The gProtocolDatabaseLock must be owned
 104
 105   @param  Protocol               The ID of the protocol
 106   @param  Create                 Create a new entry if not found
 107
 108   @return Protocol entry
 109
 110 **/
 111 PROTOCOL_ENTRY  *
 112 CoreFindProtocolEntry (
 113   IN EFI_GUID   *Protocol,
 114   IN BOOLEAN    Create
 115   );
 116
 117
 118 /**
 119   Signal event for every protocol in protocol entry.
 120
 121   @param  ProtEntry              Protocol entry
 122
 123 **/
 124 VOID
 125 CoreNotifyProtocolEntry (
 126   IN PROTOCOL_ENTRY   *ProtEntry
 127   );
 128
 129
 130 /**
 131   Finds the protocol instance for the requested handle and protocol.
 132   Note: This function doesn't do parameters checking, it's caller's responsibility
 133   to pass in valid parameters.
 134
 135   @param  Handle                 The handle to search the protocol on
 136   @param  Protocol               GUID of the protocol
 137   @param  Interface              The interface for the protocol being searched
 138
 139   @return Protocol instance (NULL: Not found)
 140
 141 **/
 142 PROTOCOL_INTERFACE *
 143 CoreFindProtocolInterface (
 144   IN IHANDLE        *Handle,
 145   IN EFI_GUID       *Protocol,
 146   IN VOID           *Interface
 147   );
 148
 149
 150 /**
 151   Removes Protocol from the protocol list (but not the handle list).
 152
 153   @param  Handle                 The handle to remove protocol on.
 154   @param  Protocol               GUID of the protocol to be moved
 155   @param  Interface              The interface of the protocol
 156
 157   @return Protocol Entry
 158
 159 **/
 160 PROTOCOL_INTERFACE *
 161 CoreRemoveInterfaceFromProtocol (
 162   IN IHANDLE        *Handle,
 163   IN EFI_GUID       *Protocol,
 164   IN VOID           *Interface
 165   );
 166
 167
 168 /**
 169   Removes all the events in the protocol database that match Event.
 170
 171   @param  Event                  The event to search for in the protocol
 172                                  database.
 173
 174   @return EFI_SUCCESS when done searching the entire database.
 175
 176 **/
 177 EFI_STATUS
 178 CoreUnregisterProtocolNotify (
 179   IN EFI_EVENT      Event
 180   );
 181
 182 /**
 183   Connects a controller to a driver.
 184
 185   @param  ControllerHandle                      Handle of the controller to be
 186                                                 connected.
 187   @param  ContextDriverImageHandles             DriverImageHandle A pointer to an
 188                                                 ordered list of driver image
 189                                                 handles.
 190   @param  RemainingDevicePath                   RemainingDevicePath A pointer to
 191                                                 the device path that specifies a
 192                                                 child  of the controller
 193                                                 specified by ControllerHandle.
 194
 195   @retval EFI_SUCCESS                           One or more drivers were
 196                                                 connected to ControllerHandle.
 197   @retval EFI_OUT_OF_RESOURCES                  No enough system resources to
 198                                                 complete the request.
 199   @retval EFI_NOT_FOUND                         No drivers were connected to
 200                                                 ControllerHandle.
 201
 202 **/
 203 EFI_STATUS
 204 CoreConnectSingleController (
 205   IN  EFI_HANDLE                ControllerHandle,
 206   IN  EFI_HANDLE                *ContextDriverImageHandles OPTIONAL,
 207   IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath       OPTIONAL
 208   );
 209
 210 /**
 211   Attempts to disconnect all drivers that are using the protocol interface being queried.
 212   If failed, reconnect all drivers disconnected.
 213   Note: This function doesn't do parameters checking, it's caller's responsibility
 214   to pass in valid parameters.
 215
 216   @param  UserHandle             The handle on which the protocol is installed
 217   @param  Prot                   The protocol to disconnect drivers from
 218
 219   @retval EFI_SUCCESS            Drivers using the protocol interface are all
 220                                  disconnected
 221   @retval EFI_ACCESS_DENIED      Failed to disconnect one or all of the drivers
 222
 223 **/
 224 EFI_STATUS
 225 CoreDisconnectControllersUsingProtocolInterface (
 226   IN EFI_HANDLE           UserHandle,
 227   IN PROTOCOL_INTERFACE   *Prot
 228   );
 229
 230
 231 /**
 232   Acquire lock on gProtocolDatabaseLock.
 233
 234 **/
 235 VOID
 236 CoreAcquireProtocolLock (
 237   VOID
 238   );
 239
 240
 241 /**
 242   Release lock on gProtocolDatabaseLock.
 243
 244 **/
 245 VOID
 246 CoreReleaseProtocolLock (
 247   VOID
 248   );
 249
 250
 251 /**
 252   Check whether a handle is a valid EFI_HANDLE
 253
 254   @param  UserHandle             The handle to check
 255
 256   @retval EFI_INVALID_PARAMETER  The handle is NULL or not a valid EFI_HANDLE.
 257   @retval EFI_SUCCESS            The handle is valid EFI_HANDLE.
 258
 259 **/
 260 EFI_STATUS
 261 CoreValidateHandle (
 262   IN  EFI_HANDLE                UserHandle
 263   );
 264
 265 //
 266 // Externs
 267 //
 268
 269 extern EFI_LOCK         gProtocolDatabaseLock;
 270 extern LIST_ENTRY       gHandleList;
 271 extern UINT64           gHandleDatabaseKey;
 272
 273 #endif