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 - 2013, 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 /**
  99   Get best support language for this driver.
 100
 101   First base on the user input language  to search, second base on the current
 102   platform used language to search, third get the first language from the
 103   support language list. The caller need to free the buffer of the best language.
 104
 105   @param[in] SupportedLanguages      The support languages for this driver.
 106   @param[in] InputLanguage           The user input language.
 107   @param[in] Iso639Language          Whether get language for ISO639.
 108
 109   @return                            The best support language for this driver.
 110 **/
 111 CHAR8 *
 112 EFIAPI
 113 GetBestLanguageForDriver (
 114   IN CONST CHAR8  *SupportedLanguages,
 115   IN CONST CHAR8  *InputLanguage,
 116   IN BOOLEAN      Iso639Language
 117   );
 118
 119 #define HR_UNKNOWN                     0
 120 #define HR_IMAGE_HANDLE                BIT1
 121 #define HR_DRIVER_BINDING_HANDLE       BIT2 // has driver binding
 122 #define HR_DEVICE_DRIVER               BIT3 // device driver (hybrid?)
 123 #define HR_BUS_DRIVER                  BIT4 // a bus driver  (hybrid?)
 124 #define HR_DRIVER_CONFIGURATION_HANDLE BIT5
 125 #define HR_DRIVER_DIAGNOSTICS_HANDLE   BIT6
 126 #define HR_COMPONENT_NAME_HANDLE       BIT7
 127 #define HR_DEVICE_HANDLE               BIT8
 128 #define HR_PARENT_HANDLE               BIT9
 129 #define HR_CONTROLLER_HANDLE           BIT10
 130 #define HR_CHILD_HANDLE                BIT11
 131 #define HR_VALID_MASK                  (BIT1|BIT2|BIT3|BIT4|BIT5|BIT6|BIT7|BIT8|BIT9|BIT10|BIT11)
 132
 133 /**
 134   Gets all the related EFI_HANDLEs based on the mask supplied.
 135
 136   This function will scan all EFI_HANDLES in the UEFI environment's handle database
 137   and return all the ones with the specified relationship (Mask) to the specified
 138   controller handle.
 139
 140   If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
 141   If MatchingHandleCount is NULL, then ASSERT.
 142
 143   If MatchingHandleBuffer is not NULL upon a successful return, the memory must be
 144   caller freed.
 145
 146   @param[in] DriverBindingHandle    The handle with Driver Binding protocol on it.
 147   @param[in] ControllerHandle       The handle with Device Path protocol on it.
 148   @param[in] Mask                   The mask of what relationship(s) is desired.
 149   @param[in] MatchingHandleCount    The pointer to UINTN specifying number of HANDLES in
 150                                     MatchingHandleBuffer.
 151   @param[out] MatchingHandleBuffer  On a successful return, a buffer of MatchingHandleCount
 152                                     EFI_HANDLEs with a terminating NULL EFI_HANDLE.
 153
 154   @retval EFI_SUCCESS               The operation was successful, and any related handles
 155                                     are in MatchingHandleBuffer.
 156   @retval EFI_NOT_FOUND             No matching handles were found.
 157   @retval EFI_INVALID_PARAMETER     A parameter was invalid or out of range.
 158   @sa ParseHandleDatabaseByRelationshipWithType
 159 **/
 160 EFI_STATUS
 161 EFIAPI
 162 ParseHandleDatabaseByRelationship (
 163   IN CONST EFI_HANDLE       DriverBindingHandle OPTIONAL,
 164   IN CONST EFI_HANDLE       ControllerHandle OPTIONAL,
 165   IN CONST UINTN            Mask,
 166   IN UINTN                  *MatchingHandleCount,
 167   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 168   );
 169
 170 /**
 171   Gets all the related EFI_HANDLEs based on the mask supplied.
 172
 173   This function scans all EFI_HANDLES in the UEFI environment's handle database
 174   and returns the ones with the specified relationship (Mask) to the specified
 175   controller handle.
 176
 177   If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
 178   If MatchingHandleCount is NULL, then ASSERT.
 179
 180   If MatchingHandleBuffer is not NULL upon a successful return the memory must be
 181   caller freed.
 182
 183   @param[in] DriverBindingHandle    The handle with Driver Binding protocol on it.
 184   @param[in] ControllerHandle       The handle with Device Path protocol on it.
 185   @param[in] MatchingHandleCount    The pointer to UINTN that specifies the number of HANDLES in
 186                                     MatchingHandleBuffer.
 187   @param[out] MatchingHandleBuffer  On a successful return, a buffer of MatchingHandleCount
 188                                     EFI_HANDLEs with a terminating NULL EFI_HANDLE.
 189   @param[out] HandleType            An array of type information.
 190
 191   @retval EFI_SUCCESS               The operation was successful, and any related handles
 192                                     are in MatchingHandleBuffer.
 193   @retval EFI_NOT_FOUND             No matching handles were found.
 194   @retval EFI_INVALID_PARAMETER     A parameter was invalid or out of range.
 195 **/
 196 EFI_STATUS
 197 EFIAPI
 198 ParseHandleDatabaseByRelationshipWithType (
 199   IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL,
 200   IN CONST EFI_HANDLE ControllerHandle OPTIONAL,
 201   IN UINTN            *HandleCount,
 202   OUT EFI_HANDLE      **HandleBuffer,
 203   OUT UINTN           **HandleType
 204   );
 205
 206 /**
 207   Gets handles for any parents of the passed in controller.
 208
 209   @param[in] ControllerHandle       The handle of the controller.
 210   @param[in] Count                  The pointer to the number of handles in
 211                                     MatchingHandleBuffer on return.
 212   @param[out] Buffer                The buffer containing handles on a successful
 213                                     return.
 214   @retval EFI_SUCCESS               The operation was successful.
 215   @sa ParseHandleDatabaseByRelationship
 216 **/
 217 #define PARSE_HANDLE_DATABASE_PARENTS(ControllerHandle, Count, Buffer) \
 218   ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_PARENT_HANDLE, Count, Buffer)
 219
 220 /**
 221   Gets handles for any UEFI drivers of the passed in controller.
 222
 223   @param[in] ControllerHandle       The handle of the controller.
 224   @param[in] Count                  The pointer to the number of handles in
 225                                     MatchingHandleBuffer on return.
 226   @param[out] Buffer                The buffer containing handles on a successful
 227                                     return.
 228   @retval EFI_SUCCESS               The operation was successful.
 229   @sa ParseHandleDatabaseByRelationship
 230 **/
 231 #define PARSE_HANDLE_DATABASE_UEFI_DRIVERS(ControllerHandle, Count, Buffer) \
 232   ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_DRIVER_BINDING_HANDLE|HR_DEVICE_DRIVER, Count, Buffer)
 233
 234 /**
 235   Gets handles for any children of the passed in controller by the passed in driver handle.
 236
 237   @param[in] DriverHandle           The handle of the driver.
 238   @param[in] ControllerHandle       The handle of the controller.
 239   @param[in] Count                  The pointer to the number of handles in
 240                                     MatchingHandleBuffer on return.
 241   @param[out] Buffer                The buffer containing handles on a successful
 242                                     return.
 243   @retval EFI_SUCCESS               The operation was successful.
 244   @sa ParseHandleDatabaseByRelationship
 245 **/
 246 #define PARSE_HANDLE_DATABASE_MANAGED_CHILDREN(DriverHandle, ControllerHandle, Count, Buffer) \
 247   ParseHandleDatabaseByRelationship(DriverHandle, ControllerHandle, HR_CHILD_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
 248
 249 /**
 250   Gets handles for any devices managed by the passed in driver.
 251
 252   @param[in] DriverHandle           The handle of the driver.
 253   @param[in] Count                  The pointer to the number of handles in
 254                                     MatchingHandleBuffer on return.
 255   @param[out] Buffer                The buffer containing handles on a successful
 256                                     return.
 257   @retval EFI_SUCCESS               The operation was successful.
 258   @sa ParseHandleDatabaseByRelationship
 259 **/
 260 #define PARSE_HANDLE_DATABASE_DEVICES(DriverHandle, Count, Buffer) \
 261   ParseHandleDatabaseByRelationship(DriverHandle, NULL, HR_CONTROLLER_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
 262
 263 /**
 264   Gets handles for any child devices produced by the passed in driver.
 265
 266   @param[in] DriverHandle           The handle of the driver.
 267   @param[in] MatchingHandleCount    The pointer to the number of handles in
 268                                     MatchingHandleBuffer on return.
 269   @param[out] MatchingHandleBuffer  The buffer containing handles on a successful
 270                                     return.
 271   @retval EFI_SUCCESS               The operation was successful.
 272   @sa ParseHandleDatabaseByRelationship
 273 **/
 274 EFI_STATUS
 275 EFIAPI
 276 ParseHandleDatabaseForChildDevices(
 277   IN CONST EFI_HANDLE       DriverHandle,
 278   IN UINTN                  *MatchingHandleCount,
 279   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 280   );
 281
 282 /**
 283   Gets handles for any child controllers of the passed in controller.
 284
 285   @param[in] ControllerHandle       The handle of the "parent controller".
 286   @param[in] MatchingHandleCount    The pointer to the number of handles in
 287                                     MatchingHandleBuffer on return.
 288   @param[out] MatchingHandleBuffer  The buffer containing handles on a successful
 289                                     return.
 290   @retval EFI_SUCCESS               The operation was successful.
 291   @sa ParseHandleDatabaseByRelationship
 292 **/
 293 EFI_STATUS
 294 EFIAPI
 295 ParseHandleDatabaseForChildControllers(
 296   IN CONST EFI_HANDLE       ControllerHandle,
 297   IN UINTN                  *MatchingHandleCount,
 298   OUT EFI_HANDLE            **MatchingHandleBuffer OPTIONAL
 299   );
 300
 301
 302 /**
 303   Function to retrieve the human-friendly index of a given handle.  If the handle
 304   does not have a index one will be automatically assigned.  The index value is valid
 305   until the termination of the shell application.
 306
 307   @param[in] TheHandle    The handle to retrieve an index for.
 308
 309   @retval 0               A memory allocation failed.
 310   @return                 The index of the handle.
 311
 312 **/
 313 UINTN
 314 EFIAPI
 315 ConvertHandleToHandleIndex(
 316   IN CONST EFI_HANDLE TheHandle
 317   );
 318
 319 /**
 320   Function to retrieve the EFI_HANDLE from the human-friendly index.
 321
 322   @param[in] TheIndex     The index to retrieve the EFI_HANDLE for.
 323
 324   @retval NULL            The index was invalid.
 325   @return                 The EFI_HANDLE that index represents.
 326
 327 **/
 328 EFI_HANDLE
 329 EFIAPI
 330 ConvertHandleIndexToHandle(
 331   IN CONST UINTN TheIndex
 332   );
 333
 334 /**
 335   Function to get all handles that support a given protocol or all handles.
 336
 337   @param[in] ProtocolGuid The guid of the protocol to get handles for.  If NULL
 338                           then the function will return all handles.
 339
 340   @retval NULL            A memory allocation failed.
 341   @return                 A NULL terminated list of handles.
 342 **/
 343 EFI_HANDLE*
 344 EFIAPI
 345 GetHandleListByProtocol (
 346   IN CONST EFI_GUID *ProtocolGuid OPTIONAL
 347   );
 348
 349 /**
 350   Function to get all handles that support some protocols.
 351
 352   @param[in] ProtocolGuids  A NULL terminated list of protocol GUIDs.
 353
 354   @retval NULL              A memory allocation failed.
 355   @retval NULL              ProtocolGuids was NULL.
 356   @return                   A NULL terminated list of EFI_HANDLEs.
 357 **/
 358 EFI_HANDLE*
 359 EFIAPI
 360 GetHandleListByProtocolList (
 361   IN CONST EFI_GUID **ProtocolGuids
 362   );
 363
 364 #endif // __HANDLE_PARSING_LIB__