xref: /illumos-gate/usr/src/boot/efi/include/Protocol/DriverHealth.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
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 - 2018, Intel Corporation. All rights reserved.<BR>
24   Copyright (c) 2014, Hewlett-Packard Development Company, L.P.<BR>
25   SPDX-License-Identifier: BSD-2-Clause-Patent
26 
27   @par Revision Reference:
28   This Protocol is defined in UEFI Specification 2.3d
29 
30 **/
31 
32 #ifndef __EFI_DRIVER_HEALTH_H__
33 #define __EFI_DRIVER_HEALTH_H__
34 
35 #define EFI_DRIVER_HEALTH_PROTOCOL_GUID \
36   { \
37     0x2a534210, 0x9280, 0x41d8, { 0xae, 0x79, 0xca, 0xda, 0x1, 0xa2, 0xb1, 0x27 } \
38   }
39 
40 typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;
41 
42 ///
43 /// EFI_DRIVER_HEALTH_HEALTH_STATUS
44 ///
45 typedef enum {
46   EfiDriverHealthStatusHealthy,
47   EfiDriverHealthStatusRepairRequired,
48   EfiDriverHealthStatusConfigurationRequired,
49   EfiDriverHealthStatusFailed,
50   EfiDriverHealthStatusReconnectRequired,
51   EfiDriverHealthStatusRebootRequired
52 } EFI_DRIVER_HEALTH_STATUS;
53 
54 ///
55 /// EFI_DRIVER_HEALTH_HII_MESSAGE
56 ///
57 typedef struct {
58   EFI_HII_HANDLE    HiiHandle;
59   EFI_STRING_ID     StringId;
60 
61   ///
62   /// 64-bit numeric value of the warning/error specified by this message.
63   ///   A value of 0x0000000000000000 is used to indicate that MessageCode is not specified.
64   ///   The values  0x0000000000000001 to 0x0fffffffffffffff are reserved for allocation by the UEFI Specification.
65   ///   The values  0x1000000000000000 to 0x1fffffffffffffff are reserved for IHV-developed drivers.
66   ///   The values 0x8000000000000000 to 0x8fffffffffffffff is reserved for platform/OEM drivers.
67   ///   All other values are reserved and should not be used.
68   ///
69   UINT64    MessageCode;
70 } EFI_DRIVER_HEALTH_HII_MESSAGE;
71 
72 /**
73   Reports the progress of a repair operation
74 
75   @param[in]  Value             A value between 0 and Limit that identifies the current
76                                 progress of the repair operation.
77 
78   @param[in]  Limit             The maximum value of Value for the current repair operation.
79                                 For example, a driver that wants to specify progress in
80                                 percent would use a Limit value of 100.
81 **/
82 typedef
83 EFI_STATUS
84 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR_NOTIFY)(
85   IN UINTN  Value,
86   IN UINTN  Limit
87   );
88 
89 /**
90   Retrieves the health status of a controller in the platform.  This function can also
91   optionally return warning messages, error messages, and a set of HII Forms that may
92   be repair a controller that is not proper configured.
93 
94   @param[in] This             A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
95 
96   @param[in] ControllerHandle The handle of the controller to retrieve the health status
97                               on.  This is an optional parameter that may be NULL.  If
98                               this parameter is NULL, then the value of ChildHandle is
99                               ignored, and the combined health status of all the devices
100                               that the driver is managing is returned.
101 
102   @param[in] ChildHandle      The handle of the child controller to retrieve the health
103                               status on.  This is an optional parameter that may be NULL.
104                               This parameter is ignored of ControllerHandle is NULL.  It
105                               will be NULL for device drivers.  It will also be NULL for
106                               bus drivers when an attempt is made to collect the health
107                               status of the bus controller.  If will not be NULL when an
108                               attempt is made to collect the health status for a child
109                               controller produced by the driver.
110 
111   @param[out] HealthStatus    A pointer to the health status that is returned by this
112                               function.  This is an optional parameter that may be NULL.
113                               This parameter is ignored of ControllerHandle is NULL.
114                               The health status for the controller specified by
115                               ControllerHandle and ChildHandle is returned.
116 
117   @param[out] MessageList     A pointer to an array of warning or error messages associated
118                               with the controller specified by ControllerHandle and
119                               ChildHandle.  This is an optional parameter that may be NULL.
120                               MessageList is allocated by this function with the EFI Boot
121                               Service AllocatePool(), and it is the caller's responsibility
122                               to free MessageList with the EFI Boot Service FreePool().
123                               Each message is specified by tuple of an EFI_HII_HANDLE and
124                               an EFI_STRING_ID.  The array of messages is terminated by tuple
125                               containing a EFI_HII_HANDLE with a value of NULL.  The
126                               EFI_HII_STRING_PROTOCOL.GetString() function can be used to
127                               retrieve the warning or error message as a Null-terminated
128                               string in a specific language.  Messages may be
129                               returned for any of the HealthStatus values except
130                               EfiDriverHealthStatusReconnectRequired and
131                               EfiDriverHealthStatusRebootRequired.
132 
133   @param[out] FormHiiHandle   A pointer to the HII handle containing the HII form used when
134                               configuration is required. The HII handle is associated with
135                               the controller specified by ControllerHandle and ChildHandle.
136                               If this is NULL, then no HII form is available. An HII handle
137                               will only be returned with a HealthStatus value of
138                               EfiDriverHealthStatusConfigurationRequired.
139 
140   @retval EFI_SUCCESS           ControllerHandle is NULL, and all the controllers
141                                 managed by this driver specified by This have a health
142                                 status of EfiDriverHealthStatusHealthy with no warning
143                                 messages to be returned.  The ChildHandle, HealthStatus,
144                                 MessageList, and FormList parameters are ignored.
145 
146   @retval EFI_DEVICE_ERROR      ControllerHandle is NULL, and one or more of the
147                                 controllers managed by this driver specified by This
148                                 do not have a health status of EfiDriverHealthStatusHealthy.
149                                 The ChildHandle, HealthStatus, MessageList, and
150                                 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                                 have one or more warning and/or error messages.
155                                 The ChildHandle, HealthStatus, MessageList, and
156                                 FormList parameters are ignored.
157 
158   @retval EFI_SUCCESS           ControllerHandle is not NULL and the health status
159                                 of the controller specified by ControllerHandle and
160                                 ChildHandle was returned in HealthStatus.  A list
161                                 of warning and error messages may be optionally
162                                 returned in MessageList, and a list of HII Forms
163                                 may be optionally returned in FormList.
164 
165   @retval EFI_UNSUPPORTED       ControllerHandle is not NULL, and the controller
166                                 specified by ControllerHandle and ChildHandle is not
167                                 currently being managed by the driver specified by This.
168 
169   @retval EFI_INVALID_PARAMETER HealthStatus is NULL.
170 
171   @retval EFI_OUT_OF_RESOURCES  MessageList is not NULL, and there are not enough
172                                 resource available to allocate memory for MessageList.
173 
174 **/
175 typedef
176 EFI_STATUS
177 (EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(
178   IN  EFI_DRIVER_HEALTH_PROTOCOL       *This,
179   IN  EFI_HANDLE                       ControllerHandle OPTIONAL,
180   IN  EFI_HANDLE                       ChildHandle      OPTIONAL,
181   OUT EFI_DRIVER_HEALTH_STATUS         *HealthStatus,
182   OUT EFI_DRIVER_HEALTH_HII_MESSAGE    **MessageList    OPTIONAL,
183   OUT EFI_HII_HANDLE                   *FormHiiHandle   OPTIONAL
184   );
185 
186 /**
187   Performs a repair operation on a controller in the platform.  This function can
188   optionally report repair progress information back to the platform.
189 
190   @param[in] This              A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
191   @param[in] ControllerHandle  The handle of the controller to repair.
192   @param[in] ChildHandle       The handle of the child controller to repair.  This is
193                                an optional parameter that may be NULL.  It will be NULL
194                                for device drivers.  It will also be NULL for bus
195                                drivers when an attempt is made to repair a bus controller.
196                                If will not be NULL when an attempt is made to repair a
197                                child controller produced by the driver.
198   @param[in] RepairNotify      A notification function that may be used by a driver to
199                                report the progress of the repair operation.  This is
200                                an optional parameter that may be NULL.
201 
202 
203   @retval EFI_SUCCESS           An attempt to repair the controller specified by
204                                 ControllerHandle and ChildHandle was performed.
205                                 The result of the repair operation can bet
206                                 determined by calling GetHealthStatus().
207   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
208                                 managing the controller specified by ControllerHandle
209                                 and ChildHandle.
210   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to perform the
211                                 repair operation.
212 
213 */
214 typedef
215 EFI_STATUS
216 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(
217   IN  EFI_DRIVER_HEALTH_PROTOCOL                *This,
218   IN  EFI_HANDLE                                ControllerHandle,
219   IN  EFI_HANDLE                                ChildHandle       OPTIONAL,
220   IN  EFI_DRIVER_HEALTH_REPAIR_NOTIFY           RepairNotify      OPTIONAL
221   );
222 
223 ///
224 /// When installed, the Driver Health Protocol produces a collection of services
225 /// that allow the health status for a controller to be retrieved.  If a controller
226 /// is not in a usable state, status messages may be reported to the user, repair
227 /// operations can be invoked, and the user may be asked to make software and/or
228 /// hardware configuration changes.
229 ///
230 struct _EFI_DRIVER_HEALTH_PROTOCOL {
231   EFI_DRIVER_HEALTH_GET_HEALTH_STATUS    GetHealthStatus;
232   EFI_DRIVER_HEALTH_REPAIR               Repair;
233 };
234 
235 extern EFI_GUID  gEfiDriverHealthProtocolGuid;
236 
237 #endif
238