Skip to content

Latest commit

 

History

History
102 lines (82 loc) · 6.53 KB

README.md

File metadata and controls

102 lines (82 loc) · 6.53 KB
Raw

14.2 GetHealthStatus() Implementations

The GetHealthStatus() service retrieves the health status for a controller a driver is managing or a child the driver has produced. This service is not allowed to use any of the console I/O related protocols. Instead, the health status information is returned to the caller. The caller may choose to log or display the health status information. The example below shows an empty implementation of the GetHealthStatus() service for the Driver Health Protocol.

Example 152-GetHealthStatus() Function of the Driver Health Protocol
#include <Uefi.h>
#include <Protocol/DriverHealth.h>

EFI_STATUS
EFIAPI
AbcGetHealthStatus (
  IN  EFI_DRIVER_HEALTH_PROTOCOL     *This,
  IN  EFI_HANDLE                     ControllerHandle,  OPTIONAL
  IN  EFI_HANDLE                     ChildHandle,       OPTIONAL
  OUT EFI_DRIVER_HEALTH_STATUS       *HealthStatus,
  OUT EFI_DRIVER_HEALTH_HII_MESSAGE  **MessageList,     OPTIONAL
  OUT EFI_HII_HANDLE                 *FormHiiHandle     OPTIONAL
  )
{
}

HealthStatus is the return parameter reporting the status for the controller specified by ControllerHandle and ChildHandle. Descriptions of the various health status values returned in HealthStatus follow.

Table 23-Health Status Values
Health Status Name Definition
EfiDriverHealthStatu sHealthy The controller is in a healthy state.
EfiDriverHealthStatu sRepairRequired The controller requires a repair operation taking an extended period of time to perform. The UEFI Boot Manager is required to call the Repair() function when this state is detected.
EfiDriverHealthStatu sConfigurationRequired The controller requires the user to make software or hardware configuration changes in order to put the controller into a healthy state. The set of software configuration changes are specified by the FormHiiHandle parameter. The EFI Boot Manager may call the EFI_FORM_BROWSER2_PROTOCOL.SendForm() function to display configuration information and allow the user to make the required configuration changes. The HII form is the first enabled form in the form set class EFI_HII_DRIVER_HEALTH_FORMSET_GUID, which is installed on the returned HII handle FormHiiHandle.
EfiDriverHealthStatusFailed The controller is in a failed state and there are no actions that can place the controller into a healthy state. This controller, nor no any boot devices behind it, cannot be used as a boot device.
EfiDriverHealthStatu sReconnectRequired A hardware and/or software configuration change was performed by the user and the controller needs to be reconnected before the controller can be placed in a healthy state. The UEFI Boot Manager is required to call the UEFI Boot Service DisconnectController(), followed by the UEFI Boot Service ConnectController(), to reconnect the controller.
EfiDriverHealthStatu sRebootRequired A hardware and/or software configuration change was performed by the user and the controller requires the entire platform to be rebooted before the controller can be placed in a healthy state. The UEFI Boot Manager should complete the configuration and repair operations on all the controllers that are not in a healthy state before rebooting the system.

Depending on the specific health status value returned, additional information may be returned in MessageList and FormHiiHandle as described in the table above. The health status for devices is typically stored in the private context data structure. The Driver Binding Protocol Start() function for a UEFI Driver is usually where the health status for a device is initially detected and the results of that detection logic are stored in the private context data structure. As the UEFI Boot Manager performs repair or configuration actions, the health status of a controller changes. Each time GetHealthStatus() is called, the health status of the controller must be evaluated. The EFI Driver Health Protocol section of the UEFI Specification defines the legal state transitions for health status values as shown in the following figure.

Figure 18-Driver Health Status State Diagram

Driver Health Status State

The Driver Health Protocol is only available for devices a driver is currently managing. Because UEFI supports connecting the minimum number of drivers and devices required to establish console and gain access to the boot device, there may be many unconnected devices that support The Driver Health Protocol. As a result, when the user wishes to enter a platform configuration mode, the UEFI Boot Manager must connect all drivers to all devices so the UEFI Boot Manager can evaluate the health status of all the devices in the platform supporting the Driver Health Protocol.