EFI DEBUGPORT PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol provides the communication link between the debug agent and the remote host.

Contents

GUID

#define EFI_DEBUGPORT_PROTOCOL_GUID \
  {0xEBA4E8D2,0x3858,0x41EC,0xA2,0x81,0x26,0x47,0xBA,0x96,
  0x60,0xD0}

Protocol Interface Structure

typedef struct {
  EFI_DEBUGPORT_RESET Reset;
  EFI_DEBUGPORT_WRITE Write;
  EFI_DEBUGPORT_READ  Read;
  EFI_DEBUGPORT_POLL  Poll;
} EFI_DEBUGPORT_PROTOCOL;

Members

Members Description
Reset Resets the debugport hardware.
Write Send a buffer of characters to the debug port device.
Read Receive a buffer of characters from the debug port device.
Poll Determine if there is any data available to be read from the debugport device.

Description

This protocol is used for byte stream communication with a debugport device. The debug port can be a standard UART Serial port, a USB-based character device, or potentially any character-based I/O device.

The attributes for all UART-style debugport device interfaces are defined in the DEBUGPORT variable.

Historically, remote debugging has typically been done using a standard UART serial port to connect the host and target. This is obviously not possible in a legacy reduced system that does not have a UART. The Debugport protocol solves this problem by providing an abstraction that can support many different types of debugport hardware. The debug agent should use this abstraction to communicate with the host.

The interface is minimal with only reset, read, write, and poll abstractions. Since these functions are called in interrupt context, none of them may call any EFI services or other protocol interfaces. Debug port selection and configuration is handled by setting defaults via an environment variable which contains a full device path to the debug port. This environment variable is used during the debug port driver’s initialization to configure the debugport correctly. The variable contains a full device path to the debugport, with the last node (prior to the terminal node) being a debug port messaging node.

The driver must also produce an instance of the EFI Device Path protocol to indicate what hardware is being used for the debugport. This may be used by the OS to maintain the debug port across a call to ExitBootServices().

Reset()

Resets the debugport.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DEBUGPORT_RESET) (
  IN EFI_DEBUGPORT_PROTOCOL *This
  );

Parameters

Parameter Description
This A pointer to the EFI_DEBUGPORT_PROTOCOL instance.

Description
The Reset() function resets the debug port device.

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

Status Codes Returned

Status Code Description
EFI_SUCCESS The debug port device was reset and is in usable state.
EFI_DEVICE_ERROR The debug port device could not be reset and is unusable.

Write()

Writes data to the debugport.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DEBUGPORT_WRITE) (
  IN     EFI_DEBUGPORT_PROTOCOL *This,
  IN     UINT32                 Timeout,
  IN OUT UINTN                  *BufferSize,
  IN     VOID                   *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
Timeout The number of microseconds to wait before timing out a write operation.
BufferSize On input, the requested number of bytes of data to write. On output, the number of bytes of data actually written.
Buffer A pointer to a buffer containing the data to write.

Description
The Write() function writes the specified number of bytes to a debugport device. If a timeout error occurs while data is being sent to the debugport, transmission of this buffer will terminate, and EFI_TIMEOUT will be returned. In all cases the number of bytes actually written to the debug port device is returned in BufferSize.

It is the responsibility of the caller to insure all parameters are valid. There is no provision for parameter checking by Write().

The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was written.
EFI_DEVICE_ERROR The device reported an error.
EFI_TIMEOUT The data write was stopped due to a timeout.

Read()

Reads data from the debugport.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DEBUGPORT_READ) (
  IN     EFI_DEBUGPORT_PROTOCOL *This,
  IN     UINT32                 Timeout,
  IN OUT UINTN                  *BufferSize,
  OUT    VOID                   *Buffer
  );

Parameters

Parameter Description
This A pointer to the EFI_DEBUGPORT_PROTOCOL instance.
Timeout The number of microseconds to wait before timing out a read operation.
BufferSize A pointer to an integer which, on input contains the requested number of bytes of data to read, and on output contains the actual

number of bytes of data read and returned in Buffer.

Buffer A pointer to a buffer into which the data read will be saved.

Description
The Read() function reads a specified number of bytes from a debug port. If a timeout error or an overrun error is detected while data is being read from the debugport, then no more characters will be read, and EFI_TIMEOUT will be returned. In all cases the number of bytes actually read is returned in *BufferSize.

It is the responsibility of the caller to insure all parameters are valid. There is no provision for parameter checking by Read().

The implementation behavior when an invalid parameter is passed is not defined by this specification.

Status Codes Returned

Status Code Description
EFI_SUCCESS The data was read.
EFI_DEVICE_ERROR The debug port device reported an error.
EFI_TIMEOUT The operation was stopped due to a timeout or overrun.

Poll()

Checks to see if any data is available to be read from the debugport device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_DEBUGPORT_POLL) (
  IN EFI_DEBUGPORT_PROTOCOL *This
  );

Parameters

Parameter Description
This A pointer to the EFI_DEBUGPORT_PROTOCOL instance.

Description
The Poll() function checks if there is any data available to be read from the debug port device and returns the result. No data is actually removed from the input stream. This function enables simpler debugger design since buffering of reads is not necessary by the caller.

Status Codes Returned

Status Code Description
EFI_SUCCESS At least one byte of data is available to be read.
EFI_NOT_READY No data is available to be read.
EFI_DEVICE_ERROR The debug port device is not functioning correctly

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

Personal tools