]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/DriverHealth.h
MdePkg: Replace BSD License with BSD+Patent License
[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
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 40typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;\r
41\r
42///\r
43/// EFI_DRIVER_HEALTH_HEALTH_STATUS\r
44///\r
45typedef 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
57typedef 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
82typedef\r
83EFI_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
175typedef\r
176EFI_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
214typedef\r
215EFI_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
230struct _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
235extern EFI_GUID gEfiDriverHealthProtocolGuid;\r
236\r
237#endif\r
238\r
239\r
240\r
241\r