13.2 RunDiagnostics() Implementations

The RunDiagnostics() service runs diagnostics on the controller a driver is managing or a child the driver has produced. This service is not allowed to use any of the consoleI/O-related protocols. Instead, the results of the diagnostics are returned to the caller in a buffer. The caller may choose to log the results or display them. The example below shows an empty implementation of the RunDiagnostics() service for the Driver Diagnostics 2 Protocol. The recommended implementation style shown allows the same RunDiagnostics() service implementation to be shared between the Driver Diagnostics Protocol and the Driver Diagnostics 2 Protocol.

Example 147-RunDiagnostics() Service

#include <Uefi.h>
#include <Protocol/DriverDiagnostics2.h>

EFI_STATUS
EFIAPI
AbcRunDiagnostics (
  IN  EFI_DRIVER_DIAGNOSTICS2_PROTOCOL  *This,
  IN  EFI_HANDLE                        ControllerHandle,
  IN  EFI_HANDLE                        ChildHandle,  OPTIONAL
  IN  EFI_DRIVER_DIAGNOSTIC_TYPE        DiagnosticType,
  IN  CHAR8                             *Language,
  OUT EFI_GUID                          **ErrorType,
  OUT UINTN                             *BufferSize,
  OUT CHAR16                            **Buffer
  )
{
}

The DiagnosticType parameter tells the driver the type of diagnostics to perform. Standard diagnostics must be implemented and test basic functionality. They should complete in less than 30 seconds. Extended diagnostics are recommended and may take more than 30 seconds to execute. Manufacturing diagnostics are intended to be used in manufacturing and test environments.

ErrorType, BufferSize, and Buffer are the return parameters that report the results of the diagnostic. Buffer begins with a NULL-terminated Unicode string so the caller of the RunDiagnostics() service can display a human-readable diagnostic result. ErrorType is a GUID that defines the format of the data buffer following the NULL-terminated Unicode string. BufferSize is the size of Buffer that includes the NULL-terminated Unicode string and the GUID-specific data buffer. The implementation of RunDiagnostics() must allocate Buffer using the service AllocatePool(), and it is the caller's responsibility to free this buffer with FreePool().

The Driver Diagnostics Protocols are available only for devices a driver is currently managing. Because UEFI supports connecting the minimum number of drivers and devices that are required to establish console and gain access to the boot device, there may be many unconnected devices that support diagnostics. 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 that the user can be shown all devices supporting diagnostics.