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