7. Report Status Code Routers¶

7.1. Overview¶

This section provides the code definitions for the PPI and Protocols used in a Report Status Code Router. These interfaces allow multiple platform dependent drivers for displaying status code information to coexist without prior knowledge of one another.

_images/V3_Report_Status_Code_Router-2.png — Fig. 7.4 **Status Code Services**¶

There is a generic status code driver in each phase. In each case the driver consumes the Report Status Code Protocol and produces the Report Status Code Handler PPI or Protocol. Each consumer of the Report Status Code Handler PPI or Protocol will register a callback to receive notification of new Status Codes from the Generic Status Code Driver.

7.2. Code Definitions¶

7.2.1. Report Status Code Handler Protocol¶

7.2.1.1. EFI_RSC_HANDLER_PROTOCOL¶

Summary

Provide registering and unregistering services to status code consumers while in DXE.

GUID

#define EFI_RSC_HANDLER_PROTOCOL_GUID \
{ \
  0x86212936, 0xe76, 0x41c8, \
  0xa0, 0x3a, 0x2a, 0xf2, 0xfc, 0x1c, 0x39, 0xe2 \
}

Protocol Interface Structure

typedef struct {
  EFI_RSC_HANDLER_REGISTER      Register;
  EFI_RSC_HANDLER_UNREGISTER    Unregister;
} EFI_RSC_HANDLER_PROTOCOL;

Members

Register: Register the callback for notification of status code messages.

Unregister: Unregister the callback.

Description

Once registered, status code messages will be forwarded to the callback. The callback must be unregistered before it is deallocated.

typedef
EFI_STATUS
(EFIAPI *EFI_RSC_HANDLER_CALLBACK) (
  IN EFI_STATUS_CODE_TYPE     CodeType,
  IN EFI_STATUS_CODE_VALUE    Value,
  IN UINT32                   Instance,
  IN EFI_GUID                 *CallerId,
  IN EFI_STATUS_CODE_DATA     *Data
  );

For parameter descriptions, function descriptions and status code values, see ReportStatusCode() in the PI Specification,Volume 2, section 14.2.

7.2.1.2. EFI_RSC_HANDLER_PROTOCOL.Register()¶

Summary

Register the callback function for ReportStatusCode() notification.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_RSC_HANDLER_REGISTER) (
  IN EFI_RSC_HANDLER_CALLBACK   Callback,
  IN EFI_TPL                    Tpl
  );

Parameters

Callback: A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is called when a call to ReportStatusCode() occurs.

Tpl: TPL at which callback can be safely invoked.

Description

When this function is called the function pointer is added to an internal list and any future calls to ReportStatusCode() will be forwarded to the Callback function. During the boot-services, this is the callback for which this service can be invoked. The report status code router will create an event such that the callback function is only invoked at the TPL for which it was registered. The entity that registers for the callback should also register for an event upon generation of exit boot services and invoke the unregister service.

If the handler does not have a TPL dependency, it should register for a callback at TPL high. The router infrastructure will support making callbacks at runtime, but the caller for runtime invocation must meet the following criteria:

must be a runtime driver type so that itsmemory is not reclaimed
not unregister at exit boot services so that the router will still have its callback address
the caller must be self-contained (eg. Not call out into any boot-service interfaces) and be runtime safe, in general.

Status Codes Returned

Table 7.21 Status Codes Returned¶
EFI_SUCCESS	Function was successfully registered.
EFI_INVALID_PARAMETER	The callback function was `NULL`.
EFI_OUT_OF_RESOURCES	The internal buffer ran out of space. No more functions can be registered.
EFI_ALREADY_STARTED	The function was already registered. It can’t be registered again.

7.2.1.3. EFI_RSC_HANDLER_PROTOCOL.Unregister()¶

Summary

Remove a previously registered callback function from the notification list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_RSC_HANDLER_UNREGISTER) (
  IN EFI_RSC_HANDLER_CALLBACK    Callback
  );

Parameters

Callback: A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is to be unregistered.

Description

A callback function must be unregistered before it is deallocated. It is important that any registered callbacks that are not runtime complaint be unregistered when ExitBootServices() is called.

Status Codes Returned

Table 7.22 Status Codes Returned¶
EFI_SUCCESS	The function was successfully unregistered.
EFI_INVALID_PARAMETER	The callback function was `NULL`
EFI_NOT_FOUND	The callback function was not found to be unregistered.

7.2.2. Report Status Code Handler PPI¶

7.2.2.1. EFI_PEI_RSC_HANDLER_PPI¶

Summary

Provide registering and unregistering services to status code consumers.

GUID

#define EFI_PEI_RSC_HANDLER_PPI_GUID \
  { \
    0x65d394, 0x9951, 0x4144, \
    0x82, 0xa3, 0xa, 0xfc, 0x85, 0x79, 0xc2, 0x51 \
  }

PPI Interface Structure

typedef struct _EFI_PEI_RSC_HANDLER_PPI {
  EFI_PEI_RSC_HANDLER_REGISTER        Register;
  EFI_PEI_RSC_HANDLER_UNREGISTER      Unregister;
} EFI_PEI_RSC_HANDLER_PPI;

Members

Register: Register the callback for notification of status code messages.

Unregister: Unregister the callback.

Description

Once registered, status code messages will be forwarded to the callback.

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_RSC_HANDLER_CALLBACK) (
  IN CONST EFI_PEI_SERVICES         **PeiServices,
  IN       EFI_STATUS_CODE_TYPE     Type,
  IN       EFI_STATUS_CODE_VALUE    Value,
  IN       UINT32                   Instance,
  IN CONST EFI_GUID                 *CallerId,
  IN CONST EFI_STATUS_CODE_DATA     *Data
);

For parameter descriptions, function descriptions and status code values, see ReportStatusCode() in the PI specification Volume 1, section 4.5 .

7.2.2.2. EFI_PEI_RSC_HANDLER_PPI.Register()¶

Summary

Register the callback function for ReportStatusCode() notification.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_RSC_HANDLER_REGISTER) (
  IN EFI_PEI_RSC_HANDLER_CALLBACK   Callback
  );

Parameters

Callback: A pointer to a function of type EFI_PEI_RSC_HANDLER_CALLBACK that is called when a call to ReportStatusCode() occurs.

Description

When this function is called the function pointer is added to an internal list and any future calls to ReportStatusCode() will be forwarded to the Callback function.

Status Codes Returned

Table 7.23 Status Codes Returned¶
EFI_SUCCESS	Function was successfully registered.
EFI_INVALID_PARAMETER	The callback function was `NULL`.
EFI_OUT_OF_RESOURCES	The internal buffer ran out of space. No more functions can be registered.
EFI_ALREADY_STARTED	The function was already registered. It can t be registered again.

7.2.2.3. EFI_PEI_RSC_HANDLER_PPI.Unregister()¶

Summary

Remove a previously registered callback function from the notification list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_RSC_HANDLER_UNREGISTER) (
  IN EFI_PEI_RSC_HANDLER_CALLBACK   ``Callback``
  );

Parameters

Callback: A pointer to a function of type EFI_PEI_RSC_HANDLER_CALLBACK that is to be unregistered.

Description

ReportStatusCode() messages will no longer be forwarded to the Callback function.

Status Codes Returned

Table 7.24 Status Codes Returned¶
EFI_SUCCESS	The function was successfully unregistered.
EFI_INVALID_PARAMETER	The callback function was `NULL`.
EFI_NOT_FOUND	The callback function was not found to be unregistered.

7.2.3. SMM Report Status Code Handler Protocol¶

7.2.3.1. EFI_SMM_RSC_HANDLER_PROTOCOL¶

Summary

Provide registering and unregistering services to status code consumers while in DXE SMM.

GUID

#define EFI_SMM_RSC_HANDLER_PROTOCOL_GUID \
  { \
0x2ff29fa7, 0x5e80, 0x4ed9, 0xb3, 0x80, 0x1, 0x7d, 0x3c,
0x55, 0x4f, 0xf4
  }

Protocol Interface Structure

typedef struct _EFI_SMM_RSC_HANDLER_PROTOCOL {
  EFI_SMM_RSC_HANDLER_REGISTER        Register;
  SMM_RSC_HANDLER_UNREGISTER          Unregister;
} EFI_SMM_RSC_HANDLER_PROTOCOL;

Members

Register: Register the callback for notification of status code messages.

Unregister: Unregister the callback.

Description

Once registered, status code messages will be forwarded to the callback. The callback must be unregistered before it is deallocated.

typedef
EFI_STATUS
(EFIAPI *EFI_SMM_RSC_HANDLER_CALLBACK) (
  IN EFI_STATUS_CODE_TYPE     CodeType,
  IN EFI_STATUS_CODE_VALUE    Value,
  IN UINT32                   Instance,
  IN EFI_GUID                 *CallerId,
  IN EFI_STATUS_CODE_DATA     *Data
  );

For parameter descriptions, function descriptions and status code values, see ReportStatusCode() in the PI specification Volume 2, section 14.2.

7.2.3.2. EFI_SMM_RSC_HANDLER_PROTOCOL.Register()¶

Summary

Register the callback function for ReportStatusCode() notification.

Prototype

typedef
EFI_STATUS
  (EFIAPI *EFI_SMM_RSC_HANDLER_REGISTER) (
  IN EFI_SMM_RSC_HANDLER_CALLBACK        Callback
  );

Parameters

Callback: A pointer to a function of type EFI_RSC_HANDLER_CALLBACK that is called when a call to ReportStatusCode() occurs.

Description

When this function is called the function pointer is added to an internal list and any future calls to ReportStatusCode() will be forwarded to the Callback function.

Status Codes Returned

Table 7.25 Status Codes Returned¶
EFI_SUCCESS	Function was successfully registered.
EFI_INVALID_PARAMETER	The callback function was `NULL`.
EFI_OUT_OF_RESOURCES	The internal buffer ran out of space No more functions can be registered.
EFI_ALREADY_STARTED	The function was already registered It can t be registered again.

7.2.3.3. EFI_SMM_RSC_HANDLER_PROTOCOL.Unregister()¶

Summary

Remove a previously registered callback function from the notification list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SMM_RSC_HANDLER_UNREGISTER) (
  IN EFI_SMM_RSC_HANDLER_CALLBACK        Callback
  );

Parameters

Callback: A pointer to a function of type EFI_SMM_RSC_HANDLER_CALLBACK that is to be unregistered.

Description

A callback function must be unregistered before it is deallocated. It is important that any registered callbacks that are not runtime complaint be unregistered when ExitBootServices() is called.

Status Codes Returned

Table 7.26 Status Codes Returned¶
EFI_SUCCESS	The function was successfully unregistered.
EFI_INVALID_PARAMETER	The callback function was `NULL`.
EFI_NOT_FOUND	The callback function was not found to be unregistered.