Correct a typo: Change the type of the 4th parameter of EFI_DRIVER_HEALTH_PROTOCOL...
[mirror_edk2.git] / 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 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.3d
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[in] Value A value between 0 and Limit that identifies the current
72 progress of the repair operation.
73
74 @param[in] 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 typedef
79 EFI_STATUS
80 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR_NOTIFY)(
81 IN UINTN Value,
82 IN UINTN Limit
83 );
84
85 /**
86 Retrieves the health status of a controller in the platform. This function can also
87 optionally return warning messages, error messages, and a set of HII Forms that may
88 be repair a controller that is not proper configured.
89
90 @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
91
92 @param[in] ControllerHandle The handle of the controller to retrieve the health status
93 on. This is an optional parameter that may be NULL. If
94 this parameter is NULL, then the value of ChildHandle is
95 ignored, and the combined health status of all the devices
96 that the driver is managing is returned.
97
98 @param[in] ChildHandle The handle of the child controller to retrieve the health
99 status on. This is an optional parameter that may be NULL.
100 This parameter is ignored of ControllerHandle is NULL. It
101 will be NULL for device drivers. It will also be NULL for
102 bus drivers when an attempt is made to collect the health
103 status of the bus controller. If will not be NULL when an
104 attempt is made to collect the health status for a child
105 controller produced by the driver.
106
107 @param[out] HealthStatus A pointer to the health status that is returned by this
108 function. This is an optional parameter that may be NULL.
109 This parameter is ignored of ControllerHandle is NULL.
110 The health status for the controller specified by
111 ControllerHandle and ChildHandle is returned.
112
113 @param[out] MessageList A pointer to an array of warning or error messages associated
114 with the controller specified by ControllerHandle and
115 ChildHandle. This is an optional parameter that may be NULL.
116 MessageList is allocated by this function with the EFI Boot
117 Service AllocatePool(), and it is the caller's responsibility
118 to free MessageList with the EFI Boot Service FreePool().
119 Each message is specified by tuple of an EFI_HII_HANDLE and
120 an EFI_STRING_ID. The array of messages is terminated by tuple
121 containing a EFI_HII_HANDLE with a value of NULL. The
122 EFI_HII_STRING_PROTOCOL.GetString() function can be used to
123 retrieve the warning or error message as a Null-terminated
124 string in a specific language. Messages may be
125 returned for any of the HealthStatus values except
126 EfiDriverHealthStatusReconnectRequired and
127 EfiDriverHealthStatusRebootRequired.
128
129 @param[out] FormHiiHandle A pointer to the HII handle containing the HII form used when
130 configuration is required. The HII handle is associated with
131 the controller specified by ControllerHandle and ChildHandle.
132 If this is NULL, then no HII form is available. An HII handle
133 will only be returned with a HealthStatus value of
134 EfiDriverHealthStatusConfigurationRequired.
135
136 @retval EFI_SUCCESS ControllerHandle is NULL, and all the controllers
137 managed by this driver specified by This have a health
138 status of EfiDriverHealthStatusHealthy with no warning
139 messages to be returned. The ChildHandle, HealthStatus,
140 MessageList, and FormList parameters are ignored.
141
142 @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the
143 controllers managed by this driver specified by This
144 do not have a health status of EfiDriverHealthStatusHealthy.
145 The ChildHandle, HealthStatus, MessageList, and
146 FormList parameters are ignored.
147
148 @retval EFI_DEVICE_ERROR ControllerHandle is NULL, and one or more of the
149 controllers managed by this driver specified by This
150 have one or more warning and/or error messages.
151 The ChildHandle, HealthStatus, MessageList, and
152 FormList parameters are ignored.
153
154 @retval EFI_SUCCESS ControllerHandle is not NULL and the health status
155 of the controller specified by ControllerHandle and
156 ChildHandle was returned in HealthStatus. A list
157 of warning and error messages may be optionally
158 returned in MessageList, and a list of HII Forms
159 may be optionally returned in FormList.
160
161 @retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller
162 specified by ControllerHandle and ChildHandle is not
163 currently being managed by the driver specified by This.
164
165 @retval EFI_INVALID_PARAMETER HealthStatus is NULL.
166
167 @retval EFI_OUT_OF_RESOURCES MessageList is not NULL, and there are not enough
168 resource available to allocate memory for MessageList.
169
170 **/
171 typedef
172 EFI_STATUS
173 (EFIAPI *EFI_DRIVER_HEALTH_GET_HEALTH_STATUS)(
174 IN EFI_DRIVER_HEALTH_PROTOCOL *This,
175 IN EFI_HANDLE ControllerHandle OPTIONAL,
176 IN EFI_HANDLE ChildHandle OPTIONAL,
177 OUT EFI_DRIVER_HEALTH_STATUS *HealthStatus,
178 OUT EFI_DRIVER_HEALTH_HII_MESSAGE **MessageList OPTIONAL,
179 OUT EFI_HII_HANDLE *FormHiiHandle OPTIONAL
180 );
181
182 /**
183 Performs a repair operation on a controller in the platform. This function can
184 optionally report repair progress information back to the platform.
185
186 @param[in] This A pointer to the EFI_DRIVER_HEALTH_PROTOCOL instance.
187 @param[in] ControllerHandle The handle of the controller to repair.
188 @param[in] ChildHandle The handle of the child controller to repair. This is
189 an optional parameter that may be NULL. It will be NULL
190 for device drivers. It will also be NULL for bus
191 drivers when an attempt is made to repair a bus controller.
192 If will not be NULL when an attempt is made to repair a
193 child controller produced by the driver.
194 @param[in] RepairNotify A notification function that may be used by a driver to
195 report the progress of the repair operation. This is
196 an optional parameter that may be NULL.
197
198
199 @retval EFI_SUCCESS An attempt to repair the controller specified by
200 ControllerHandle and ChildHandle was performed.
201 The result of the repair operation can bet
202 determined by calling GetHealthStatus().
203 @retval EFI_UNSUPPORTED The driver specified by This is not currently
204 managing the controller specified by ControllerHandle
205 and ChildHandle.
206 @retval EFI_OUT_OF_RESOURCES There are not enough resources to perform the
207 repair operation.
208
209 */
210 typedef
211 EFI_STATUS
212 (EFIAPI *EFI_DRIVER_HEALTH_REPAIR)(
213 IN EFI_DRIVER_HEALTH_PROTOCOL *This,
214 IN EFI_HANDLE ControllerHandle,
215 IN EFI_HANDLE ChildHandle OPTIONAL,
216 IN EFI_DRIVER_HEALTH_REPAIR_NOTIFY RepairNotify OPTIONAL
217 );
218
219 ///
220 /// When installed, the Driver Health Protocol produces a collection of services
221 /// that allow the health status for a controller to be retrieved. If a controller
222 /// is not in a usable state, status messages may be reported to the user, repair
223 /// operations can be invoked, and the user may be asked to make software and/or
224 /// hardware configuration changes.
225 ///
226 struct _EFI_DRIVER_HEALTH_PROTOCOL {
227 EFI_DRIVER_HEALTH_GET_HEALTH_STATUS GetHealthStatus;
228 EFI_DRIVER_HEALTH_REPAIR Repair;
229 };
230
231 extern EFI_GUID gEfiDriverHealthProtocolGuid;
232
233 #endif
234
235
236
237