MdeModulePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Hand / Handle.h

/** @file\r
  Support functions for managing protocol.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef  _HAND_H_\r
#define  _HAND_H_\r
\r
\r
#define EFI_HANDLE_SIGNATURE            SIGNATURE_32('h','n','d','l')\r
\r
///\r
/// IHANDLE - contains a list of protocol handles\r
///\r
typedef struct {\r
  UINTN               Signature;\r
  /// All handles list of IHANDLE\r
  LIST_ENTRY          AllHandles;\r
  /// List of PROTOCOL_INTERFACE's for this handle\r
  LIST_ENTRY          Protocols;\r
  UINTN               LocateRequest;\r
  /// The Handle Database Key value when this handle was last created or modified\r
  UINT64              Key;\r
} IHANDLE;\r
\r
#define ASSERT_IS_HANDLE(a)  ASSERT((a)->Signature == EFI_HANDLE_SIGNATURE)\r
\r
#define PROTOCOL_ENTRY_SIGNATURE        SIGNATURE_32('p','r','t','e')\r
\r
///\r
/// PROTOCOL_ENTRY - each different protocol has 1 entry in the protocol\r
/// database.  Each handler that supports this protocol is listed, along\r
/// with a list of registered notifies.\r
///\r
typedef struct {\r
  UINTN               Signature;\r
  /// Link Entry inserted to mProtocolDatabase\r
  LIST_ENTRY          AllEntries;\r
  /// ID of the protocol\r
  EFI_GUID            ProtocolID;\r
  /// All protocol interfaces\r
  LIST_ENTRY          Protocols;\r
  /// Registerd notification handlers\r
  LIST_ENTRY          Notify;\r
} PROTOCOL_ENTRY;\r
\r
\r
#define PROTOCOL_INTERFACE_SIGNATURE  SIGNATURE_32('p','i','f','c')\r
\r
///\r
/// PROTOCOL_INTERFACE - each protocol installed on a handle is tracked\r
/// with a protocol interface structure\r
///\r
typedef struct {\r
  UINTN                       Signature;\r
  /// Link on IHANDLE.Protocols\r
  LIST_ENTRY                  Link;\r
  /// Back pointer\r
  IHANDLE                     *Handle;\r
  /// Link on PROTOCOL_ENTRY.Protocols\r
  LIST_ENTRY                  ByProtocol;\r
  /// The protocol ID\r
  PROTOCOL_ENTRY              *Protocol;\r
  /// The interface value\r
  VOID                        *Interface;\r
  /// OPEN_PROTOCOL_DATA list\r
  LIST_ENTRY                  OpenList;\r
  UINTN                       OpenListCount;\r
\r
} PROTOCOL_INTERFACE;\r
\r
#define OPEN_PROTOCOL_DATA_SIGNATURE  SIGNATURE_32('p','o','d','l')\r
\r
typedef struct {\r
  UINTN                       Signature;\r
  ///Link on PROTOCOL_INTERFACE.OpenList\r
  LIST_ENTRY                  Link;\r
\r
  EFI_HANDLE                  AgentHandle;\r
  EFI_HANDLE                  ControllerHandle;\r
  UINT32                      Attributes;\r
  UINT32                      OpenCount;\r
} OPEN_PROTOCOL_DATA;\r
\r
\r
#define PROTOCOL_NOTIFY_SIGNATURE       SIGNATURE_32('p','r','t','n')\r
\r
///\r
/// PROTOCOL_NOTIFY - used for each register notification for a protocol\r
///\r
typedef struct {\r
  UINTN               Signature;\r
  PROTOCOL_ENTRY      *Protocol;\r
  /// All notifications for this protocol\r
  LIST_ENTRY          Link;\r
  /// Event to notify\r
  EFI_EVENT           Event;\r
  /// Last position notified\r
  LIST_ENTRY          *Position;\r
} PROTOCOL_NOTIFY;\r
\r
\r
\r
/**\r
  Finds the protocol entry for the requested protocol.\r
  The gProtocolDatabaseLock must be owned\r
\r
  @param  Protocol               The ID of the protocol\r
  @param  Create                 Create a new entry if not found\r
\r
  @return Protocol entry\r
\r
**/\r
PROTOCOL_ENTRY  *\r
CoreFindProtocolEntry (\r
  IN EFI_GUID   *Protocol,\r
  IN BOOLEAN    Create\r
  );\r
\r
\r
/**\r
  Signal event for every protocol in protocol entry.\r
\r
  @param  ProtEntry              Protocol entry\r
\r
**/\r
VOID\r
CoreNotifyProtocolEntry (\r
  IN PROTOCOL_ENTRY   *ProtEntry\r
  );\r
\r
\r
/**\r
  Finds the protocol instance for the requested handle and protocol.\r
  Note: This function doesn't do parameters checking, it's caller's responsibility\r
  to pass in valid parameters.\r
\r
  @param  Handle                 The handle to search the protocol on\r
  @param  Protocol               GUID of the protocol\r
  @param  Interface              The interface for the protocol being searched\r
\r
  @return Protocol instance (NULL: Not found)\r
\r
**/\r
PROTOCOL_INTERFACE *\r
CoreFindProtocolInterface (\r
  IN IHANDLE        *Handle,\r
  IN EFI_GUID       *Protocol,\r
  IN VOID           *Interface\r
  );\r
\r
\r
/**\r
  Removes Protocol from the protocol list (but not the handle list).\r
\r
  @param  Handle                 The handle to remove protocol on.\r
  @param  Protocol               GUID of the protocol to be moved\r
  @param  Interface              The interface of the protocol\r
\r
  @return Protocol Entry\r
\r
**/\r
PROTOCOL_INTERFACE *\r
CoreRemoveInterfaceFromProtocol (\r
  IN IHANDLE        *Handle,\r
  IN EFI_GUID       *Protocol,\r
  IN VOID           *Interface\r
  );\r
\r
\r
/**\r
  Connects a controller to a driver.\r
\r
  @param  ControllerHandle                      Handle of the controller to be\r
                                                connected.\r
  @param  ContextDriverImageHandles             DriverImageHandle A pointer to an\r
                                                ordered list of driver image\r
                                                handles.\r
  @param  RemainingDevicePath                   RemainingDevicePath A pointer to\r
                                                the device path that specifies a\r
                                                child  of the controller\r
                                                specified by ControllerHandle.\r
\r
  @retval EFI_SUCCESS                           One or more drivers were\r
                                                connected to ControllerHandle.\r
  @retval EFI_OUT_OF_RESOURCES                  No enough system resources to\r
                                                complete the request.\r
  @retval EFI_NOT_FOUND                         No drivers were connected to\r
                                                ControllerHandle.\r
\r
**/\r
EFI_STATUS\r
CoreConnectSingleController (\r
  IN  EFI_HANDLE                ControllerHandle,\r
  IN  EFI_HANDLE                *ContextDriverImageHandles OPTIONAL,\r
  IN  EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath       OPTIONAL\r
  );\r
\r
/**\r
  Attempts to disconnect all drivers that are using the protocol interface being queried.\r
  If failed, reconnect all drivers disconnected.\r
  Note: This function doesn't do parameters checking, it's caller's responsibility\r
  to pass in valid parameters.\r
\r
  @param  UserHandle             The handle on which the protocol is installed\r
  @param  Prot                   The protocol to disconnect drivers from\r
\r
  @retval EFI_SUCCESS            Drivers using the protocol interface are all\r
                                 disconnected\r
  @retval EFI_ACCESS_DENIED      Failed to disconnect one or all of the drivers\r
\r
**/\r
EFI_STATUS\r
CoreDisconnectControllersUsingProtocolInterface (\r
  IN EFI_HANDLE           UserHandle,\r
  IN PROTOCOL_INTERFACE   *Prot\r
  );\r
\r
\r
/**\r
  Acquire lock on gProtocolDatabaseLock.\r
\r
**/\r
VOID\r
CoreAcquireProtocolLock (\r
  VOID\r
  );\r
\r
\r
/**\r
  Release lock on gProtocolDatabaseLock.\r
\r
**/\r
VOID\r
CoreReleaseProtocolLock (\r
  VOID\r
  );\r
\r
\r
/**\r
  Check whether a handle is a valid EFI_HANDLE\r
\r
  @param  UserHandle             The handle to check\r
\r
  @retval EFI_INVALID_PARAMETER  The handle is NULL or not a valid EFI_HANDLE.\r
  @retval EFI_SUCCESS            The handle is valid EFI_HANDLE.\r
\r
**/\r
EFI_STATUS\r
CoreValidateHandle (\r
  IN  EFI_HANDLE                UserHandle\r
  );\r
\r
//\r
// Externs\r
//\r
extern EFI_LOCK         gProtocolDatabaseLock;\r
extern LIST_ENTRY       gHandleList;\r
extern UINT64           gHandleDatabaseKey;\r
\r
#endif\r