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