]>
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 | |
9095d37b LG |
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 | |
91750954 | 13 | Driver Health Protocol must be produced.\r |
9095d37b LG |
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 | |
23 | Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>\r | |
24 | Copyright (c) 2014, Hewlett-Packard Development Company, L.P.<BR>\r | |
25 | This program and the accompanying materials\r | |
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 | |
91750954 | 32 | \r |
33 | @par Revision Reference:\r | |
9095d37b | 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 | |
9095d37b | 45 | \r |
91750954 | 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 | |
9095d37b | 66 | \r |
ba0ef1e4 | 67 | ///\r |
9095d37b LG |
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 | |
ba0ef1e4 | 70 | /// The values 0x0000000000000001 to 0x0fffffffffffffff are reserved for allocation by the UEFI Specification.\r |
9095d37b | 71 | /// The values 0x1000000000000000 to 0x1fffffffffffffff are reserved for IHV-developed drivers.\r |
ba0ef1e4 SEHM |
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 | |
9095d37b | 81 | @param[in] Value A value between 0 and Limit that identifies the current\r |
91750954 | 82 | progress of the repair operation.\r |
9095d37b | 83 | \r |
5e33ee94 | 84 | @param[in] Limit The maximum value of Value for the current repair operation.\r |
9095d37b | 85 | For example, a driver that wants to specify progress in\r |
91750954 | 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 | |
9095d37b LG |
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 | |
9095d37b LG |
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 | |
5e33ee94 | 106 | that the driver is managing is returned.\r |
107 | \r | |
9095d37b LG |
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 | |
5e33ee94 | 115 | controller produced by the driver.\r |
116 | \r | |
9095d37b LG |
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 | |
134 | string in a specific language. Messages may be\r | |
135 | returned for any of the HealthStatus values except\r | |
136 | EfiDriverHealthStatusReconnectRequired and\r | |
5e33ee94 | 137 | EfiDriverHealthStatusRebootRequired.\r |
138 | \r | |
9095d37b LG |
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 | |
25a0aa5d | 141 | the controller specified by ControllerHandle and ChildHandle.\r |
142 | If this is NULL, then no HII form is available. An HII handle\r | |
9095d37b | 143 | will only be returned with a HealthStatus value of\r |
25a0aa5d | 144 | EfiDriverHealthStatusConfigurationRequired.\r |
91750954 | 145 | \r |
9095d37b LG |
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 | |
91750954 | 150 | MessageList, and FormList parameters are ignored.\r |
151 | \r | |
9095d37b LG |
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 | |
91750954 | 156 | FormList parameters are ignored.\r |
157 | \r | |
9095d37b LG |
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 | |
91750954 | 162 | FormList parameters are ignored.\r |
163 | \r | |
9095d37b LG |
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 | |
91750954 | 169 | may be optionally returned in FormList.\r |
170 | \r | |
9095d37b LG |
171 | @retval EFI_UNSUPPORTED ControllerHandle is not NULL, and the controller\r |
172 | specified by ControllerHandle and ChildHandle is not\r | |
91750954 | 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 |
9095d37b | 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 | |
9095d37b LG |
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 | |
9095d37b LG |
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 | |
59ec2b00 | 201 | drivers when an attempt is made to repair a bus controller.\r |
9095d37b | 202 | If will not be NULL when an attempt is made to repair a\r |
59ec2b00 | 203 | child controller produced by the driver.\r |
9095d37b LG |
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 | |
9095d37b LG |
209 | @retval EFI_SUCCESS An attempt to repair the controller specified by\r |
210 | ControllerHandle and ChildHandle was performed.\r | |
211 | The result of the repair operation can bet\r | |
91750954 | 212 | determined by calling GetHealthStatus().\r |
9095d37b LG |
213 | @retval EFI_UNSUPPORTED The driver specified by This is not currently\r |
214 | managing the controller specified by ControllerHandle\r | |
91750954 | 215 | and ChildHandle.\r |
9095d37b | 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 | |
9095d37b LG |
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 | |
91750954 | 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 |