EFI DRIVER DIAGNOSTICS2 PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Used to perform diagnostics on a controller that a UEFI driver is managing.

Contents

GUID

#define EFI_DRIVER_DIAGNOSTICS2_PROTOCOL_GUID \
  {0x4d330321,0x025f,0x4aac,0x90,0xd8,0x5e,0xd9,0x00,0x17,0x3b,0x63}

Protocol Interface Structure

#include EFI_PROTOCOL_PRODUCER(DriverDiagnostics2)

extern EFI_GUID gEfiDriverDiagnostics2ProtocolGuid;
typedef struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL {
  EFI_DRIVER_DIAGNOSTICS_RUN_DIAGNOSTICS RunDiagnostics;
  CHAR8                                  *SupportedLanguages;
} EFI_DRIVER_DIAGNOSTICS2_PROTOCOL;

Members

Member Description
RunDiagnostics Runs diagnostics on a controller.
SupportedLanguages A Null-terminated ASCII string that contains one or more supported language codes. This is the list of language codes that this protocol supports. The number of languages supported by a driver is up to the driver writer. SupportedLanguages is specified in RFC 4646 format. See Appendix M for the format of language codes and language code arrays.

Description

The EFI_DRIVER_DIAGNOSTICS2_PROTOCOL is used by a platform management utility to allow the user to run driver specific diagnostics on a controller. This protocol is optionally attached to the image handle of driver in the driver's entry point. The platform management utility can collect all the EFI_DRIVER_DIAGNOSTICS2_PROTOCOL instances present in the system, and present the user with a menu of the controllers that have diagnostic capabilities. This platform management utility is invoked through a platform component such as the Boot Manager.

RunDiagnostics()

Runs diagnostics on a controller.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DRIVER_DIAGNOSTICS_RUN_DIAGNOSTICS) (
  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
  );

Parameters

Parameter Description
This A pointer to the EFI_DRIVER_DIAGNOSTICS2_PROTOCOL instance.
ControllerHandle The handle of the controller to run diagnostics on.
ChildHandle The handle of the child controller to run diagnostics on. This is an optional parameter that may be NULL. It will be NULL for device drivers. It will also be NULL for a bus drivers that attempt to run diagnostics on the bus controller. It will not be NULL for a bus driver that attempts to run diagnostics on one of its child controllers.
DiagnosticType Indicates type of diagnostics to perform on the controller specified by ControllerHandle and ChildHandle.
Language A pointer to a Null-terminated ASCII string array indicating the language. This is the language in which the optional error message should be returned in Buffer, and it must match one of the languages specified in SupportedLanguages. The number of languages supported by a driver is up to the driver writer. Language is specified in RFC 4646 language code format.
ErrorType A GUID that defines the format of the data returned in Buffer.
BufferSize The size, in bytes, of the data returned in Buffer.
Buffer A buffer that contains a Null-terminated Unicode string plus some additional data whose format is defined by ErrorType. Buffer is allocated by this function with AllocatePool(), and it is the caller’s responsibility to free it with a call to FreePool().

Description
This function runs diagnostics on the controller specified by ControllerHandle and ChildHandle. DiagnoticType specifies the type of diagnostics to perform on the controller specified by ControllerHandle and ChildHandle. If the driver specified by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned. If the controller specified by ControllerHandle and ChildHandle is not supported by the driver specified by This, then EFI_UNSUPPORTED is returned. If the diagnostics type specified by DiagnosticType is not supported by this driver, then EFI_UNSUPPORTED is returned. If there are not enough resources available to complete the diagnostic, then EFI_OUT_OF_RESOURCES is returned. If the controller specified by ControllerHandle and ChildHandle passes the diagnostic, then EFI_SUCCESS is returned. Otherwise, EFI_DEVICE_ERROR is returned.

If the language specified by Language is supported by this driver, then status information is returned in ErrorType, BufferSize, and Buffer. Buffer contains a Null-terminated Unicode string followed by additional data whose format is defined by ErrorType. BufferSize is the size of Buffer is bytes, and it is the caller's responsibility to call FreePool() on Buffer when the caller is done with the return data. If there are not enough resources available to return the status information, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The controller specified by ControllerHandle and ChildHandle passed the diagnostic.
EFI_ACCESS_DENIED The request for initiating diagnostics was unable to be completed due to some underlying hardware or software state.
EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER The driver specified by This is not a device driver, and ChildHandle is not NULL, and ChildHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Language is NULL.
EFI_INVALID_PARAMETER ErrorType is NULL.
EFI_INVALID_PARAMETER BufferSize is NULL.
EFI_INVALID_PARAMETER Buffer is NULL.
EFI_UNSUPPORTED The driver specified by This does not support running diagnostics for the controller specified by ControllerHandle and ChildHandle.
EFI_UNSUPPORTED The driver specified by This does not support the type of diagnostic specified by DiagnosticType.
EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language.
EFI_OUT_OF_RESOURCES There are not enough resources available to complete the diagnostics.
EFI_OUT_OF_RESOURCES There are not enough resources available to return the status information in ErrorType, BufferSize, and Buffer.
EFI_DEVICE_ERROR The controller specified by ControllerHandle and ChildHandle did not pass the diagnostic.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools