EFI DEBUG SUPPORT PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol provides the services to allow the debug agent to register callback functions that are called either periodically or when specific processor exceptions occur.

Contents

GUID

#define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
  {0x2755590C,0x6F3C,0x42FA,0x9E,0xA4,0xA3,0xBA,0x54,0x3C,0xDA,0x25}

Protocol Interface Structure

typedef struct {
  EFI_INSTRUCTION_SET_ARCHITECTURE Isa;
  EFI_GET_MAXIMUM_PROCESSOR_INDEX  GetMaximumProcessorIndex;
  EFI_REGISTER_PERIODIC_CALLBACK   RegisterPeriodicCallback;
  EFI_REGISTER_EXCEPTION_CALLBACK  RegisterExceptionCallback;
  EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache;
} EFI_DEBUG_SUPPORT_PROTOCOL;

Members

Member Description
Isa Declares the processor architecture for this instance of the EFI Debug Support protocol.
GetMaximumProcessorIndex Returns the maximum processor index value that may be used with RegisterPeriodicCallback and RegisterExceptionCallback.
RegisterPeriodicCallback Registers a callback function that will be invoked periodically and asynchronously to the execution of EFI.
RegisterExceptionCallback Registers a callback function that will be called each time the specified processor exception occurs.
InvalidateInstructionCache Invalidate the instruction cache of the processor. This is required by processor architectures where instruction and data caches are not coherent when instructions in the code under debug has been modified by the debug agent.


Description

The UEFI Debug Support protocol provides the interfaces required to register debug agent callback functions and to manage the processor’s instruction stream as required. Registered callback functions are invoked in interrupt context when the specified event occurs. The driver that produces the EFI_DEBUG_SUPPORT_PROTOCOL is also responsible for saving the machine context prior to invoking a registered callback function and restoring it after the callback function returns prior to returning to the code under debug. If the debug agent has modified the context record, the modified context must be used in the restore operation.

Furthermore, if the debug agent modifies any of the code under debug (to set a software breakpoint for example), it must call the InvalidateInstructionCache() function for the region of memory that has been modified.

GetMaximumProcessorIndex()

Returns the maximum value that may be used for the ProcessorIndex parameter in RegisterPeriodicCallback and RegisterExceptionCallback.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX) (
  IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
  OUT UINTN *MaxProcessorIndex);

Parameters

Parameter Description
This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported processor index is returned.

Description
The GetMaximumProcessorIndex() function returns the maximum processor index in the output parameter MaxProcessorIndex. This value is the largest value that may be used in the ProcessorIndex parameter for both RegisterPeriodicCallback() and RegisterExceptionCallback(). All values between 0 and MaxProcessorIndex must be supported by RegisterPeriodicCallback() and RegisterExceptionCallback().

It is the responsibility of the caller to insure all parameters are correct. There is no provision for parameter checking by GetMaximumProcessorIndex(). The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned
EFI_SUCCESS The function completed successfully.

RegisterPeriodicCallback()

Registers a function to be called back periodically in interrupt context.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK) (
  IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
  IN UINTN ProcessorIndex,
  IN EFI_PERIODIC_CALLBACK PeriodicCallback);

Parameters

Parameter Description
This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
ProcessorIndex Specifies which processor the callback function applies to.
PeriodicCallback A pointer to a function of type EFI_PERIODIC_CALLBACK that is the main periodic entry point of the debug agent. It receives as a parameter a pointer to the full context of the interrupted execution thread.


Description
The RegisterPeriodicCallback() function registers and enables the on-target debug agent’s periodic entry point. To unregister and disable calling the debug agent’s periodic entry point, call RegisterPeriodicCallback() passing a NULL PeriodicCallback parameter.

The implementation must handle saving and restoring the processor context to/from the system context record around calls to the registered callback function.

If the interrupt is also used by the firmware for the EFI time base or some other use, two rules must be observed. First, the registered callback function must be called before any EFI processing takes place. Second, the Debug Support implementation must perform the necessary steps to pass control to the firmware’s corresponding interrupt handler in a transparent manner.

There is no quality of service requirement or specification regarding the frequency of calls to the registered PeriodicCallback function. This allows the implementation to mitigate a potential adverse impact to EFI timer based services due to the latency induced by the context save/restore and the associated callback function.

It is the responsibility of the caller to insure all parameters are correct. There is no provision for parameter checking by RegisterPeriodicCallback(). The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned
EFI_SUCCESS The function completed successfully. EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback function was previously registered. EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback function.

RegisterExceptionCallback()

Registers a function to be called when a given processor exception occurs.

Prototype

typedef
EFI_STATUS
(EFIAPI *REGISTER_EXCEPTION_CALLBACK) (
  IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
  IN UINTN ProcessorIndex,
  IN EFI_EXCEPTION_CALLBACK ExceptionCallback,
  IN EFI_EXCEPTION_TYPE ExceptionType);

Parameters

Parameter Description
This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
ProcessorIndex Specifies which processor the callback function applies to.
ExceptionCallback A pointer to a function of type EFI_EXCEPTION_CALLBACK that is called when the processor exception specified by ExceptionType occurs. Passing NULL unregisters any previously registered function associated with ExceptionType.
ExceptionType Specifies which processor exception to hook.


Description
The RegisterExceptionCallback() function registers and enables an exception callback function for the specified exception. The specified exception must be valid for the instruction set architecture. To unregister the callback function and stop servicing the exception, call RegisterExceptionCallback() passing a NULL ExceptionCallback parameter.

The implementation must handle saving and restoring the processor context to/from the system context record around calls to the registered callback function. No chaining of exception handlers is allowed.

It is the responsibility of the caller to insure all parameters are correct. There is no provision for parameter checking by RegisterExceptionCallback(). The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned
EFI_SUCCESS The function completed successfully. EFI_ALREADY_STARTED Non-NULL ExceptionCallback parameter when a callback function was previously registered. EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback function.

InvalidateInstructionCache()

Invalidates processor instruction cache for a memory range. Subsequent execution in this range causes a fresh memory fetch to retrieve code to be executed.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE) (
  IN EFI_DEBUG_SUPPORT_PROTOCOL *This,
  IN UINTN ProcessorIndex,
  IN VOID *Start,
  IN UINT64 Length);

Parameters

Parameter Description
This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
ProcessorIndex Specifies which processor’s instruction cache is to be invalidated.
Start Specifies the physical base of the memory range to be invalidated.
Length Specifies the minimum number of bytes in the processor’s instruction cache to invalidate.

Description
Typical operation of a debugger may require modifying the code image that is under debug. This can occur for many reasons, but is typically done to insert/remove software break instructions. Some processor architectures do not have coherent instruction and data caches so modifications to the code image require that the instruction cache be explicitly invalidated in that memory region.

The InvalidateInstructionCache() function abstracts this operation from the debug agent and provides a general purpose capability to invalidate the processor’s instruction cache. It is the responsibility of the caller to insure all parameters are correct. There is no provision for parameter checking by RegisterExceptionCallback(). The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned
EFI_SUCCESS Completed successfully.


Copyright (C) 2009 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2006-2008 Unified EFI, Inc. Used with permission.

Personal tools