IntelFrameworkModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.h

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