14. DXE Runtime Protocols

14.1. Introduction

In addition to the architectural protocols listed earlier, there is also a runtime protocol. Specifically, the ability to report status codes is runtime-callable service that allows for emitting status and progress information. It was formerly part of the 0.9 DXE-CIS runtime table, but in consideration of UEFI 2.0 compatibility, this capability has become a separate runtime protocol.

14.2. Status Code Runtime Protocol

14.2.1. EFI_STATUS_CODE_PROTOCOL

Summary

Provides the service required to report a status code to the platform firmware. This protocol must be produced by a runtime DXE driver.

GUID

#define EFI_STATUS_CODE_RUNTIME_PROTOCOL_GUID \
  { 0xd2b2b828, 0x826, 0x48a7, 0xb3, 0xdf, 0x98, 0x3c, \
  0x0, 0x60, 0x24, 0xf0}

Protocol Interface Structure

typedef struct _EFI_STATUS_CODE_PROTOCOL {
  EFI_REPORT_STATUS_CODE          ReportStatusCode;
} EFI_STATUS_CODE_PROTOCOL;

Parameters

ReportStatusCode: Emit a status code.

Description

The DXE driver that produces this protocol must be a runtime driver. This driver is responsible for providing the ReportStatusCode() service with the EFI_STATUS_CODE_PROTOCOL .

EFI_STATUS_CODE_PROTOCOL.ReportStatusCode()

Summary

Provides an interface that a software module can call to report a status code.

Prototype

EFI_STATUS
(EFIAPI *EFI_REPORT_STATUS_CODE) (
  IN EFI_STATUS_CODE_TYPE             Type,
  IN EFI_STATUS_CODE_VALUE            Value,
  IN UINT32                           Instance,
  IN CONST EFI_GUID                   *CallerId OPTIONAL,
  IN CONST EFI_STATUS_CODE_DATA       *Data     OPTIONAL
  );

Parameters

Type: Indicates the type of status code being reported. Type EFI_STATUS_CODE_TYPE is defined in “Related Definitions” below.

Value: Describes the current status of a hardware or software entity. This included information about the class and subclass that is used to classify the entity as well as an operation. For progress codes, the operation is the current activity. For error codes, it is the exception. For debug codes, it is not defined at this time. Type EFI_STATUS_CODE_VALUE is defined in “Related Definitions” below.

Instance: The enumeration of a hardware or software entity within the system. A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them. An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant. Valid instance numbers start with 1.

CallerId: This optional parameter may be used to identify the caller. This parameter allows the status code driver to apply different rules to different callers. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Data: This optional parameter may be used to pass additional data. Type EFI_STATUS_CODE_DATA is defined in volume 3 of this specification. The contents of this data type may have additional GUID-specific data.

Description

Various software modules including drivers can call this function to report a status code. No disposition of the status code is guaranteed. The ReportStatusCode() function may choose to log the status code, but this action is not required.

It is possible that this function may get called at EFI_TPL_LEVEL_HIGH . Therefore, this function cannot call any protocol interface functions or services (including memory allocation) that are not guaranteed to work at EFI_TPL_LEVEL_HIGH . It should be noted that SignalEvent() could be called by this function because it works at any TPL including EFI_TPL_LEVEL_HIGH. It is possible for an implementation to use events to log the status codes when the TPL level is reduced.

ReportStatusCode() function can perform other implementation specific work, but that is not specified in the architecture document.

In case of an error, the caller can specify the severity. In most cases, the entity that reports the error may not have a platform wide view and may not be able to accurately assess the impact of the error condition. The DXE driver that produces the Status Code Protocol, EFI_STATUS_CODE_PROTOCOL , is responsible for assessing the true severity level based on the reported severity and other information. This DXE driver may perform platform specific actions based on the type and severity of the status code being reported.

If Data is present, the Status Code Protocol driver treats it as read only data. The Status Code Protocol driver must copy Data to a local buffer in an atomic operation before performing any other actions. This is necessary to make this function re-entrant. The size of the local buffer may be limited. As a result, some of the Data can be lost. The size of the local buffer should at least be 256 bytes in size. Larger buffers will reduce the probability of losing part of the Data . Note than multiple status codes may be reported at elevated TPL levels before the TPL level is reduced. Allocating multiple local buffers may reduce the probability losing status codes at elevated TPL levels. If all of the local buffers are consumed, then this service may not be able to perform the platform specific action required by the status code being reported. As a result, if all the local buffers are consumed, the behavior of this service is undefined.

If the CallerId parameter is not NULL , then it is required to point to a constant GUID. In other words, the caller may not reuse or release the buffer pointed to by CallerId .

//
// Status Code Type Definition
//
typedef UINT32 EFI_STATUS_CODE_TYPE;

//
// A Status Code Type is made up of the code type and severity
// All values masked by EFI_STATUS_CODE_RESERVED_MASK are
// reserved for use by this specification.
//
#define EFI_STATUS_CODE_TYPE_MASK        0x000000FF
#define EFI_STATUS_CODE_SEVERITY_MASK    0xFF000000
#define EFI_STATUS_CODE_RESERVED_MASK    0x00FFFF00

//
// Definition of code types, all other values masked by
// EFI_STATUS_CODE_TYPE_MASK are reserved for use by
// this specification.
//
#define EFI_PROGRESS_CODE                0x00000001
#define EFI_ERROR_CODE                   0x00000002
#define EFI_DEBUG_CODE                   0x00000003

//
// Definitions of severities, all other values masked by
// EFI_STATUS_CODE_SEVERITY_MASK are reserved for use by
// this specification.
// Uncontained errors are major errors that could not contained
// to the specific component that is reporting the error
// For example, if a memory error was not detected early enough,
// the bad data could be consumed by other drivers.
//
#define EFI_ERROR_MINOR                  0x40000000
#define EFI_ERROR_MAJOR                  0x80000000
#define EFI_ERROR_UNRECOVERED            0x90000000
#define EFI_ERROR_UNCONTAINED            0xa0000000

//
// Status Code Value Definition
//
typedef UINT32 EFI_STATUS_CODE_VALUE;

//
// A Status Code Value is made up of the class, subclass, and
// an operation.
//
#define EFI_STATUS_CODE_CLASS_MASK       0xFF000000
#define EFI_STATUS_CODE_SUBCLASS_MASK    0x00FF0000
#define EFI_STATUS_CODE_OPERATION_MASK   0x0000FFFF

Parameters

HeaderSize: The size of the structure. This is specified to enable future expansion.

Size: The size of the data in bytes. This does not include the size of the header structure.

Type: The GUID defining the type of the data.

Status Codes Returned

Table 14.1 Status Codes Returned
EFI_SUCCESS	The function completed successfully.
EFI_DEVICE_ERROR	The function should not be completed due to a device error.