#include <GdbStubInternal.h>
#include <Protocol/DebugPort.h>

Functions
VOID EFIAPI	GdbSymbolEventHandler (IN EFI_EVENT Event, IN VOID *Context)

EFI_STATUS EFIAPI	GdbStubEntry (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)

VOID	TransferFromInBufToMem (IN UINTN Length, IN unsigned char Address, IN CHAR8 NewData)

VOID	TransferFromMemToOutBufAndSend (IN UINTN Length, IN unsigned char *Address)

UINTN	SendPacket (IN CHAR8 *PacketData)

UINTN	ReceivePacket (OUT CHAR8 *PacketData, IN UINTN PacketDataSize)

VOID	EmptyBuffer (IN CHAR8 *Buf)

INTN	HexCharToInt (IN CHAR8 Char)

VOID EFIAPI	SendError (IN UINT8 ErrorNum)

VOID EFIAPI	SendSuccess (VOID)

VOID EFIAPI	SendNotSupported (VOID)

VOID	GdbSendTSignal (IN EFI_SYSTEM_CONTEXT SystemContext, IN UINT8 GdbExceptionType)

UINT8	ConvertEFItoGDBtype (IN EFI_EXCEPTION_TYPE EFIExceptionType)

VOID EFIAPI	ReadFromMemory (CHAR8 *PacketData)

VOID EFIAPI	WriteToMemory (IN CHAR8 *PacketData)

UINTN	ParseBreakpointPacket (IN CHAR8 PacketData, OUT UINTN Type, OUT UINTN Address, OUT UINTN Length)

UINTN	gXferObjectReadResponse (IN CHAR8 Type, IN CHAR8 *Str)

VOID *EFIAPI	PeCoffLoaderGetDebuggerInfo (IN VOID Pe32Data, OUT VOID *DebugBase)

VOID	QxferLibrary (IN UINTN Offset, IN UINTN Length)

VOID EFIAPI	GdbExceptionHandler (IN EFI_EXCEPTION_TYPE ExceptionType, IN OUT EFI_SYSTEM_CONTEXT SystemContext)

VOID EFIAPI	GdbPeriodicCallBack (IN OUT EFI_SYSTEM_CONTEXT SystemContext)

Variables
UINTN	gMaxProcessorIndex = 0

CHAR8	gInBuffer [MAX_BUF_SIZE]

CHAR8	gOutBuffer [MAX_BUF_SIZE]

BOOLEAN	gSymbolTableUpdate = FALSE

EFI_EVENT	gEvent

VOID *	gGdbSymbolEventHandlerRegistration = NULL

UINTN	gPacketqXferLibraryOffset = 0

UINTN	gEfiDebugImageTableEntry = 0

EFI_DEBUG_IMAGE_INFO_TABLE_HEADER *	gDebugImageTableHeader = NULL

EFI_DEBUG_IMAGE_INFO *	gDebugTable = NULL

CHAR8	gXferLibraryBuffer [2000]

GLOBAL_REMOVE_IF_UNREFERENCED CONST CHAR8	mHexToStr [] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' }

CHAR8 *	gError = "E__"

Detailed Description

UEFI driver that implements a GDB stub

Note: Any code in the path of the Serial IO output can not call DEBUG as will will blow out the stack. Serial IO calls DEBUG, debug calls Serial IO, ...

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file GdbStub.c.

Function Documentation

◆ ConvertEFItoGDBtype()

UINT8 ConvertEFItoGDBtype ( IN EFI_EXCEPTION_TYPE EFIExceptionType )

Translates the EFI mapping to GDB mapping

Parameters

EFIExceptionType EFI Exception that is being processed

Return values

UINTN that corresponds to EFIExceptionType's GDB exception type number

Definition at line 571 of file GdbStub.c.

◆ EmptyBuffer()

VOID EmptyBuffer ( IN CHAR8 * Buf )

Empties the given buffer

Parameters

Buf	pointer to the first element in buffer to be emptied

Definition at line 393 of file GdbStub.c.

◆ GdbExceptionHandler()

VOID EFIAPI GdbExceptionHandler	(	IN EFI_EXCEPTION_TYPE	ExceptionType,
		IN OUT EFI_SYSTEM_CONTEXT	SystemContext
	)

Exception Handler for GDB. It will be called for all exceptions registered via the gExceptionType[] array.

Parameters

ExceptionType	Exception that is being processed
SystemContext	Register content at time of the exception

Definition at line 1088 of file GdbStub.c.

◆ GdbPeriodicCallBack()

VOID EFIAPI GdbPeriodicCallBack ( IN OUT EFI_SYSTEM_CONTEXT SystemContext )

Periodic callback for GDB. This function is used to catch a ctrl-c or other break in type command from GDB.

Parameters

SystemContext Register content at time of the call

Definition at line 1199 of file GdbStub.c.

◆ GdbSendTSignal()

VOID GdbSendTSignal	(	IN EFI_SYSTEM_CONTEXT	SystemContext,
		IN UINT8	GdbExceptionType
	)

Send the T signal with the given exception type (in gdb order) and possibly with n:r pairs related to the watchpoints

Parameters

SystemContext	Register content at time of the exception
GdbExceptionType	GDB exception type

Definition at line 480 of file GdbStub.c.

◆ GdbStubEntry()

EFI_STATUS EFIAPI GdbStubEntry	(	IN EFI_HANDLE	ImageHandle,
		IN EFI_SYSTEM_TABLE *	SystemTable
	)

The user Entry Point for Application. The user code starts with this function as the real entry point for the image goes into a library that calls this function.

Parameters

[in]	ImageHandle	The firmware allocated handle for the EFI image.
[in]	SystemTable	A pointer to the EFI System Table.

Return values

EFI_SUCCESS	The entry point is executed successfully.
other	Some error occurs when executing this entry point.

Definition at line 65 of file GdbStub.c.

◆ GdbSymbolEventHandler()

VOID EFIAPI GdbSymbolEventHandler	(	IN EFI_EVENT	Event,
		IN VOID *	Context
	)

Definition at line 44 of file GdbStub.c.

◆ gXferObjectReadResponse()

UINTN gXferObjectReadResponse	(	IN CHAR8	Type,
		IN CHAR8 *	Str
	)

Definition at line 775 of file GdbStub.c.

◆ HexCharToInt()

INTN HexCharToInt ( IN CHAR8 Char )

Converts an 8-bit Hex Char into a INTN.

Parameters

Char	the hex character to be converted into UINTN

Return values

a	INTN, from 0 to 15, that corresponds to Char -1 if Char is not a hex character

Definition at line 408 of file GdbStub.c.

◆ ParseBreakpointPacket()

UINTN ParseBreakpointPacket	(	IN CHAR8 *	PacketData,
		OUT UINTN *	Type,
		OUT UINTN *	Address,
		OUT UINTN *	Length
	)

Parses breakpoint packet data and captures Breakpoint type, Address and length. In case of an error, function returns particular error code. Returning 0 meaning no error.

Parameters

PacketData	Pointer to the payload data for the packet.
Type	Breakpoint type
Address	Breakpoint address
Length	Breakpoint length in Bytes (1 byte, 2 byte, 4 byte)

Return values

1	Success
{other}	Particular error code

Definition at line 719 of file GdbStub.c.

◆ PeCoffLoaderGetDebuggerInfo()

VOID *EFIAPI PeCoffLoaderGetDebuggerInfo	(	IN VOID *	Pe32Data,
		OUT VOID **	DebugBase
	)

Note: This should be a library function. In the Apple case you have to add the size of the PE/COFF header into the starting address to make things work right as there is no way to pad the Mach-O for the size of the PE/COFF header.

Returns a pointer to the PDB file name for a PE/COFF image that has been loaded into system memory with the PE/COFF Loader Library functions.

Returns the PDB file name for the PE/COFF image specified by Pe32Data. If the PE/COFF image specified by Pe32Data is not a valid, then NULL is returned. If the PE/COFF image specified by Pe32Data does not contain a debug directory entry, then NULL is returned. If the debug directory entry in the PE/COFF image specified by Pe32Data does not contain a PDB file name, then NULL is returned. If Pe32Data is NULL, then ASSERT().

Parameters

Pe32Data	Pointer to the PE/COFF image that is loaded in system memory.
DebugBase	Address that the debugger would use as the base of the image

Returns: The PDB file name for the PE/COFF image specified by Pe32Data or NULL if it cannot be retrieved. DebugBase is only valid if PDB file name is valid.

Definition at line 838 of file GdbStub.c.

◆ QxferLibrary()

VOID QxferLibrary	(	IN UINTN	Offset,
		IN UINTN	Length
	)

Process "qXfer:object:read:annex:offset,length" request.

Returns an XML document that contains loaded libraries. In our case it is information in the EFI Debug Image Table converted into an XML document.

GDB will call with an arbitrary length (it can't know the real length and will reply with chunks of XML that are easy for us to deal with. Gdb will keep calling until we say we are done. XML doc looks like:

<library-list> <library name="/a/a/c/d.dSYM"><segment address="0x10000000"></library> <library name="/a/m/e/e.pdb"><segment address="0x20000000"></library> <library name="/a/l/f/f.dll"><segment address="0x30000000"></library> </library-list>

Since we can not allocate memory in interrupt context this module has assumptions about how it will get called: 1) Length will generally be max remote packet size (big enough) 2) First Offset of an XML document read needs to be 0 3) This code will return back small chunks of the XML document on every read. Each subsequent call will ask for the next available part of the document.

Note: The only variable size element in the XML is: " <library name=\"%s\"><segment address=\"%p\"/></library>\n" and it is based on the file path and name of the symbol file. If the symbol file name is bigger than the max gdb remote packet size we could update this code to respond back in chunks.

Parameters

Offset	offset into special data area
Length	number of bytes to read starting at Offset

Definition at line 1004 of file GdbStub.c.

◆ ReadFromMemory()

VOID EFIAPI ReadFromMemory ( CHAR8 * PacketData )

"m addr,length" Find the Length of the area to read and the start address. Finally, pass them to another function, TransferFromMemToOutBufAndSend, that will read from that memory space and send it as a packet.

pointer to the input buffer

Definition at line 593 of file GdbStub.c.

◆ ReceivePacket()

UINTN ReceivePacket	(	OUT CHAR8 *	PacketData,
		IN UINTN	PacketDataSize
	)

Receive a GDB Remote Serial Protocol Packet

$PacketData::checksum PacketData is passed in and this function adds the packet prefix '$', the packet terminating character '#' and the two digit checksum.

If host re-starts sending a packet without ending the previous packet, only the last valid packet is processed. (In other words, if received packet is '$12345$12345$123456::checksum', only '$123456::checksum' will be processed.)

If an ack '+' is not sent resend the packet

Parameters

PacketData Payload data for the packet

Return values

Number of bytes of packet data received.

Definition at line 327 of file GdbStub.c.

◆ SendError()

VOID EFIAPI SendError ( IN UINT8 ErrorNum )

'E NN' Send an error with the given error number after converting to hex. The error number is put into the buffer in hex. '255' is the biggest errno we can send. ex: 162 will be sent as A2.

Parameters

errno the error number that will be sent

Definition at line 436 of file GdbStub.c.

◆ SendNotSupported()

VOID EFIAPI SendNotSupported ( VOID )

Send empty packet to specify that particular command/functionality is not supported.

Definition at line 466 of file GdbStub.c.

◆ SendPacket()

UINTN SendPacket ( IN CHAR8 * PacketData )

Send a GDB Remote Serial Protocol Packet

$PacketData::checksum PacketData is passed in and this function adds the packet prefix '$', the packet terminating character '#' and the two digit checksum.

If an ack '+' is not sent resend the packet, but timeout eventually so we don't end up in an infinite loop. This is so if you unplug the debugger code just keeps running

Parameters

PacketData Payload data for the packet

Return values

Number of bytes of packet data sent.

Definition at line 270 of file GdbStub.c.

◆ SendSuccess()

VOID EFIAPI SendSuccess ( VOID )

Send 'OK' when the function is done executing successfully.

Definition at line 454 of file GdbStub.c.

◆ TransferFromInBufToMem()

VOID TransferFromInBufToMem	(	IN UINTN	Length,
		IN unsigned char *	Address,
		IN CHAR8 *	NewData
	)

Transfer length bytes of input buffer, starting at Address, to memory.

Parameters

length	the number of the bytes to be transferred/written
*address	the start address of the transferring/writing the memory
*new_data	the new data to be written to memory

Definition at line 182 of file GdbStub.c.

◆ TransferFromMemToOutBufAndSend()

VOID TransferFromMemToOutBufAndSend	(	IN UINTN	Length,
		IN unsigned char *	Address
	)

Transfer Length bytes of memory starting at Address to an output buffer, OutBuffer. This function will finally send the buffer as a packet.

Parameters

Length	the number of the bytes to be transferred/read
*address	pointer to the start address of the transferring/reading the memory

Definition at line 215 of file GdbStub.c.

◆ WriteToMemory()

VOID EFIAPI WriteToMemory ( IN CHAR8 * PacketData )

"M addr,length :XX..." Find the Length of the area in bytes to write and the start address. Finally, pass them to another function, TransferFromInBufToMem, that will write to that memory space the info in the input buffer.

pointer to the input buffer

Definition at line 640 of file GdbStub.c.

Variable Documentation

◆ gDebugImageTableHeader

EFI_DEBUG_IMAGE_INFO_TABLE_HEADER* gDebugImageTableHeader = NULL

Definition at line 36 of file GdbStub.c.

◆ gDebugTable

EFI_DEBUG_IMAGE_INFO* gDebugTable = NULL

Definition at line 37 of file GdbStub.c.

◆ gEfiDebugImageTableEntry

UINTN gEfiDebugImageTableEntry = 0

Definition at line 35 of file GdbStub.c.

◆ gError

CHAR8* gError = "E__"

Definition at line 425 of file GdbStub.c.

◆ gEvent

EFI_EVENT gEvent

Definition at line 28 of file GdbStub.c.

◆ gGdbSymbolEventHandlerRegistration

VOID* gGdbSymbolEventHandlerRegistration = NULL

Definition at line 29 of file GdbStub.c.

◆ gInBuffer

CHAR8 gInBuffer[MAX_BUF_SIZE]

Definition at line 22 of file GdbStub.c.

◆ gMaxProcessorIndex

UINTN gMaxProcessorIndex = 0

Definition at line 17 of file GdbStub.c.

◆ gOutBuffer

CHAR8 gOutBuffer[MAX_BUF_SIZE]

Definition at line 23 of file GdbStub.c.

◆ gPacketqXferLibraryOffset

UINTN gPacketqXferLibraryOffset = 0

Definition at line 34 of file GdbStub.c.

◆ gSymbolTableUpdate

BOOLEAN gSymbolTableUpdate = FALSE

Definition at line 27 of file GdbStub.c.

◆ gXferLibraryBuffer

CHAR8 gXferLibraryBuffer[2000]

Definition at line 38 of file GdbStub.c.

◆ mHexToStr

GLOBAL_REMOVE_IF_UNREFERENCED CONST CHAR8 mHexToStr[] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F' }

Definition at line 40 of file GdbStub.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ConvertEFItoGDBtype()

◆ EmptyBuffer()

◆ GdbExceptionHandler()

◆ GdbPeriodicCallBack()

◆ GdbSendTSignal()

◆ GdbStubEntry()

◆ GdbSymbolEventHandler()

◆ gXferObjectReadResponse()

◆ HexCharToInt()

◆ ParseBreakpointPacket()

◆ PeCoffLoaderGetDebuggerInfo()

◆ QxferLibrary()

◆ ReadFromMemory()

◆ ReceivePacket()

◆ SendError()

◆ SendNotSupported()

◆ SendPacket()

◆ SendSuccess()

◆ TransferFromInBufToMem()

◆ TransferFromMemToOutBufAndSend()

◆ WriteToMemory()

Variable Documentation

◆ gDebugImageTableHeader

◆ gDebugTable

◆ gEfiDebugImageTableEntry

◆ gError

◆ gEvent

◆ gGdbSymbolEventHandlerRegistration

◆ gInBuffer

◆ gMaxProcessorIndex

◆ gOutBuffer

◆ gPacketqXferLibraryOffset

◆ gSymbolTableUpdate

◆ gXferLibraryBuffer

◆ mHexToStr