MdePkg/Include/Protocol/DriverHealth.h

   1 /** @file
   2   EFI Driver Health Protocol definitions.
   3
   4   When installed, the Driver Health Protocol produces a collection of services that allow
   5   the health status for a controller to be retrieved. If a controller is not in a usable
   6   state, status messages may be reported to the user, repair operations can be invoked,
   7   and the user may be asked to make software and/or hardware configuration changes.
   8
   9   The Driver Health Protocol is optionally produced by a driver that follows the
  10   EFI Driver Model.  If an EFI Driver needs to report health status to the platform,
  11   provide warning or error messages to the user, perform length repair operations,
  12   or request the user to make hardware or software configuration changes, then the
  13   Driver Health Protocol must be produced.
  14
  15   A controller that is managed by driver that follows the EFI Driver Model and
  16   produces the Driver Health Protocol must report the current health of the
  17   controllers that the driver is currently managing.  The controller can initially
  18   be healthy, failed, require repair, or require configuration.  If a controller
  19   requires configuration, and the user make configuration changes, the controller
  20   may then need to be reconnected or the system may need to be rebooted for the
  21   configuration changes to take affect.
  22
  23   Copyright (c) 2009, Intel Corporation
  24   All rights reserved. This program and the accompanying materials
  25   are licensed and made available under the terms and conditions of the BSD License
  26   which accompanies this distribution.  The full text of the license may be found at
  27   http://opensource.org/licenses/bsd-license.php
  28
  29   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  30   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  31
  32   @par Revision Reference:
  33   This Protocol is defined in UEFI Specification 2.2
  34
  35 **/
  36
  37 #ifndef __EFI_DRIVER_HEALTH_H__
  38 #define __EFI_DRIVER_HEALTH_H__
  39
  40 #define EFI_DRIVER_HEALTH_PROTOCOL_GUID \
  41   { \
  42     0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \
  43   }
  44
  45 typedef struct _EFI_DRIVER_HEALTH_PROTOCOL  EFI_DRIVER_HEALTH_PROTOCOL;
  46
  47 ///
  48 /// EFI_DRIVER_HEALTH_HEALTH_STATUS
  49 ///
  50 typedef enum {
  51   EfiDriverHealthStatusHealthy,
  52   EfiDriverHealthStatusRepairRequired,
  53   EfiDriverHealthStatusConfigurationRequired,
  54   EfiDriverHealthStatusFailed,
  55   EfiDriverHealthStatusReconnectRequired,
  56   EfiDriverHealthStatusRebootRequired
  57 } EFI_DRIVER_HEALTH_STATUS;
  58
  59 ///
  60 /// EFI_DRIVER_HEALTH_HII_MESSAGE
  61 ///
  62 typedef struct {
  63   EFI_HII_HANDLE  HiiHandle;
  64   EFI_STRING_ID   StringId;
  65   UINT64          Reserved;
  66 } EFI_DRIVER_HEALTH_HII_MESSAGE;
  67
  68 /**
  69   Reports the progress of a repair operation
  70
  71   @param  Value                 A value between 0 and Limit that identifies the current
  72                                 progress of the repair operation.
  73
  74   @param  Limit                 The maximum value of Value for the current repair operation.
  75                                 For example, a driver that wants to specify progress in
  76                                 percent would use a Limit value of 100.
  77
  78   @retval EFI_SUCCESS           An attempt to repair the controller specified by
  79                                 ControllerHandle and ChildHandle was performed. The
  80                                 result of the repair operation can bet determined by
  81                                 calling GetHealthStatus().
  82   @retval EFI_UNSUPPORTED       The driver specified by This is not currently managing the
  83                                 controller specified by ControllerHandle and
  84                                 ChildHandle.
  85   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to perform the repair operation.
  86
  87 **/
  88 typedef
  89 EFI_STATUS
  90 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY)(
  91   IN UINTN  Value,
  92   IN UINTN  Limit
  93   );
  94
  95 /**
  96   Retrieves the health status of a controller in the platform.  This function can also
  97   optionally return warning messages, error messages, and a set of HII Forms that may
  98   be repair a controller that is not proper configured.
  99
 100   @param  This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
 101
 102   @param  ControllerHandle The handle of the controller to retrieve the health status
 103                            on.  This is an optional parameter that may be NULL.  If
 104                            this parameter is NULL, then the value of ChildHandle is
 105                            ignored, and the combined health status of all the devices
 106                            that the driver is managing is returned.
 107
 108   @param  ChildHandle      The handle of the child controller to retrieve the health
 109                            status on.  This is an optional parameter that may be NULL.
 110                            This parameter is ignored of ControllerHandle is NULL.  It
 111                            will be NULL for device drivers.  It will also be NULL for
 112                            bus drivers when an attempt is made to collect the health
 113                            status of the bus controller.  If will not be NULL when an
 114                            attempt is made to collect the health status for a child
 115                            controller produced by the driver.
 116
 117   @param  HealthStatus     A pointer to the health status that is returned by this
 118                            function.  This is an optional parameter that may be NULL.
 119                            This parameter is ignored of ControllerHandle is NULL.
 120                            The health status for the controller specified by
 121                            ControllerHandle and ChildHandle is returned.
 122
 123   @param  MessageList      A pointer to an array of warning or error messages associated
 124                            with the controller specified by ControllerHandle and
 125                            ChildHandle.  This is an optional parameter that may be NULL.
 126                            MessageList is allocated by this function with the EFI Boot
 127                            Service AllocatePool(), and it is the caller's responsibility
 128                            to free MessageList with the EFI Boot Service FreePool().
 129                            Each message is specified by tuple of an EFI_HII_HANDLE and
 130                            an EFI_STRING_ID.  The array of messages is terminated by tuple
 131                            containing a EFI_HII_HANDLE with a value of NULL.  The
 132                            EFI_HII_STRING_PROTOCOL.GetString() function can be used to
 133                            retrieve the warning or error message as a Null-terminated
 134                            Unicode string in a specific language.  Messages may be
 135                            returned for any of the HealthStatus values except
 136                            EfiDriverHealthStatusReconnectRequired and
 137                            EfiDriverHealthStatusRebootRequired.
 138
 139   @param  FormHiiHandle    A pointer to the HII handle for an HII form associated with the
 140                            controller specified by ControllerHandle and ChildHandle.
 141                            This is an optional parameter that may be NULL.  An HII form
 142                            is specified by a combination of an EFI_HII_HANDLE and an
 143                            EFI_GUID that identifies the Form Set GUID.  The
 144                            EFI_FORM_BROWSER2_PROTOCOL.SendForm() function can be used
 145                            to display and allow the user to make configuration changes
 146                            to the HII Form.  An HII form may only be returned with a
 147                            HealthStatus value of EfiDriverHealthStatusConfigurationRequired.
 148
 149   @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers
 150                                 managed by this driver specified by This have a health
 151                                 status of EfiDriverHealthStatusHealthy with no warning
 152                                 messages to be returned.  The ChildHandle, HealthStatus,
 153                                 MessageList, and FormList parameters are ignored.
 154
 155   @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the
 156                                 controllers managed by this driver specified by This
 157                                 do not have a health status of EfiDriverHealthStatusHealthy.
 158                                 The ChildHandle, HealthStatus, MessageList, and
 159                                 FormList parameters are ignored.
 160
 161   @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the
 162                                 controllers managed by this driver specified by This
 163                                 have one or more warning and/or error messages.
 164                                 The ChildHandle, HealthStatus, MessageList, and
 165                                 FormList parameters are ignored.
 166
 167   @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status
 168                                 of the controller specified by ControllerHandle and
 169                                 ChildHandle was returned in HealthStatus.  A list
 170                                 of warning and error messages may be optionally
 171                                 returned in MessageList, and a list of HII Forms
 172                                 may be optionally returned in FormList.
 173
 174   @retval EFI_UNSUPPORTED             ControllerHandle is not NULL, and the controller
 175                                 specified by ControllerHandle and ChildHandle is not
 176                                 currently being managed by the driver specified by This.
 177
 178   @retval EFI_INVALID_PARAMETER HealthStatus is NULL.
 179
 180   @retval EFI_OUT_OF_RESOURCES  MessageList is not NULL, and there are not enough
 181                                 resource available to allocate memory for MessageList.
 182
 183 **/
 184 typedef
 185 EFI_STATUS
 186 (EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(
 187   IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,
 188   IN  EFI_HANDLE                       ControllerHandle OPTIONAL,
 189   IN  EFI_HANDLE                       ChildHandle      OPTIONAL,
 190   OUT EFI_DRIVER_HEALTH_STATUS         *HealthStatus,
 191   OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList    OPTIONAL,
 192   OUT EFI_HII_HANDLE                   *FormHiiHandle   OPTIONAL
 193   );
 194
 195 /**
 196   Performs a repair operation on a controller in the platform.  This function can
 197   optionally report repair progress information back to the platform.
 198
 199   @param  This                  A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
 200   @param  ControllerHandle      The handle of the controller to repair.
 201   @param  ChildHandle           The handle of the child controller to repair.  This is
 202                                 an optional parameter that may be NULL.  It will be NULL
 203                                 for device drivers.  It will also be NULL for bus
 204                                 drivers when an attempt is made to repair a bus controller.
 205                                 If will not be NULL when an attempt is made to repair a
 206                                 child controller produced by the driver.
 207   @param  ProgressNotification  A notification function that may be used by a driver to
 208                                 report the progress of the repair operation.  This is
 209                                 an optional parameter that may be NULL.
 210
 211
 212   @retval EFI_SUCCESS             An attempt to repair the controller specified by
 213                                 ControllerHandle and ChildHandle was performed.
 214                                 The result of the repair operation can bet
 215                                 determined by calling GetHealthStatus().
 216   @retval EFI_UNSUPPORTED             The driver specified by This is not currently
 217                                 managing the controller specified by ControllerHandle
 218                                 and ChildHandle.
 219   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to perform the
 220                                 repair operation.
 221
 222 */
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(
 226   IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,
 227   IN  EFI_HANDLE                                ControllerHandle,
 228   IN  EFI_HANDLE                                ChildHandle          OPTIONAL,
 229   IN  EFI_DRIVER_HEALTH_REPAIR_PROGRESS_NOTIFY  ProgressNotification OPTIONAL
 230   );
 231
 232 ///
 233 /// When installed, the Driver Health Protocol produces a collection of services
 234 /// that allow the health status for a controller to be retrieved.  If a controller
 235 /// is not in a usable state, status messages may be reported to the user, repair
 236 /// operations can be invoked, and the user may be asked to make software and/or
 237 /// hardware configuration changes.
 238 ///
 239 struct _EFI_DRIVER_HEALTH_PROTOCOL {
 240   EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;
 241   EFI_DRIVER_HEALTH_REPAIR             Repair;
 242 };
 243
 244 extern EFI_GUID gEfiDriverHealthProtocolGuid;
 245
 246 #endif
 247
 248
 249
 250