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