14.1 Driver Health Protocol Implementation

The implementation of the Driver Health Protocol is typically found in the file DriverHealth.c. Appendix A contains a template for a DriverHealth.c file for a UEFI Driver. The list of tasks to implement the Driver Health Protocol feature follow:

• Add global variable for the EFI_DRIVER_HEALTH_PROTOCOL instance to DriverHealth.c.
• Add private fields, as required, to the design of the private context data structure that supports storing the current health status of a device and managing repair operations.
• Implement the GetHealthStatus() service of the Driver Health Protocol in DriverHealth.c.
• Implement the Repair() service of the Driver Health Protocol in DriverHealth.c.
• Install the Driver Health Protocol onto the same handle as that of the Driver Binding Protocol.
• If the UEFI Driver produces multiple Driver Binding Protocols, install the Driver Health Protocol on the same handles as those of the Driver Binding Protocol.
• If the UEFI Driver supports the unload feature, uninstall all the Driver Health Protocol instances in the Unload() function.

The example below shows the protocol interface structure for the Driver Health Protocol for reference and is composed of two services; GetHealthStatus() and Repair().

Example 150-Driver Health Protocol

typedef struct _EFI_DRIVER_HEALTH_PROTOCOL EFI_DRIVER_HEALTH_PROTOCOL;

///
/// When installed, the Driver Health Protocol produces a collection of services
/// that allow the health status for a controller to be retrieved. If a controller
/// is not in a usable state, status messages may be reported to the user, repair
/// operations can be invoked, and the user may be asked to make software and/or
/// hardware configuration changes.
///
struct _EFI_DRIVER_HEALTH_PROTOCOL {
  EFI_DRIVER_HEALTH_GET_HEALTH_STATUS GetHealthStatus;
  EFI_DRIVER_HEALTH_REPAIR Repair;
};

This example declares a global variable called gAbcDriverHealth with the services AbcGetHealthStatus() and AbcRepair(). The UEFI Boot Service InstallMultipleProtocolInterfaces() is used to install the Driver Health Protocol instance gAbcDriverHealth onto the same ImageHandle as that of the Driver Binding Protocol instance gAbcDriverBinding

Example 151-Install Driver Health Protocol

#include <Uefi.h>
#include <Protocol/DriverBinding.h>
#include <Protocol/DriverHealth.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiLib.h>
#include <Library/DebugLib.h>

#define ABC_VERSION 0x10

EFI_DRIVER_BINDING_PROTOCOL gAbcDriverBinding = {
  AbcSupported,
  AbcStart,
  AbcStop,
  ABC_VERSION,
  NULL,
  NULL
};

GLOBAL_REMOVE_IF_UNREFERENCED
EFI_DRIVER_HEALTH_PROTOCOL gAbcDriverHealth = {
  AbcGetHealthStatus,
  AbcRepair
};

EFI_STATUS
EFIAPI
AbcDriverEntryPoint (
  IN EFI_HANDLE                  ImageHandle,
  IN EFI_SYSTEM_TABLE            *SystemTable
  )
{
  EFI_STATUS  Status;
  //
  // Install driver model protocol(s) on ImageHandle
  //
  Status = EfiLibInstallDriverBinding (
             ImageHandle,        // ImageHandle
             SystemTable,        // SystemTable
             &gAbcDriverBinding, // DriverBinding
             ImageHandle         // DriverBindingHandle
             );
  ASSERT_EFI_ERROR (Status);

  //
  // Install Driver Family Override Protocol onto ImageHandle
  //
  Status = gBS->InstallMultipleProtocolInterfaces (
                  &ImageHandle,
                  &gEfiDriverHealthProtocolGuid,
                  &gAbcDriverHealth,
                  NULL
                  );
  ASSERT_EFI_ERROR (Status);

  return Status;
}