IntelFrameworkModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.h

   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