]>
Commit | Line | Data |
---|---|---|
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 | |
46 | typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;\r | |
47 | \r | |
48 | ///\r | |
49 | /// EFI_DRIVER_HEALTH_HEALTH_STATUS\r | |
50 | ///\r | |
51 | typedef 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 | |
63 | typedef 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 |
88 | typedef\r | |
89 | EFI_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 | |
181 | typedef\r | |
182 | EFI_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 | |
220 | typedef\r | |
221 | EFI_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 | |
236 | struct _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 | |
241 | extern EFI_GUID gEfiDriverHealthProtocolGuid;\r | |
242 | \r | |
243 | #endif\r | |
244 | \r | |
245 | \r | |
246 | \r | |
247 | \r |