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