MdePkg/Include/Protocol/DriverHealth.h

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