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