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