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