ShellPkg/Include/Library/HandleParsingLib.h

   1 /** @file
   2   Provides interface to advanced shell functionality for parsing both handle and protocol database.
   3
   4   Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
   5   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 __HANDLE_PARSING_LIB__
  16 #define __HANDLE_PARSING_LIB__
  17
  18 #include <Uefi.h>
  19
  20 /**
  21   Function to get the name of a protocol or struct from it's GUID.
  22
  23   If Guid is NULL, then ASSERT.
  24
  25   @param[in] Guid               The GUID to look for the name of.
  26   @param[in] Lang               The language to use.
  27
  28   @return                       The pointer to a string of the name.  The caller
  29                                 is responsible to free this memory.
  30 **/
  31 CHAR16*
  32 EFIAPI
  33 GetStringNameFromGuid(
  34   IN CONST EFI_GUID *Guid,
  35   IN CONST CHAR8    *Lang OPTIONAL
  36   );
  37
  38 /**
  39   Function to get the Guid for a protocol or struct based on it's string name.
  40
  41   @param[in] Name           The pointer to the string name.
  42   @param[in] Lang           The pointer to the language code (string).
  43   @param[in] Guid           The pointer to the pointer to the Guid.
  44
  45   @retval EFI_SUCCESS       The operation was successful.
  46 **/
  47 EFI_STATUS
  48 EFIAPI
  49 GetGuidFromStringName(
  50   IN CONST CHAR16 *Name,
  51   IN CONST CHAR8  *Lang OPTIONAL,
  52   IN EFI_GUID     **Guid
  53   );
  54
  55 /**
  56   Function to dump protocol information from a handle.
  57
  58   This function will return a allocated string buffer containing the
  59   information.  The caller is responsible for freeing the memory.
  60
  61   If Guid is NULL, ASSERT().
  62   If TheHandle is NULL, ASSERT().
  63
  64   @param[in] TheHandle      The handle to dump information from.
  65   @param[in] Guid           The GUID of the protocol to dump.
  66   @param[in] Verbose        TRUE for extra info.  FALSE otherwise.
  67
  68   @return                   The pointer to string.
  69   @retval NULL              An error was encountered.
  70 **/
  71 CHAR16*
  72 EFIAPI
  73 GetProtocolInformationDump(
  74   IN CONST EFI_HANDLE TheHandle,
  75   IN CONST EFI_GUID   *Guid,
  76   IN CONST BOOLEAN    Verbose
  77   );
  78
  79 /**
  80   Function to retrieve the driver name (if possible) from the ComponentName or
  81   ComponentName2 protocol.
  82
  83   The string returned must be callee freed.
  84
  85   @param[in] TheHandle      The driver handle to get the name of.
  86   @param[in] Language       The language to use.
  87
  88   @retval NULL              The name could not be found.
  89   @return                   A pointer to the string name.  Do not de-allocate the memory.
  90 **/
  91 CONST CHAR16*
  92 EFIAPI
  93 GetStringNameFromHandle(
  94   IN CONST EFI_HANDLE TheHandle,
  95   IN CONST CHAR8      *Language
  96   );
  97
  98 #define HR_UNKNOWN                     0
  99 #define HR_IMAGE_HANDLE                BIT1
 100 #define HR_DRIVER_BINDING_HANDLE       BIT2 // has driver binding
 101 #define HR_DEVICE_DRIVER               BIT3 // device driver (hybrid?)
 102 #define HR_BUS_DRIVER                  BIT4 // a bus driver  (hybrid?)
 103 #define HR_DRIVER_CONFIGURATION_HANDLE BIT5
 104 #define HR_DRIVER_DIAGNOSTICS_HANDLE   BIT6
 105 #define HR_COMPONENT_NAME_HANDLE       BIT7
 106 #define HR_DEVICE_HANDLE               BIT8
 107 #define HR_PARENT_HANDLE               BIT9
 108 #define HR_CONTROLLER_HANDLE           BIT10
 109 #define HR_CHILD_HANDLE                BIT11
 110 #define HR_VALID_MASK                  (BIT1|BIT2|BIT3|BIT4|BIT5|BIT6|BIT7|BIT8|BIT9|BIT10|BIT11)
 111
 112 /**
 113   Gets all the related EFI_HANDLEs based on the mask supplied.
 114
 115   This function will scan all EFI_HANDLES in the UEFI environment's handle database
 116   and return all the ones with the specified relationship (Mask) to the specified
 117   controller handle.
 118
 119   If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
 120   If MatchingHandleCount is NULL, then ASSERT.
 121
 122   If MatchingHandleBuffer is not NULL upon a successful return, the memory must be
 123   caller freed.
 124
 125   @param[in] DriverBindingHandle    The handle with Driver Binding protocol on it.
 126   @param[in] ControllerHandle       The handle with Device Path protocol on it.
 127   @param[in] Mask                   The mask of what relationship(s) is desired.
 128   @param[in] MatchingHandleCount    The pointer to UINTN specifying number of HANDLES in
 129                                     MatchingHandleBuffer.
 130   @param[out] MatchingHandleBuffer  On a successful return, a buffer of MatchingHandleCount
 131                                     EFI_HANDLEs with a terminating NULL EFI_HANDLE.
 132
 133   @retval EFI_SUCCESS               The operation was successful, and any related handles
 134                                     are in MatchingHandleBuffer.
 135   @retval EFI_NOT_FOUND             No matching handles were found.
 136   @retval EFI_INVALID_PARAMETER     A parameter was invalid or out of range.
 137   @sa ParseHandleDatabaseByRelationshipWithType
 138 **/
 139 EFI_STATUS
 140 EFIAPI
 141 ParseHandleDatabaseByRelationship (
 142   IN CONST EFI_HANDLE       DriverBindingHandle OPTIONAL,
 143   IN CONST EFI_HANDLE       ControllerHandle OPTIONAL,
 144   IN CONST UINTN            Mask,
 145   IN UINTN                  *MatchingHandleCount,
 146   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 147   );
 148
 149 /**
 150   Gets all the related EFI_HANDLEs based on the mask supplied.
 151
 152   This function scans all EFI_HANDLES in the UEFI environment's handle database
 153   and returns the ones with the specified relationship (Mask) to the specified
 154   controller handle.
 155
 156   If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
 157   If MatchingHandleCount is NULL, then ASSERT.
 158
 159   If MatchingHandleBuffer is not NULL upon a successful return the memory must be
 160   caller freed.
 161
 162   @param[in] DriverBindingHandle    The handle with Driver Binding protocol on it.
 163   @param[in] ControllerHandle       The handle with Device Path protocol on it.
 164   @param[in] MatchingHandleCount    The pointer to UINTN that specifies the number of HANDLES in
 165                                     MatchingHandleBuffer.
 166   @param[out] MatchingHandleBuffer  On a successful return, a buffer of MatchingHandleCount
 167                                     EFI_HANDLEs with a terminating NULL EFI_HANDLE.
 168   @param[out] HandleType            An array of type information.
 169
 170   @retval EFI_SUCCESS               The operation was successful, and any related handles
 171                                     are in MatchingHandleBuffer.
 172   @retval EFI_NOT_FOUND             No matching handles were found.
 173   @retval EFI_INVALID_PARAMETER     A parameter was invalid or out of range.
 174 **/
 175 EFI_STATUS
 176 EFIAPI
 177 ParseHandleDatabaseByRelationshipWithType (
 178   IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL,
 179   IN CONST EFI_HANDLE ControllerHandle OPTIONAL,
 180   IN UINTN            *HandleCount,
 181   OUT EFI_HANDLE      **HandleBuffer,
 182   OUT UINTN           **HandleType
 183   );
 184
 185 /**
 186   Gets handles for any parents of the passed in controller.
 187
 188   @param[in] ControllerHandle       The handle of the controller.
 189   @param[in] Count                  The pointer to the number of handles in
 190                                     MatchingHandleBuffer on return.
 191   @param[out] Buffer                The buffer containing handles on a successful
 192                                     return.
 193   @retval EFI_SUCCESS               The operation was successful.
 194   @sa ParseHandleDatabaseByRelationship
 195 **/
 196 #define PARSE_HANDLE_DATABASE_PARENTS(ControllerHandle, Count, Buffer) \
 197   ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_PARENT_HANDLE, Count, Buffer)
 198
 199 /**
 200   Gets handles for any UEFI drivers of the passed in controller.
 201
 202   @param[in] ControllerHandle       The handle of the controller.
 203   @param[in] Count                  The pointer to the number of handles in
 204                                     MatchingHandleBuffer on return.
 205   @param[out] Buffer                The buffer containing handles on a successful
 206                                     return.
 207   @retval EFI_SUCCESS               The operation was successful.
 208   @sa ParseHandleDatabaseByRelationship
 209 **/
 210 #define PARSE_HANDLE_DATABASE_UEFI_DRIVERS(ControllerHandle, Count, Buffer) \
 211   ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_DRIVER_BINDING_HANDLE|HR_DEVICE_DRIVER, Count, Buffer)
 212
 213 /**
 214   Gets handles for any children of the passed in controller by the passed in driver handle.
 215
 216   @param[in] DriverHandle           The handle of the driver.
 217   @param[in] ControllerHandle       The handle of the controller.
 218   @param[in] Count                  The pointer to the number of handles in
 219                                     MatchingHandleBuffer on return.
 220   @param[out] Buffer                The buffer containing handles on a successful
 221                                     return.
 222   @retval EFI_SUCCESS               The operation was successful.
 223   @sa ParseHandleDatabaseByRelationship
 224 **/
 225 #define PARSE_HANDLE_DATABASE_MANAGED_CHILDREN(DriverHandle, ControllerHandle, Count, Buffer) \
 226   ParseHandleDatabaseByRelationship(DriverHandle, ControllerHandle, HR_CHILD_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
 227
 228 /**
 229   Gets handles for any devices managed by the passed in driver.
 230
 231   @param[in] DriverHandle           The handle of the driver.
 232   @param[in] Count                  The pointer to the number of handles in
 233                                     MatchingHandleBuffer on return.
 234   @param[out] Buffer                The buffer containing handles on a successful
 235                                     return.
 236   @retval EFI_SUCCESS               The operation was successful.
 237   @sa ParseHandleDatabaseByRelationship
 238 **/
 239 #define PARSE_HANDLE_DATABASE_DEVICES(DriverHandle, Count, Buffer) \
 240   ParseHandleDatabaseByRelationship(DriverHandle, NULL, HR_CONTROLLER_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
 241
 242 /**
 243   Gets handles for any child devices produced by the passed in driver.
 244
 245   @param[in] DriverHandle           The handle of the driver.
 246   @param[in] MatchingHandleCount    The pointer to the number of handles in
 247                                     MatchingHandleBuffer on return.
 248   @param[out] MatchingHandleBuffer  The buffer containing handles on a successful
 249                                     return.
 250   @retval EFI_SUCCESS               The operation was successful.
 251   @sa ParseHandleDatabaseByRelationship
 252 **/
 253 EFI_STATUS
 254 EFIAPI
 255 ParseHandleDatabaseForChildDevices(
 256   IN CONST EFI_HANDLE       DriverHandle,
 257   IN UINTN                  *MatchingHandleCount,
 258   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 259   );
 260
 261 /**
 262   Gets handles for any child controllers of the passed in controller.
 263
 264   @param[in] ControllerHandle       The handle of the "parent controller".
 265   @param[in] MatchingHandleCount    The pointer to the number of handles in
 266                                     MatchingHandleBuffer on return.
 267   @param[out] MatchingHandleBuffer  The buffer containing handles on a successful
 268                                     return.
 269   @retval EFI_SUCCESS               The operation was successful.
 270   @sa ParseHandleDatabaseByRelationship
 271 **/
 272 EFI_STATUS
 273 EFIAPI
 274 ParseHandleDatabaseForChildControllers(
 275   IN CONST EFI_HANDLE       ControllerHandle,
 276   IN UINTN                  *MatchingHandleCount,
 277   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 278   );
 279
 280
 281 /**
 282   Function to retrieve the human-friendly index of a given handle.  If the handle
 283   does not have a index one will be automatically assigned.  The index value is valid
 284   until the termination of the shell application.
 285
 286   @param[in] TheHandle    The handle to retrieve an index for.
 287
 288   @retval 0               A memory allocation failed.
 289   @return                 The index of the handle.
 290
 291 **/
 292 UINTN
 293 EFIAPI
 294 ConvertHandleToHandleIndex(
 295   IN CONST EFI_HANDLE TheHandle
 296   );
 297
 298 /**
 299   Function to retrieve the EFI_HANDLE from the human-friendly index.
 300
 301   @param[in] TheIndex     The index to retrieve the EFI_HANDLE for.
 302
 303   @retval NULL            The index was invalid.
 304   @return                 The EFI_HANDLE that index represents.
 305
 306 **/
 307 EFI_HANDLE
 308 EFIAPI
 309 ConvertHandleIndexToHandle(
 310   IN CONST UINTN TheIndex
 311   );
 312
 313 /**
 314   Function to get all handles that support a given protocol or all handles.
 315
 316   @param[in] ProtocolGuid The guid of the protocol to get handles for.  If NULL
 317                           then the function will return all handles.
 318
 319   @retval NULL            A memory allocation failed.
 320   @return                 A NULL terminated list of handles.
 321 **/
 322 EFI_HANDLE*
 323 EFIAPI
 324 GetHandleListByPotocol (
 325   IN CONST EFI_GUID *ProtocolGuid OPTIONAL
 326   );
 327
 328 /**
 329   Function to get all handles that support some protocols.
 330
 331   @param[in] ProtocolGuids  A NULL terminated list of protocol GUIDs.
 332
 333   @retval NULL              A memory allocation failed.
 334   @return                   A NULL terminated list of handles.
 335 **/
 336 EFI_HANDLE*
 337 EFIAPI
 338 GetHandleListByPotocolList (
 339   IN CONST EFI_GUID **ProtocolGuids
 340   );
 341
 342 #endif // __HANDLE_PARSING_LIB__