1 /** @file 2 The platform device manager reference implement 3 4 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef _DEVICE_MANAGER_H_ 10 #define _DEVICE_MANAGER_H_ 11 12 #include "Bds.h" 13 #include "FrontPage.h" 14 #include "DeviceManagerVfr.h" 15 #include <Protocol/PciIo.h> 16 17 #define DEVICE_MANAGER_CALLBACK_DATA_SIGNATURE SIGNATURE_32 ('D', 'M', 'C', 'B') 18 #define DEVICE_MANAGER_DRIVER_HEALTH_INFO_SIGNATURE SIGNATURE_32 ('D', 'M', 'D', 'H') 19 20 21 typedef struct { 22 UINTN Signature; 23 24 /// 25 /// Device Manager HII relative handles 26 /// 27 EFI_HII_HANDLE HiiHandle; 28 29 /// 30 /// Driver Health HII relative handles 31 /// 32 EFI_HII_HANDLE DriverHealthHiiHandle; 33 34 EFI_HANDLE DriverHandle; 35 EFI_HANDLE DriverHealthHandle; 36 37 /// 38 /// Device Manager Produced protocols 39 /// 40 EFI_HII_CONFIG_ACCESS_PROTOCOL ConfigAccess; 41 42 /// 43 /// Driver Health Produced protocols 44 /// 45 EFI_HII_CONFIG_ACCESS_PROTOCOL DriverHealthConfigAccess; 46 47 /// 48 /// Configuration data 49 /// 50 UINT8 VideoBios; 51 } DEVICE_MANAGER_CALLBACK_DATA; 52 53 54 typedef struct { 55 UINTN Signature; 56 LIST_ENTRY Link; 57 58 /// 59 /// HII relative handles 60 /// 61 EFI_HII_HANDLE HiiHandle; 62 63 /// 64 /// Driver relative handles 65 /// 66 EFI_HANDLE DriverHandle; 67 EFI_HANDLE ControllerHandle; 68 EFI_HANDLE ChildHandle; 69 70 EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth; 71 /// 72 /// Driver health messages of the specify Driver 73 /// 74 EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList; 75 76 /// 77 /// Driver Health status 78 /// 79 EFI_DRIVER_HEALTH_STATUS HealthStatus; 80 } DRIVER_HEALTH_INFO; 81 82 typedef struct { 83 EFI_STRING_ID PromptId; 84 EFI_QUESTION_ID QuestionId; 85 }MENU_INFO_ITEM; 86 87 typedef struct { 88 UINTN CurListLen; 89 UINTN MaxListLen; 90 MENU_INFO_ITEM *NodeList; 91 } MAC_ADDRESS_NODE_LIST; 92 93 #define DEVICE_MANAGER_HEALTH_INFO_FROM_LINK(a) \ 94 CR (a, \ 95 DRIVER_HEALTH_INFO, \ 96 Link, \ 97 DEVICE_MANAGER_DRIVER_HEALTH_INFO_SIGNATURE \ 98 ) 99 100 #define DEVICE_MANAGER_CALLBACK_DATA_FROM_THIS(a) \ 101 CR (a, \ 102 DEVICE_MANAGER_CALLBACK_DATA, \ 103 ConfigAccess, \ 104 DEVICE_MANAGER_CALLBACK_DATA_SIGNATURE \ 105 ) 106 typedef struct { 107 EFI_STRING_ID StringId; 108 UINT16 Class; 109 } DEVICE_MANAGER_MENU_ITEM; 110 111 /** 112 This function is invoked if user selected a interactive opcode from Device Manager's 113 Formset. The decision by user is saved to gCallbackKey for later processing. If 114 user set VBIOS, the new value is saved to EFI variable. 115 116 117 @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. 118 @param Action Specifies the type of action taken by the browser. 119 @param QuestionId A unique value which is sent to the original exporting driver 120 so that it can identify the type of data to expect. 121 @param Type The type of value for the question. 122 @param Value A pointer to the data being sent to the original exporting driver. 123 @param ActionRequest On return, points to the action requested by the callback function. 124 125 @retval EFI_SUCCESS The callback successfully handled the action. 126 @retval EFI_INVALID_PARAMETER The setup browser call this function with invalid parameters. 127 128 **/ 129 EFI_STATUS 130 EFIAPI 131 DeviceManagerCallback ( 132 IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This, 133 IN EFI_BROWSER_ACTION Action, 134 IN EFI_QUESTION_ID QuestionId, 135 IN UINT8 Type, 136 IN EFI_IFR_TYPE_VALUE *Value, 137 OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest 138 ); 139 140 /** 141 This function is invoked if user selected a interactive opcode from Driver Health's 142 Formset. The decision by user is saved to gCallbackKey for later processing. 143 144 145 @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. 146 @param Action Specifies the type of action taken by the browser. 147 @param QuestionId A unique value which is sent to the original exporting driver 148 so that it can identify the type of data to expect. 149 @param Type The type of value for the question. 150 @param Value A pointer to the data being sent to the original exporting driver. 151 @param ActionRequest On return, points to the action requested by the callback function. 152 153 @retval EFI_SUCCESS The callback successfully handled the action. 154 @retval EFI_INVALID_PARAMETER The setup browser call this function with invalid parameters. 155 156 **/ 157 EFI_STATUS 158 EFIAPI 159 DriverHealthCallback ( 160 IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This, 161 IN EFI_BROWSER_ACTION Action, 162 IN EFI_QUESTION_ID QuestionId, 163 IN UINT8 Type, 164 IN EFI_IFR_TYPE_VALUE *Value, 165 OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest 166 ); 167 168 169 /** 170 171 This function registers HII packages to HII database. 172 173 @retval EFI_SUCCESS HII packages for the Device Manager were registered successfully. 174 @retval EFI_OUT_OF_RESOURCES HII packages for the Device Manager failed to be registered. 175 176 **/ 177 EFI_STATUS 178 InitializeDeviceManager ( 179 VOID 180 ); 181 182 /** 183 184 Call the browser and display the device manager to allow user 185 to configure the platform. 186 187 This function create the dynamic content for device manager. It includes 188 section header for all class of devices, one-of opcode to set VBIOS. 189 190 @retval EFI_SUCCESS Operation is successful. 191 @retval Other values if failed to clean up the dynamic content from HII 192 database. 193 194 **/ 195 EFI_STATUS 196 CallDeviceManager ( 197 VOID 198 ); 199 200 201 /** 202 Check the Driver Health status of a single controller and try to process it if not healthy. 203 204 This function called by CheckAllControllersHealthStatus () function in order to process a specify 205 contoller's health state. 206 207 @param DriverHealthList A Pointer to the list contain all of the platform driver health information. 208 @param DriverHandle The handle of driver. 209 @param ControllerHandle The class guid specifies which form set will be displayed. 210 @param ChildHandle The handle of the child controller to retrieve the health 211 status on. This is an optional parameter that may be NULL. 212 @param DriverHealth A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance. 213 @param HealthStatus The health status of the controller. 214 215 @retval EFI_INVALID_PARAMETER HealthStatus or DriverHealth is NULL. 216 @retval HealthStatus The Health status of specify controller. 217 @retval EFI_OUT_OF_RESOURCES The list of Driver Health Protocol handles can not be retrieved. 218 @retval EFI_NOT_FOUND No controller in the platform install Driver Health Protocol. 219 @retval EFI_SUCCESS The Health related operation has been taken successfully. 220 221 **/ 222 EFI_STATUS 223 EFIAPI 224 GetSingleControllerHealthStatus ( 225 IN OUT LIST_ENTRY *DriverHealthList, 226 IN EFI_HANDLE DriverHandle, 227 IN EFI_HANDLE ControllerHandle, OPTIONAL 228 IN EFI_HANDLE ChildHandle, OPTIONAL 229 IN EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth, 230 IN EFI_DRIVER_HEALTH_STATUS *HealthStatus 231 ); 232 233 /** 234 Collects all the EFI Driver Health Protocols currently present in the EFI Handle Database, 235 and queries each EFI Driver Health Protocol to determine if one or more of the controllers 236 managed by each EFI Driver Health Protocol instance are not healthy. 237 238 @param DriverHealthList A Pointer to the list contain all of the platform driver health 239 information. 240 241 @retval EFI_NOT_FOUND No controller in the platform install Driver Health Protocol. 242 @retval EFI_SUCCESS All the controllers in the platform are healthy. 243 @retval EFI_OUT_OF_RESOURCES The list of Driver Health Protocol handles can not be retrieved. 244 245 **/ 246 EFI_STATUS 247 GetAllControllersHealthStatus ( 248 IN OUT LIST_ENTRY *DriverHealthList 249 ); 250 251 /** 252 Check the healthy status of the platform, this function will return immediately while found one driver 253 in the platform are not healthy. 254 255 @retval FALSE at least one driver in the platform are not healthy. 256 @retval TRUE No controller install Driver Health Protocol, 257 or all controllers in the platform are in healthy status. 258 **/ 259 BOOLEAN 260 PlaformHealthStatusCheck ( 261 VOID 262 ); 263 264 /** 265 Repair the whole platform. 266 267 This function is the main entry for user choose "Repair All" in the front page. 268 It will try to do recovery job till all the driver health protocol installed modules 269 reach a terminal state. 270 271 @param DriverHealthList A Pointer to the list contain all of the platform driver health 272 information. 273 274 **/ 275 VOID 276 PlatformRepairAll ( 277 IN LIST_ENTRY *DriverHealthList 278 ); 279 280 /** 281 Processes a single controller using the EFI Driver Health Protocol associated with 282 that controller. This algorithm continues to query the GetHealthStatus() service until 283 one of the legal terminal states of the EFI Driver Health Protocol is reached. This may 284 require the processing of HII Messages, HII Form, and invocation of repair operations. 285 286 @param DriverHealth A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance. 287 @param ControllerHandle The class guid specifies which form set will be displayed. 288 @param ChildHandle The handle of the child controller to retrieve the health 289 status on. This is an optional parameter that may be NULL. 290 @param HealthStatus The health status of the controller. 291 @param MessageList An array of warning or error messages associated 292 with the controller specified by ControllerHandle and 293 ChildHandle. This is an optional parameter that may be NULL. 294 @param FormHiiHandle The HII handle for an HII form associated with the 295 controller specified by ControllerHandle and ChildHandle. 296 @param RebootRequired Indicate whether a reboot is required to repair the controller. 297 **/ 298 VOID 299 ProcessSingleControllerHealth ( 300 IN EFI_DRIVER_HEALTH_PROTOCOL *DriverHealth, 301 IN EFI_HANDLE ControllerHandle, OPTIONAL 302 IN EFI_HANDLE ChildHandle, OPTIONAL 303 IN EFI_DRIVER_HEALTH_STATUS HealthStatus, 304 IN EFI_DRIVER_HEALTH_HII_MESSAGE **MessageList, OPTIONAL 305 IN EFI_HII_HANDLE FormHiiHandle, 306 IN OUT BOOLEAN *RebootRequired 307 ); 308 309 /** 310 Reports the progress of a repair operation. 311 312 @param[in] Value A value between 0 and Limit that identifies the current 313 progress of the repair operation. 314 315 @param[in] Limit The maximum value of Value for the current repair operation. 316 For example, a driver that wants to specify progress in 317 percent would use a Limit value of 100. 318 319 @retval EFI_SUCCESS The progress of a repair operation is reported successfully. 320 321 **/ 322 EFI_STATUS 323 EFIAPI 324 RepairNotify ( 325 IN UINTN Value, 326 IN UINTN Limit 327 ); 328 329 /** 330 Processes a set of messages returned by the GetHealthStatus () 331 service of the EFI Driver Health Protocol 332 333 @param MessageList The MessageList point to messages need to processed. 334 335 **/ 336 VOID 337 ProcessMessages ( 338 IN EFI_DRIVER_HEALTH_HII_MESSAGE *MessageList 339 ); 340 341 342 /** 343 Collect and display the platform's driver health relative information, allow user to do interactive 344 operation while the platform is unhealthy. 345 346 This function display a form which divided into two parts. The one list all modules which has installed 347 driver health protocol. The list usually contain driver name, controller name, and it's health info. 348 While the driver name can't be retrieved, will use device path as backup. The other part of the form provide 349 a choice to the user to repair all platform. 350 351 **/ 352 VOID 353 CallDriverHealth ( 354 VOID 355 ); 356 357 /** 358 359 Select the best matching language according to front page policy for best user experience. 360 361 This function supports both ISO 639-2 and RFC 4646 language codes, but language 362 code types may not be mixed in a single call to this function. 363 364 @param SupportedLanguages A pointer to a Null-terminated ASCII string that 365 contains a set of language codes in the format 366 specified by Iso639Language. 367 @param Iso639Language If TRUE, then all language codes are assumed to be 368 in ISO 639-2 format. If FALSE, then all language 369 codes are assumed to be in RFC 4646 language format. 370 371 @retval NULL The best matching language could not be found in SupportedLanguages. 372 @retval NULL There are not enough resources available to return the best matching 373 language. 374 @retval Other A pointer to a Null-terminated ASCII string that is the best matching 375 language in SupportedLanguages. 376 **/ 377 CHAR8 * 378 DriverHealthSelectBestLanguage ( 379 IN CHAR8 *SupportedLanguages, 380 IN BOOLEAN Iso639Language 381 ); 382 383 /** 384 385 This is an internal worker function to get the Component Name (2) protocol interface 386 and the language it supports. 387 388 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID. 389 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved. 390 @param ComponentName A pointer to the Component Name (2) protocol interface. 391 @param SupportedLanguage The best suitable language that matches the SupportedLangues interface for the 392 located Component Name (2) instance. 393 394 @retval EFI_SUCCESS The Component Name (2) protocol instance is successfully located and we find 395 the best matching language it support. 396 @retval EFI_UNSUPPORTED The input Language is not supported by the Component Name (2) protocol. 397 @retval Other Some error occurs when locating Component Name (2) protocol instance or finding 398 the supported language. 399 400 **/ 401 EFI_STATUS 402 GetComponentNameWorker ( 403 IN EFI_GUID *ProtocolGuid, 404 IN EFI_HANDLE DriverBindingHandle, 405 OUT EFI_COMPONENT_NAME_PROTOCOL **ComponentName, 406 OUT CHAR8 **SupportedLanguage 407 ); 408 409 /** 410 411 This is an internal worker function to get driver name from Component Name (2) protocol interface. 412 413 414 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID. 415 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved. 416 @param DriverName A pointer to the Unicode string to return. This Unicode string is the name 417 of the driver specified by This. 418 419 @retval EFI_SUCCESS The driver name is successfully retrieved from Component Name (2) protocol 420 interface. 421 @retval Other The driver name cannot be retrieved from Component Name (2) protocol 422 interface. 423 424 **/ 425 EFI_STATUS 426 GetDriverNameWorker ( 427 IN EFI_GUID *ProtocolGuid, 428 IN EFI_HANDLE DriverBindingHandle, 429 OUT CHAR16 **DriverName 430 ); 431 432 /** 433 434 This function gets driver name from Component Name 2 protocol interface and Component Name protocol interface 435 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the driver name. 436 If the attempt fails, it then gets the driver name from EFI 1.1 Component Name protocol for backward 437 compatibility support. 438 439 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved. 440 @param DriverName A pointer to the Unicode string to return. This Unicode string is the name 441 of the driver specified by This. 442 443 @retval EFI_SUCCESS The driver name is successfully retrieved from Component Name (2) protocol 444 interface. 445 @retval Other The driver name cannot be retrieved from Component Name (2) protocol 446 interface. 447 448 **/ 449 EFI_STATUS 450 DriverHealthGetDriverName ( 451 IN EFI_HANDLE DriverBindingHandle, 452 OUT CHAR16 **DriverName 453 ); 454 455 /** 456 This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface 457 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name. 458 If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward 459 compatibility support. 460 461 @param ProtocolGuid A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID. 462 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved. 463 @param ControllerHandle The handle of a controller that the driver specified by This is managing. 464 This handle specifies the controller whose name is to be returned. 465 @param ChildHandle The handle of the child controller to retrieve the name of. This is an 466 optional parameter that may be NULL. It will be NULL for device drivers. 467 It will also be NULL for bus drivers that attempt to retrieve the name 468 of the bus controller. It will not be NULL for a bus driver that attempts 469 to retrieve the name of a child controller. 470 @param ControllerName A pointer to the Unicode string to return. This Unicode string 471 is the name of the controller specified by ControllerHandle and ChildHandle. 472 473 @retval EFI_SUCCESS The controller name is successfully retrieved from Component Name (2) protocol 474 interface. 475 @retval Other The controller name cannot be retrieved from Component Name (2) protocol. 476 477 **/ 478 EFI_STATUS 479 GetControllerNameWorker ( 480 IN EFI_GUID *ProtocolGuid, 481 IN EFI_HANDLE DriverBindingHandle, 482 IN EFI_HANDLE ControllerHandle, 483 IN EFI_HANDLE ChildHandle, 484 OUT CHAR16 **ControllerName 485 ); 486 487 /** 488 This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface 489 in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name. 490 If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward 491 compatibility support. 492 493 @param DriverBindingHandle The handle on which the Component Name (2) protocol instance is retrieved. 494 @param ControllerHandle The handle of a controller that the driver specified by This is managing. 495 This handle specifies the controller whose name is to be returned. 496 @param ChildHandle The handle of the child controller to retrieve the name of. This is an 497 optional parameter that may be NULL. It will be NULL for device drivers. 498 It will also be NULL for bus drivers that attempt to retrieve the name 499 of the bus controller. It will not be NULL for a bus driver that attempts 500 to retrieve the name of a child controller. 501 @param ControllerName A pointer to the Unicode string to return. This Unicode string 502 is the name of the controller specified by ControllerHandle and ChildHandle. 503 504 @retval EFI_SUCCESS The controller name is successfully retrieved from Component Name (2) protocol 505 interface. 506 @retval Other The controller name cannot be retrieved from Component Name (2) protocol. 507 508 **/ 509 EFI_STATUS 510 DriverHealthGetControllerName ( 511 IN EFI_HANDLE DriverBindingHandle, 512 IN EFI_HANDLE ControllerHandle, 513 IN EFI_HANDLE ChildHandle, 514 OUT CHAR16 **ControllerName 515 ); 516 517 #endif 518