| 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 | GetHandleListByProtocol (
|
|---|
| 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 | @retval NULL ProtocolGuids was NULL.
|
|---|
| 335 | @return A NULL terminated list of EFI_HANDLEs.
|
|---|
| 336 | **/
|
|---|
| 337 | EFI_HANDLE*
|
|---|
| 338 | EFIAPI
|
|---|
| 339 | GetHandleListByProtocolList (
|
|---|
| 340 | IN CONST EFI_GUID **ProtocolGuids
|
|---|
| 341 | );
|
|---|
| 342 |
|
|---|
| 343 | #endif // __HANDLE_PARSING_LIB__
|
|---|
