IntelFrameworkModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.h

   1 /** @file
   2   The platform device manager reference implement
   3
   4 Copyright (c) 2004 - 2011, 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   Repair notification function, simply print the repair progress.
 317
 318   @param  Value   The value of part has been repaired.
 319   @param  Limit   Total value need to be repaired.
 320
 321 **/
 322 VOID
 323 RepairNotify (
 324   IN  UINTN Value,
 325   IN  UINTN Limit
 326   );
 327
 328 /**
 329   Processes a set of messages returned by the GetHealthStatus ()
 330   service of the EFI Driver Health Protocol
 331
 332   @param    MessageList  The MessageList point to messages need to processed.
 333
 334 **/
 335 VOID
 336 ProcessMessages (
 337   IN  EFI_DRIVER_HEALTH_HII_MESSAGE      *MessageList
 338   );
 339
 340
 341 /**
 342   Collect and display the platform's driver health relative information, allow user to do interactive
 343   operation while the platform is unhealthy.
 344
 345   This function display a form which divided into two parts. The one list all modules which has installed
 346   driver health protocol. The list usually contain driver name, controller name, and it's health info.
 347   While the driver name can't be retrieved, will use device path as backup. The other part of the form provide
 348   a choice to the user to repair all platform.
 349
 350 **/
 351 VOID
 352 CallDriverHealth (
 353   VOID
 354   );
 355
 356 /**
 357
 358   Select the best matching language according to front page policy for best user experience.
 359
 360   This function supports both ISO 639-2 and RFC 4646 language codes, but language
 361   code types may not be mixed in a single call to this function.
 362
 363   @param  SupportedLanguages   A pointer to a Null-terminated ASCII string that
 364                                contains a set of language codes in the format
 365                                specified by Iso639Language.
 366   @param  Iso639Language       If TRUE, then all language codes are assumed to be
 367                                in ISO 639-2 format.  If FALSE, then all language
 368                                codes are assumed to be in RFC 4646 language format.
 369
 370   @retval NULL                 The best matching language could not be found in SupportedLanguages.
 371   @retval NULL                 There are not enough resources available to return the best matching
 372                                language.
 373   @retval Other                A pointer to a Null-terminated ASCII string that is the best matching
 374                                language in SupportedLanguages.
 375 **/
 376 CHAR8 *
 377 DriverHealthSelectBestLanguage (
 378   IN CHAR8        *SupportedLanguages,
 379   IN BOOLEAN      Iso639Language
 380   );
 381
 382 /**
 383
 384   This is an internal worker function to get the Component Name (2) protocol interface
 385   and the language it supports.
 386
 387   @param  ProtocolGuid         A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
 388   @param  DriverBindingHandle  The handle on which the Component Name (2) protocol instance is retrieved.
 389   @param  ComponentName        A pointer to the Component Name (2) protocol interface.
 390   @param  SupportedLanguage    The best suitable language that matches the SupportedLangues interface for the
 391                                located Component Name (2) instance.
 392
 393   @retval EFI_SUCCESS          The Component Name (2) protocol instance is successfully located and we find
 394                                the best matching language it support.
 395   @retval EFI_UNSUPPORTED      The input Language is not supported by the Component Name (2) protocol.
 396   @retval Other                Some error occurs when locating Component Name (2) protocol instance or finding
 397                                the supported language.
 398
 399 **/
 400 EFI_STATUS
 401 GetComponentNameWorker (
 402   IN  EFI_GUID                    *ProtocolGuid,
 403   IN  EFI_HANDLE                  DriverBindingHandle,
 404   OUT EFI_COMPONENT_NAME_PROTOCOL **ComponentName,
 405   OUT CHAR8                       **SupportedLanguage
 406   );
 407
 408 /**
 409
 410   This is an internal worker function to get driver name from Component Name (2) protocol interface.
 411
 412
 413   @param  ProtocolGuid         A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
 414   @param  DriverBindingHandle  The handle on which the Component Name (2) protocol instance is retrieved.
 415   @param  DriverName           A pointer to the Unicode string to return. This Unicode string is the name
 416                                of the driver specified by This.
 417
 418   @retval EFI_SUCCESS          The driver name is successfully retrieved from Component Name (2) protocol
 419                                interface.
 420   @retval Other                The driver name cannot be retrieved from Component Name (2) protocol
 421                                interface.
 422
 423 **/
 424 EFI_STATUS
 425 GetDriverNameWorker (
 426   IN  EFI_GUID    *ProtocolGuid,
 427   IN  EFI_HANDLE  DriverBindingHandle,
 428   OUT CHAR16      **DriverName
 429   );
 430
 431 /**
 432
 433   This function gets driver name from Component Name 2 protocol interface and Component Name protocol interface
 434   in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the driver name.
 435   If the attempt fails, it then gets the driver name from EFI 1.1 Component Name protocol for backward
 436   compatibility support.
 437
 438   @param  DriverBindingHandle  The handle on which the Component Name (2) protocol instance is retrieved.
 439   @param  DriverName           A pointer to the Unicode string to return. This Unicode string is the name
 440                                of the driver specified by This.
 441
 442   @retval EFI_SUCCESS          The driver name is successfully retrieved from Component Name (2) protocol
 443                                interface.
 444   @retval Other                The driver name cannot be retrieved from Component Name (2) protocol
 445                                interface.
 446
 447 **/
 448 EFI_STATUS
 449 DriverHealthGetDriverName (
 450   IN  EFI_HANDLE  DriverBindingHandle,
 451   OUT CHAR16      **DriverName
 452   );
 453
 454 /**
 455   This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface
 456   in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name.
 457   If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward
 458   compatibility support.
 459
 460   @param  ProtocolGuid         A pointer to an EFI_GUID. It points to Component Name (2) protocol GUID.
 461   @param  DriverBindingHandle  The handle on which the Component Name (2) protocol instance is retrieved.
 462   @param  ControllerHandle     The handle of a controller that the driver specified by This is managing.
 463                                This handle specifies the controller whose name is to be returned.
 464   @param  ChildHandle          The handle of the child controller to retrieve the name of. This is an
 465                                optional parameter that may be NULL. It will be NULL for device drivers.
 466                                It will also be NULL for bus drivers that attempt to retrieve the name
 467                                of the bus controller. It will not be NULL for a bus driver that attempts
 468                                to retrieve the name of a child controller.
 469   @param  ControllerName       A pointer to the Unicode string to return. This Unicode string
 470                                is the name of the controller specified by ControllerHandle and ChildHandle.
 471
 472   @retval  EFI_SUCCESS         The controller name is successfully retrieved from Component Name (2) protocol
 473                                interface.
 474   @retval  Other               The controller name cannot be retrieved from Component Name (2) protocol.
 475
 476 **/
 477 EFI_STATUS
 478 GetControllerNameWorker (
 479   IN  EFI_GUID    *ProtocolGuid,
 480   IN  EFI_HANDLE  DriverBindingHandle,
 481   IN  EFI_HANDLE  ControllerHandle,
 482   IN  EFI_HANDLE  ChildHandle,
 483   OUT CHAR16      **ControllerName
 484   );
 485
 486 /**
 487   This function gets controller name from Component Name 2 protocol interface and Component Name protocol interface
 488   in turn. It first tries UEFI 2.0 Component Name 2 protocol interface and try to get the controller name.
 489   If the attempt fails, it then gets the controller name from EFI 1.1 Component Name protocol for backward
 490   compatibility support.
 491
 492   @param  DriverBindingHandle  The handle on which the Component Name (2) protocol instance is retrieved.
 493   @param  ControllerHandle     The handle of a controller that the driver specified by This is managing.
 494                                This handle specifies the controller whose name is to be returned.
 495   @param  ChildHandle          The handle of the child controller to retrieve the name of. This is an
 496                                optional parameter that may be NULL. It will be NULL for device drivers.
 497                                It will also be NULL for bus drivers that attempt to retrieve the name
 498                                of the bus controller. It will not be NULL for a bus driver that attempts
 499                                to retrieve the name of a child controller.
 500   @param  ControllerName       A pointer to the Unicode string to return. This Unicode string
 501                                is the name of the controller specified by ControllerHandle and ChildHandle.
 502
 503   @retval EFI_SUCCESS          The controller name is successfully retrieved from Component Name (2) protocol
 504                                interface.
 505   @retval Other                The controller name cannot be retrieved from Component Name (2) protocol.
 506
 507 **/
 508 EFI_STATUS
 509 DriverHealthGetControllerName (
 510   IN  EFI_HANDLE  DriverBindingHandle,
 511   IN  EFI_HANDLE  ControllerHandle,
 512   IN  EFI_HANDLE  ChildHandle,
 513   OUT CHAR16      **ControllerName
 514   );
 515
 516 #endif