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 - 2013, Intel Corporation. All rights reserved.<BR>
  24   Copyright (c) 2014, Hewlett-Packard Development Company, L.P.<BR>
  25   This program and the accompanying materials
  26   are licensed and made available under the terms and conditions of the BSD License
  27   which accompanies this distribution.  The full text of the license may be found at
  28   http://opensource.org/licenses/bsd-license.php
  29
  30   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  31   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  32
  33   @par Revision Reference:
  34   This Protocol is defined in UEFI Specification 2.3d
  35
  36 **/
  37
  38 #ifndef __EFI_DRIVER_HEALTH_H__
  39 #define __EFI_DRIVER_HEALTH_H__
  40
  41 #define EFI_DRIVER_HEALTH_PROTOCOL_GUID \
  42   { \
  43     0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \
  44   }
  45
  46 typedef struct _EFI_DRIVER_HEALTH_PROTOCOL  EFI_DRIVER_HEALTH_PROTOCOL;
  47
  48 ///
  49 /// EFI_DRIVER_HEALTH_HEALTH_STATUS
  50 ///
  51 typedef enum {
  52   EfiDriverHealthStatusHealthy,
  53   EfiDriverHealthStatusRepairRequired,
  54   EfiDriverHealthStatusConfigurationRequired,
  55   EfiDriverHealthStatusFailed,
  56   EfiDriverHealthStatusReconnectRequired,
  57   EfiDriverHealthStatusRebootRequired
  58 } EFI_DRIVER_HEALTH_STATUS;
  59
  60 ///
  61 /// EFI_DRIVER_HEALTH_HII_MESSAGE
  62 ///
  63 typedef struct {
  64   EFI_HII_HANDLE  HiiHandle;
  65   EFI_STRING_ID   StringId;
  66
  67   ///
  68   /// 64-bit numeric value of the warning/error specified by this message.
  69   ///   A value of 0x0000000000000000 is used to indicate that MessageCode is not specified.
  70   ///   The values  0x0000000000000001 to 0x0fffffffffffffff are reserved for allocation by the UEFI Specification.
  71   ///   The values  0x1000000000000000 to 0x1fffffffffffffff are reserved for IHV-developed drivers.
  72   ///   The values 0x8000000000000000 to 0x8fffffffffffffff is reserved for platform/OEM drivers.
  73   ///   All other values are reserved and should not be used.
  74   ///
  75   UINT64          MessageCode;
  76 } EFI_DRIVER_HEALTH_HII_MESSAGE;
  77
  78 /**
  79   Reports the progress of a repair operation
  80
  81   @param[in]  Value             A value between 0 and Limit that identifies the current
  82                                 progress of the repair operation.
  83
  84   @param[in]  Limit             The maximum value of Value for the current repair operation.
  85                                 For example, a driver that wants to specify progress in
  86                                 percent would use a Limit value of 100.
  87 **/
  88 typedef
  89 EFI_STATUS
  90 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR_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[in] This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
 101
 102   @param[in] 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[in] 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[out] 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[out] 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                               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[out] FormHiiHandle   A pointer to the HII handle containing the HII form used when
 140                               configuration is required. The HII handle is associated with
 141                               the controller specified by ControllerHandle and ChildHandle.
 142                               If this is NULL, then no HII form is available. An HII handle
 143                               will only be returned with a HealthStatus value of
 144                               EfiDriverHealthStatusConfigurationRequired.
 145
 146   @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers
 147                                 managed by this driver specified by This have a health
 148                                 status of EfiDriverHealthStatusHealthy with no warning
 149                                 messages to be returned.  The ChildHandle, HealthStatus,
 150                                 MessageList, and FormList parameters are ignored.
 151
 152   @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the
 153                                 controllers managed by this driver specified by This
 154                                 do not have a health status of EfiDriverHealthStatusHealthy.
 155                                 The ChildHandle, HealthStatus, MessageList, and
 156                                 FormList parameters are ignored.
 157
 158   @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the
 159                                 controllers managed by this driver specified by This
 160                                 have one or more warning and/or error messages.
 161                                 The ChildHandle, HealthStatus, MessageList, and
 162                                 FormList parameters are ignored.
 163
 164   @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status
 165                                 of the controller specified by ControllerHandle and
 166                                 ChildHandle was returned in HealthStatus.  A list
 167                                 of warning and error messages may be optionally
 168                                 returned in MessageList, and a list of HII Forms
 169                                 may be optionally returned in FormList.
 170
 171   @retval EFI_UNSUPPORTED       ControllerHandle is not NULL, and the controller
 172                                 specified by ControllerHandle and ChildHandle is not
 173                                 currently being managed by the driver specified by This.
 174
 175   @retval EFI_INVALID_PARAMETER HealthStatus is NULL.
 176
 177   @retval EFI_OUT_OF_RESOURCES  MessageList is not NULL, and there are not enough
 178                                 resource available to allocate memory for MessageList.
 179
 180 **/
 181 typedef
 182 EFI_STATUS
 183 (EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(
 184   IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,
 185   IN  EFI_HANDLE                       ControllerHandle OPTIONAL,
 186   IN  EFI_HANDLE                       ChildHandle      OPTIONAL,
 187   OUT EFI_DRIVER_HEALTH_STATUS         *HealthStatus,
 188   OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList    OPTIONAL,
 189   OUT EFI_HII_HANDLE                   *FormHiiHandle   OPTIONAL
 190   );
 191
 192 /**
 193   Performs a repair operation on a controller in the platform.  This function can
 194   optionally report repair progress information back to the platform.
 195
 196   @param[in] This              A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
 197   @param[in] ControllerHandle  The handle of the controller to repair.
 198   @param[in] ChildHandle       The handle of the child controller to repair.  This is
 199                                an optional parameter that may be NULL.  It will be NULL
 200                                for device drivers.  It will also be NULL for bus
 201                                drivers when an attempt is made to repair a bus controller.
 202                                If will not be NULL when an attempt is made to repair a
 203                                child controller produced by the driver.
 204   @param[in] RepairNotify      A notification function that may be used by a driver to
 205                                report the progress of the repair operation.  This is
 206                                an optional parameter that may be NULL.
 207
 208
 209   @retval EFI_SUCCESS           An attempt to repair the controller specified by
 210                                 ControllerHandle and ChildHandle was performed.
 211                                 The result of the repair operation can bet
 212                                 determined by calling GetHealthStatus().
 213   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 214                                 managing the controller specified by ControllerHandle
 215                                 and ChildHandle.
 216   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to perform the
 217                                 repair operation.
 218
 219 */
 220 typedef
 221 EFI_STATUS
 222 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(
 223   IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,
 224   IN  EFI_HANDLE                                ControllerHandle,
 225   IN  EFI_HANDLE                                ChildHandle       OPTIONAL,
 226   IN  EFI_DRIVER_HEALTH_REPAIR_NOTIFY           RepairNotify      OPTIONAL
 227   );
 228
 229 ///
 230 /// When installed, the Driver Health Protocol produces a collection of services
 231 /// that allow the health status for a controller to be retrieved.  If a controller
 232 /// is not in a usable state, status messages may be reported to the user, repair
 233 /// operations can be invoked, and the user may be asked to make software and/or
 234 /// hardware configuration changes.
 235 ///
 236 struct _EFI_DRIVER_HEALTH_PROTOCOL {
 237   EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;
 238   EFI_DRIVER_HEALTH_REPAIR             Repair;
 239 };
 240
 241 extern EFI_GUID gEfiDriverHealthProtocolGuid;
 242
 243 #endif
 244
 245
 246
 247