SerialConnection.h File Reference

Header for serial port connection from debuggee to debugger. More...

Go to the source code of this file.

Macros
#define	CBR_110   110
#define	CBR_300   300
#define	CBR_600   600
#define	CBR_1200   1200
#define	CBR_2400   2400
#define	CBR_4800   4800
#define	CBR_9600   9600
#define	CBR_14400   14400
#define	CBR_19200   19200
#define	CBR_38400   38400
#define	CBR_56000   56000
#define	CBR_57600   57600
#define	CBR_115200   115200
#define	CBR_128000   128000
#define	CBR_256000   256000
#define	COM1_PORT   0x03F8
#define	COM2_PORT   0x02F8
#define	COM3_PORT   0x03E8
#define	COM4_PORT   0x02E8

Functions
VOID	KdHyperDbgTest (UINT16 Byte)
VOID	KdHyperDbgPrepareDebuggeeConnectionPort (UINT32 PortAddress, UINT32 Baudrate)
VOID	KdHyperDbgSendByte (UCHAR Byte, BOOLEAN BusyWait)
BOOLEAN	KdHyperDbgRecvByte (PUCHAR RecvByte)
VOID	SerialConnectionTest ()
	A simple connection test.
NTSTATUS	SerialConnectionPrepare (PDEBUGGER_PREPARE_DEBUGGEE DebuggeeRequest)
	Perform tasks relating to stepping (step-in & step-out) requests.
BOOLEAN	SerialConnectionCheckPort (UINT32 SerialPort)
	Check if serial port address.
BOOLEAN	SerialConnectionCheckBaudrate (DWORD Baudrate)
	Check if baud rate is valid or not.
BOOLEAN	SerialConnectionSend (CHAR *Buffer, UINT32 Length)
	Perform sending buffer over serial.
BOOLEAN	SerialConnectionRecvBuffer (CHAR *BufferToSave, UINT32 *LengthReceived)
	Receive packet from the debugger.
BOOLEAN	SerialConnectionSendTwoBuffers (CHAR *Buffer1, UINT32 Length1, CHAR *Buffer2, UINT32 Length2)
	Perform sending 2 not appended buffers over serial.
BOOLEAN	SerialConnectionSendThreeBuffers (CHAR *Buffer1, UINT32 Length1, CHAR *Buffer2, UINT32 Length2, CHAR *Buffer3, UINT32 Length3)
	Perform sending 3 not appended buffers over serial.

Detailed Description

Header for serial port connection from debuggee to debugger.

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

0.1

Date

2020-12-15

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

CBR_110

#define CBR_110   110

CBR_115200

#define CBR_115200   115200

CBR_1200

#define CBR_1200   1200

CBR_128000

#define CBR_128000   128000

CBR_14400

#define CBR_14400   14400

CBR_19200

#define CBR_19200   19200

CBR_2400

#define CBR_2400   2400

CBR_256000

#define CBR_256000   256000

CBR_300

#define CBR_300   300

CBR_38400

#define CBR_38400   38400

CBR_4800

#define CBR_4800   4800

CBR_56000

#define CBR_56000   56000

CBR_57600

#define CBR_57600   57600

CBR_600

#define CBR_600   600

CBR_9600

#define CBR_9600   9600

COM1_PORT

#define COM1_PORT   0x03F8

COM2_PORT

#define COM2_PORT   0x02F8

COM3_PORT

#define COM3_PORT   0x03E8

COM4_PORT

#define COM4_PORT   0x02E8

Function Documentation

KdHyperDbgPrepareDebuggeeConnectionPort()

VOID KdHyperDbgPrepareDebuggeeConnectionPort	(	UINT32	PortAddress,
		UINT32	Baudrate )

{
    UINT64 PortAddressUChar = 0ULL;
    PortAddressUChar        = PortAddressUChar | PortAddress;
 
    g_PortDetails.Address   = (PUCHAR)PortAddressUChar;
    g_PortDetails.BaudRate  = Baudrate;
    g_PortDetails.Flags     = 0;
    g_PortDetails.ByteWidth = 1;
 
    g_PortDetails.Write = WritePortWithIndex8;
    g_PortDetails.Read  = ReadPortWithIndex8;
}

KdHyperDbgRecvByte()

BOOLEAN KdHyperDbgRecvByte

(

PUCHAR

RecvByte

)

{
    if (Uart16550GetByte(&g_PortDetails, RecvByte) == UartSuccess)
    {
        return TRUE;
    }
    return FALSE;
}

KdHyperDbgSendByte()

VOID KdHyperDbgSendByte	(	UCHAR	Byte,
		BOOLEAN	BusyWait )

{
    Uart16550PutByte(&g_PortDetails, Byte, BusyWait);
}

KdHyperDbgTest()

VOID KdHyperDbgTest

(

UINT16

Byte

)

{
    UNREFERENCED_PARAMETER(Byte);
    //
    // *** This function is for internal use and test
    // don't use it ***
    //
 
    CPPORT TempPort    = {0};
    TempPort.Address   = (PUCHAR)0x2f8;
    TempPort.BaudRate  = 0x01c200; // 115200
    TempPort.Flags     = 0;
    TempPort.ByteWidth = 1;
 
    TempPort.Write = WritePortWithIndex8;
    TempPort.Read  = ReadPortWithIndex8;
 
    Uart16550PutByte(&TempPort, 0x42, TRUE);
 
    for (size_t i = 0; i < 100; i++)
    {
        // char RecvByte = 0;
        // Uart16550GetByte(&TempPort,&RecvByte);
    }
}

SerialConnectionCheckBaudrate()

BOOLEAN SerialConnectionCheckBaudrate

(

DWORD

Baudrate

)

Check if baud rate is valid or not.

Parameters

Baudrate

Returns

BOOLEAN return TRUE if it's correct and returns FALSE if it's not correct

{
    if (Baudrate == CBR_110 || Baudrate == CBR_300 || Baudrate == CBR_600 ||
        Baudrate == CBR_1200 || Baudrate == CBR_2400 || Baudrate == CBR_4800 ||
        Baudrate == CBR_9600 || Baudrate == CBR_14400 || Baudrate == CBR_19200 ||
        Baudrate == CBR_38400 || Baudrate == CBR_56000 || Baudrate == CBR_57600 ||
        Baudrate == CBR_115200 || Baudrate == CBR_128000 ||
        Baudrate == CBR_256000)
    {
        return TRUE;
    }
    return FALSE;
}

SerialConnectionCheckPort()

BOOLEAN SerialConnectionCheckPort

(

UINT32

SerialPort

)

Check if serial port address.

Parameters

SerialPort

Returns

BOOLEAN return TRUE if it's correct and returns FALSE if it's not correct

{
    if (SerialPort == COM1_PORT || SerialPort == COM2_PORT || SerialPort == COM3_PORT ||
        SerialPort == COM4_PORT)
    {
        return TRUE;
    }
    return FALSE;
}

SerialConnectionPrepare()

NTSTATUS SerialConnectionPrepare

(

PDEBUGGER_PREPARE_DEBUGGEE

DebuggeeRequest

)

Perform tasks relating to stepping (step-in & step-out) requests.

Parameters

DebuggerPrintRequest

Request to prepare debuggee

Returns

NTSTATUS

{
    //
    // Check if baud rate is valid or not
    //
    if (!SerialConnectionCheckBaudrate(DebuggeeRequest->Baudrate))
    {
        //
        // Baud rate is invalid, set the status and return
        //
        DebuggeeRequest->Result = DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_BAUDRATE;
        return STATUS_UNSUCCESSFUL;
    }
 
    //
    // Check if port address is valid or not
    //
    if (!SerialConnectionCheckPort(DebuggeeRequest->PortAddress))
    {
        //
        // Port address is invalid, set the status and return
        //
        DebuggeeRequest->Result = DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_SERIAL_PORT;
        return STATUS_UNSUCCESSFUL;
    }
 
    //
    // Prepare the structures needed for connecting remote port
    //
    KdHyperDbgPrepareDebuggeeConnectionPort(DebuggeeRequest->PortAddress, DebuggeeRequest->Baudrate);
 
    //
    // Initialize kernel debugger
    //
    KdInitializeKernelDebugger();
 
    //
    // Send "Start" packet along with Windows Name
    //
    KdResponsePacketToDebugger(DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGEE_TO_DEBUGGER,
                               DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_STARTED,
                               (CHAR *)DebuggeeRequest,
                               MAXIMUM_CHARACTER_FOR_OS_NAME);
 
    //
    // Set status to successful
    //
    DebuggeeRequest->Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
 
    return STATUS_SUCCESS;
}

SerialConnectionRecvBuffer()

BOOLEAN SerialConnectionRecvBuffer	(	CHAR *	BufferToSave,
		UINT32 *	LengthReceived )

Receive packet from the debugger.

Parameters

BufferToSave
LengthReceived

Returns

BOOLEAN

{
    UINT32 Loop = 0;
 
    //
    // Read data and store in a buffer
    //
    while (TRUE)
    {
        UCHAR RecvChar = NULL_ZERO;
 
        if (!KdHyperDbgRecvByte(&RecvChar))
        {
            continue;
        }
 
        //
        // We already now that the maximum packet size is MaxSerialPacketSize
        // Check to make sure that we don't pass the boundaries
        //
        if (!(MaxSerialPacketSize > Loop))
        {
            //
            // Invalid buffer (size of buffer exceeds the limitation)
            //
            LogError("Err, a buffer received in debuggee which exceeds the buffer limitation");
            return FALSE;
        }
 
        BufferToSave[Loop] = RecvChar;
 
        if (SerialConnectionCheckForTheEndOfTheBuffer(&Loop, (BYTE *)BufferToSave))
        {
            break;
        }
 
        Loop++;
    }
 
    //
    // Set the length
    //
    *LengthReceived = Loop;
 
    return TRUE;
}

SerialConnectionSend()

BOOLEAN SerialConnectionSend	(	CHAR *	Buffer,
		UINT32	Length )

Perform sending buffer over serial.

Parameters

Buffer	buffer to send
Length	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if (Length + SERIAL_END_OF_BUFFER_CHARS_COUNT > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/customize-build/increase-communication-buffer-size",
                 Length + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    for (SIZE_T i = 0; i < Length; i++)
    {
        KdHyperDbgSendByte(Buffer[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionSendThreeBuffers()

BOOLEAN SerialConnectionSendThreeBuffers	(	CHAR *	Buffer1,
		UINT32	Length1,
		CHAR *	Buffer2,
		UINT32	Length2,
		CHAR *	Buffer3,
		UINT32	Length3 )

Perform sending 3 not appended buffers over serial.

Parameters

Buffer1	buffer to send
Length1	length of buffer to send
Buffer2	buffer to send
Length2	length of buffer to send
Buffer3	buffer to send
Length3	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if ((Length1 + Length2 + Length3 + SERIAL_END_OF_BUFFER_CHARS_COUNT) > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/customize-build/increase-communication-buffer-size",
                 Length1 + Length2 + Length3 + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    //
    // Send first buffer
    //
    for (SIZE_T i = 0; i < Length1; i++)
    {
        KdHyperDbgSendByte(Buffer1[i], TRUE);
    }
 
    //
    // Send second buffer
    //
    for (SIZE_T i = 0; i < Length2; i++)
    {
        KdHyperDbgSendByte(Buffer2[i], TRUE);
    }
 
    //
    // Send third buffer
    //
    for (SIZE_T i = 0; i < Length3; i++)
    {
        KdHyperDbgSendByte(Buffer3[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionSendTwoBuffers()

BOOLEAN SerialConnectionSendTwoBuffers	(	CHAR *	Buffer1,
		UINT32	Length1,
		CHAR *	Buffer2,
		UINT32	Length2 )

Perform sending 2 not appended buffers over serial.

Parameters

Buffer1	buffer to send
Length1	length of buffer to send
Buffer2	buffer to send
Length2	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if ((Length1 + Length2 + SERIAL_END_OF_BUFFER_CHARS_COUNT) > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/customize-build/increase-communication-buffer-size",
                 Length1 + Length2 + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    //
    // Send first buffer
    //
    for (SIZE_T i = 0; i < Length1; i++)
    {
        KdHyperDbgSendByte(Buffer1[i], TRUE);
    }
 
    //
    // Send second buffer
    //
    for (SIZE_T i = 0; i < Length2; i++)
    {
        KdHyperDbgSendByte(Buffer2[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionTest()

VOID SerialConnectionTest

(

)

A simple connection test.

Returns

VOID

{
    for (SIZE_T i = 0; i < 100; i++)
    {
        KdHyperDbgTest((UINT16)i);
    }
}