hwdbg-interpreter.h File Reference

Headers for the interpreter of hwdbg packets and requests. More...

Go to the source code of this file.

Functions
VOID	HwdbgShowIntanceInfo (HWDBG_INSTANCE_INFORMATION *InstanceInfo)
	Show instance info details.
BOOLEAN	HwdbgInterpretPacket (PVOID BufferReceived, UINT32 LengthReceived)
	Interpret packets of hwdbg.
BOOLEAN	HwdbgInterpreterFillFileFromMemory (HWDBG_INSTANCE_INFORMATION *InstanceInfo, const TCHAR *FileName, UINT32 *MemoryBuffer, SIZE_T BufferSize, HWDBG_ACTION_ENUMS RequestedAction)
	Function to write the memory buffer to a file in the specified format.
BOOLEAN	HwdbgInterpreterFillMemoryFromFile (const TCHAR *FileName, UINT32 *MemoryBuffer, SIZE_T BufferSize)
	Function to read the file and fill the memory buffer.
SIZE_T	HwdbgComputeNumberOfFlipFlopsNeeded (HWDBG_INSTANCE_INFORMATION *InstanceInfo, UINT32 NumberOfStages)
	Function to compute number of flip-flops needed in the target device.
BOOLEAN	HwdbgInterpreterSendPacketAndBufferToHwdbg (HWDBG_INSTANCE_INFORMATION *InstanceInfo, const TCHAR *FileName, DEBUGGER_REMOTE_PACKET_TYPE PacketType, HWDBG_ACTION_ENUMS RequestedAction, CHAR *Buffer, UINT32 BufferLength)
	Sends a HyperDbg packet + a buffer to the hwdbg.
BOOLEAN	HwdbgReadInstanceInfoFromFile (const TCHAR *FileName, UINT32 *MemoryBuffer, SIZE_T BufferSize)
	Read the instance info from the file.
BOOLEAN	HwdbgWriteTestInstanceInfoRequestIntoFile (HWDBG_INSTANCE_INFORMATION *InstanceInfo, const CHAR *FileName)
	Write test instance info request into a file.
BOOLEAN	HwdbgLoadInstanceInfo (const TCHAR *InstanceFilePathToRead, UINT32 InitialBramBufferSize)
	Load the instance info.

Detailed Description

Headers for the interpreter of hwdbg packets and requests.

Author

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

Version

0.10

Date

2024-06-11

Copyright

This project is released under the GNU Public License v3.

Function Documentation

HwdbgComputeNumberOfFlipFlopsNeeded()

SIZE_T HwdbgComputeNumberOfFlipFlopsNeeded	(	HWDBG_INSTANCE_INFORMATION *	InstanceInfo,
		UINT32	NumberOfStages )

Function to compute number of flip-flops needed in the target device.

Parameters

InstanceInfo
NumberOfStages

Returns

SIZE_T

{
    //
    // Calculate the number of flip-flops needed in the target device
    // + operator symbol itself which only contains value (type is always equal to SYMBOL_SEMANTIC_RULE_TYPE)
    // so, it is not counted as a flip-flop
    //
    SIZE_T NumberOfNeededFlipFlopsInTargetDevice = 0;
 
    //
    // size of operator (GET and SET)
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages *
                                              (g_HwdbgInstanceInfo.maximumNumberOfSupportedGetScriptOperators + g_HwdbgInstanceInfo.maximumNumberOfSupportedSetScriptOperators) *
                                              g_HwdbgInstanceInfo.scriptVariableLength *
                                              sizeof(HWDBG_SHORT_SYMBOL) / sizeof(UINT64));
 
    //
    // size of main operator (/ 2 is because Type is not inferred)
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages * g_HwdbgInstanceInfo.scriptVariableLength * (sizeof(HWDBG_SHORT_SYMBOL) / sizeof(UINT64)) / 2);
 
    //
    // size of local (and global) variables
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages * g_HwdbgInstanceInfo.numberOfSupportedLocalAndGlobalVariables * g_HwdbgInstanceInfo.scriptVariableLength);
 
    //
    // size of temporary variables
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages * g_HwdbgInstanceInfo.numberOfSupportedTemporaryVariables * g_HwdbgInstanceInfo.scriptVariableLength);
 
    //
    // size of stage index register + targetStage (* 2)
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages * Log2Ceil(g_HwdbgInstanceInfo.maximumNumberOfStages * (g_HwdbgInstanceInfo.maximumNumberOfSupportedGetScriptOperators + g_HwdbgInstanceInfo.maximumNumberOfSupportedSetScriptOperators + 1)) * 2);
 
    //
    // stage enable flip-flop
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages);
 
    //
    // input => output flip-flop
    //
    NumberOfNeededFlipFlopsInTargetDevice += (NumberOfStages * g_HwdbgInstanceInfo.numberOfPins);
 
    //
    // return the number of flip-flops needed in the target device
    //
    return NumberOfNeededFlipFlopsInTargetDevice;
}

HwdbgInterpreterFillFileFromMemory()

BOOLEAN HwdbgInterpreterFillFileFromMemory	(	HWDBG_INSTANCE_INFORMATION *	InstanceInfo,
		const TCHAR *	FileName,
		UINT32 *	MemoryBuffer,
		SIZE_T	BufferSize,
		HWDBG_ACTION_ENUMS	RequestedAction )

Function to write the memory buffer to a file in the specified format.

Parameters

InstanceInfo
FileName
MemoryBuffer
BufferSize
RequestedAction

Returns

BOOLEAN

{
    std::ofstream File(FileName);
 
    if (!File.is_open())
    {
        printf("err, unable to open file %s\n", FileName);
        return FALSE;
    }
 
    SIZE_T Address = 0;
    for (SIZE_T I = 0; I < BufferSize / sizeof(UINT32); ++I)
    {
        File << std::hex << std::setw(8) << std::setfill('0') << MemoryBuffer[I];
        File << " ; +0x" << std::hex << std::setw(1) << std::setfill('0') << Address;
 
        if (I == 0)
        {
            File << "   | Checksum";
        }
        else if (I == 1)
        {
            File << "   | Checksum";
        }
        else if (I == 2)
        {
            File << "   | Indicator";
        }
        else if (I == 3)
        {
            File << "   | Indicator";
        }
        else if (I == 4)
        {
            File << "  | TypeOfThePacket - DEBUGGER_TO_DEBUGGEE_HARDWARE_LEVEL (0x4)";
        }
        else if (I == 5)
        {
            File << "  | RequestedActionOfThePacket - Value" << " (0x" << std::hex << std::setw(1) << std::setfill('0') << RequestedAction << ")";
        }
        else if (I == 6)
        {
            File << "  | Start of Optional Data";
        }
 
        File << "\n";
        Address += 4;
    }
 
    //
    // Add zeros to the end of the file to fill the shared memory
    //
    if (g_HwdbgInstanceInfoIsValid)
    {
        while (Address < InstanceInfo->sharedMemorySize)
        {
            File << "00000000 ; +0x" << std::hex << std::setw(1) << std::setfill('0') << Address;
            Address += 4;
 
            if (Address < InstanceInfo->sharedMemorySize)
            {
                File << "\n";
            }
        }
    }
 
    //
    // Close the file
    //
    File.close();
 
    return TRUE;
}

HwdbgInterpreterFillMemoryFromFile()

BOOLEAN HwdbgInterpreterFillMemoryFromFile	(	const TCHAR *	FileName,
		UINT32 *	MemoryBuffer,
		SIZE_T	BufferSize )

Function to read the file and fill the memory buffer.

Parameters

FileName
MemoryBuffer
BufferSize

Returns

BOOLEAN

{
    std::ifstream File(FileName);
    std::string   Line;
    BOOLEAN       Result = TRUE;
    SIZE_T        Index  = 0;
 
    if (!File.is_open())
    {
        ShowMessages("err, unable to open file %s\n", FileName);
        return FALSE;
    }
 
    while (getline(File, Line))
    {
        if (Index >= BufferSize)
        {
            Result = FALSE;
            ShowMessages("err, buffer overflow, file contains more data than buffer can hold\n");
            break;
        }
 
        vector<UINT32> Values = HwdbgParseStringMemoryLine(Line);
 
        for (UINT32 Value : Values)
        {
            if (Index < BufferSize)
            {
                MemoryBuffer[Index++] = Value;
            }
            else
            {
                ShowMessages("err, buffer overflow, file contains more data than buffer can hold\n");
                File.close();
                return FALSE;
            }
        }
    }
 
    File.close();
    return Result;
}

HwdbgInterpreterSendPacketAndBufferToHwdbg()

BOOLEAN HwdbgInterpreterSendPacketAndBufferToHwdbg	(	HWDBG_INSTANCE_INFORMATION *	InstanceInfo,
		const TCHAR *	FileName,
		DEBUGGER_REMOTE_PACKET_TYPE	PacketType,
		HWDBG_ACTION_ENUMS	RequestedAction,
		CHAR *	Buffer,
		UINT32	BufferLength )

Sends a HyperDbg packet + a buffer to the hwdbg.

Parameters

InstanceInfo
FileName
PacketType
RequestedAction
Buffer
BufferLength

Returns

BOOLEAN

{
    DEBUGGER_REMOTE_PACKET Packet          = {0};
    SIZE_T                 CommandMaxSize  = 0;
    SIZE_T                 FinalBufferSize = 0;
 
    if (g_HwdbgInstanceInfoIsValid)
    {
        CommandMaxSize = InstanceInfo->debuggeeAreaOffset - InstanceInfo->debuggerAreaOffset;
    }
    else
    {
        //
        // Use default limitation
        //
        CommandMaxSize = DEFAULT_INITIAL_DEBUGGEE_TO_DEBUGGER_OFFSET - DEFAULT_INITIAL_DEBUGGER_TO_DEBUGGEE_OFFSET;
    }
 
    //
    // If buffer is not available, then the length is zero
    //
    if (Buffer == NULL)
    {
        BufferLength = 0;
    }
 
    //
    // Compute the final buffer size
    //
    FinalBufferSize = sizeof(DEBUGGER_REMOTE_PACKET) + BufferLength;
 
    //
    // Check if buffer not pass the boundary
    //
    if (FinalBufferSize > CommandMaxSize)
    {
        ShowMessages("err, buffer is above the maximum buffer size that can be sent to hwdbg (%d > %d)\n",
                     FinalBufferSize,
                     CommandMaxSize);
 
        return FALSE;
    }
 
    //
    // Make the packet's structure
    //
    Packet.Indicator       = INDICATOR_OF_HYPERDBG_PACKET;
    Packet.TypeOfThePacket = PacketType;
 
    //
    // Set the requested action
    //
    Packet.RequestedActionOfThePacket = (DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION)RequestedAction;
 
    //
    // calculate checksum of the packet
    //
    Packet.Checksum =
        KdComputeDataChecksum((PVOID)((UINT64)&Packet + 1),
                              sizeof(DEBUGGER_REMOTE_PACKET) - sizeof(BYTE));
 
    if (Buffer != NULL)
    {
        Packet.Checksum += KdComputeDataChecksum((PVOID)Buffer, BufferLength);
    }
 
    //
    // If there is an offset for debugger to debuggee command, we'll apply it here
    //
    if (g_HwdbgInstanceInfoIsValid)
    {
        FinalBufferSize += InstanceInfo->debuggerAreaOffset;
    }
    else
    {
        FinalBufferSize += DEFAULT_INITIAL_DEBUGGER_TO_DEBUGGEE_OFFSET;
    }
 
    //
    // Allocate a buffer for storing the header packet + buffer (if not empty)
    //
    CHAR * FinalBuffer = (CHAR *)malloc(FinalBufferSize);
 
    if (!FinalBuffer)
    {
        return FALSE;
    }
 
    RtlZeroMemory(FinalBuffer, FinalBufferSize);
 
    //
    // Leave the offset
    //
    SIZE_T Offset = g_HwdbgInstanceInfoIsValid ? InstanceInfo->debuggerAreaOffset : DEFAULT_INITIAL_DEBUGGER_TO_DEBUGGEE_OFFSET;
 
    //
    // Copy the packet into the FinalBuffer
    //
    memcpy(FinalBuffer + Offset, &Packet, sizeof(DEBUGGER_REMOTE_PACKET));
 
    //
    // Copy the buffer (if available) into the FinalBuffer
    //
    if (Buffer != NULL)
    {
        memcpy(FinalBuffer + Offset + sizeof(DEBUGGER_REMOTE_PACKET), Buffer, BufferLength);
    }
 
    //
    // Here you would send FinalBuffer to the hardware debugger
    //
    HwdbgInterpreterFillFileFromMemory(InstanceInfo, FileName, (UINT32 *)FinalBuffer, FinalBufferSize, RequestedAction);
 
    //
    // Free the allocated memory after use
    //
    free(FinalBuffer);
 
    return TRUE;
}

HwdbgInterpretPacket()

BOOLEAN HwdbgInterpretPacket	(	PVOID	BufferReceived,
		UINT32	LengthReceived )

Interpret packets of hwdbg.

Parameters

BufferReceived
LengthReceived

Returns

BOOLEAN

{
    PHWDBG_INSTANCE_INFORMATION InstanceInfoPacket;
    PUINT32                     InstanceInfoPorts;
    DEBUGGER_REMOTE_PACKET *    TheActualPacket = NULL;
    BOOLEAN                     Result          = FALSE;
 
    //
    // Apply the initial offset
    //
    if (g_HwdbgInstanceInfoIsValid)
    {
        //
        // Use the debuggee's preferred offset (area) since the instance info
        // already received and interpreted
        //
        TheActualPacket = (DEBUGGER_REMOTE_PACKET *)(((CHAR *)BufferReceived) + g_HwdbgInstanceInfo.debuggeeAreaOffset);
    }
    else
    {
        //
        // Use default initial offset as there is no information (instance info)
        // from debuggee
        //
        TheActualPacket = (DEBUGGER_REMOTE_PACKET *)(((CHAR *)BufferReceived) + DEFAULT_INITIAL_DEBUGGEE_TO_DEBUGGER_OFFSET);
    }
 
    if (TheActualPacket->Indicator == INDICATOR_OF_HYPERDBG_PACKET)
    {
        //
        // Check checksum (for hwdbg, checksum is ignored)
        //
        // if (KdComputeDataChecksum((PVOID)&TheActualPacket->Indicator,
        //                           LengthReceived - sizeof(BYTE)) != TheActualPacket->Checksum)
        // {
        //     ShowMessages("err, checksum is invalid\n");
        //     return FALSE;
        // }
 
        //
        // Check if the packet type is correct
        //
        if (TheActualPacket->TypeOfThePacket != DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGEE_TO_DEBUGGER_HARDWARE_LEVEL)
        {
            //
            // sth wrong happened, the packet is not belonging to use
            // for hwdbg interpreter
            //
            ShowMessages("err, unknown packet received from the debuggee\n");
            return FALSE;
        }
 
        //
        // It's a HyperDbg packet (for hwdbg)
        //
        switch (TheActualPacket->RequestedActionOfThePacket)
        {
        case hwdbgResponseSuccessOrErrorMessage:
 
            Result = TRUE;
 
            //
            // Todo: implement it
            //
 
            break;
 
        case hwdbgResponseInstanceInfo:
 
            Result             = TRUE;
            InstanceInfoPacket = (HWDBG_INSTANCE_INFORMATION *)(((CHAR *)TheActualPacket) + sizeof(DEBUGGER_REMOTE_PACKET));
            InstanceInfoPorts  = (UINT32 *)(((CHAR *)InstanceInfoPacket) + sizeof(HWDBG_INSTANCE_INFORMATION));
 
            //
            // Copy the instance info into the global hwdbg instance info
            //
            RtlCopyMemory(&g_HwdbgInstanceInfo, InstanceInfoPacket, sizeof(HWDBG_INSTANCE_INFORMATION));
 
            //
            // Reset previous port configurations (if any)
            //
            g_HwdbgPortConfiguration.clear();
 
            //
            // Instance info is valid from now
            //
            g_HwdbgInstanceInfoIsValid = TRUE;
 
            //
            // Read port arrangements
            //
            for (SIZE_T i = 0; i < g_HwdbgInstanceInfo.numberOfPorts; i++)
            {
                g_HwdbgPortConfiguration.push_back(InstanceInfoPorts[i]);
            }
 
            //
            // Infom the script engine about the instance info
            //
            ScriptEngineSetHwdbgInstanceInfo(&g_HwdbgInstanceInfo);
 
            break;
 
        default:
 
            Result = FALSE;
            ShowMessages("err, unknown packet request received from the debuggee\n");
 
            break;
        }
    }
 
    //
    // Packet handled successfully
    //
    return Result;
}

HwdbgLoadInstanceInfo()

BOOLEAN HwdbgLoadInstanceInfo	(	const TCHAR *	InstanceFilePathToRead,
		UINT32	InitialBramBufferSize )

Load the instance info.

Parameters

InstanceFilePathToRead
InitialBramBufferSize

Returns

BOOLEAN

{
    UINT32 * MemoryBuffer = NULL;
 
    //
    // Allocate memory buffer to read the instance info
    //
    MemoryBuffer = (UINT32 *)malloc(InitialBramBufferSize * sizeof(UINT32));
 
    if (MemoryBuffer == NULL)
    {
        //
        // Memory allocation failed
        //
        ShowMessages("err, unable to allocate memory for the instance info packet of the debuggee");
        return FALSE;
    }
 
    //
    // *** Read the instance info from the file ***
    //
    if (HwdbgReadInstanceInfoFromFile(InstanceFilePathToRead, MemoryBuffer, InitialBramBufferSize))
    {
        ShowMessages("instance info read successfully\n");
    }
    else
    {
        ShowMessages("err, unable to read instance info packet of the debuggee");
        free(MemoryBuffer);
        return FALSE;
    }
 
    //
    // *** Interpret instance info packet ***
    //
    if (HwdbgInterpretPacket(MemoryBuffer, InitialBramBufferSize))
    {
        ShowMessages("instance info interpreted successfully\n");
        HwdbgShowIntanceInfo(&g_HwdbgInstanceInfo);
    }
    else
    {
        ShowMessages("err, unable to interpret instance info packet of the debuggee");
        free(MemoryBuffer);
        return FALSE;
    }
 
    //
    // The instance info is loaded successfully
    //
    free(MemoryBuffer);
    return TRUE;
}

HwdbgReadInstanceInfoFromFile()

BOOLEAN HwdbgReadInstanceInfoFromFile	(	const TCHAR *	FileName,
		UINT32 *	MemoryBuffer,
		SIZE_T	BufferSize )

Read the instance info from the file.

Parameters

FileName
MemoryBuffer
BufferSize

Returns

BOOLEAN

{
    TCHAR TestFilePath[MAX_PATH] = {0};
 
    if (SetupPathForFileName(HWDBG_TEST_READ_INSTANCE_INFO_PATH, TestFilePath, sizeof(TestFilePath), TRUE) &&
        HwdbgInterpreterFillMemoryFromFile(TestFilePath, MemoryBuffer, BufferSize))
    {
        //
        // Print the content of MemoryBuffer for verification
        //
        for (SIZE_T I = 0; I < BufferSize; ++I)
        {
            ShowMessages("%08x ", MemoryBuffer[I]);
            ShowMessages("\n");
        }
 
        //
        // the instance info packet is read successfully
        //
        return TRUE;
    }
 
    //
    // the instance info packet is not read successfully
    //
    return FALSE;
}

HwdbgShowIntanceInfo()

VOID HwdbgShowIntanceInfo

(

HWDBG_INSTANCE_INFORMATION *

InstanceInfo

)

Show instance info details.

Parameters

InstanceInfo

Returns

VOID

{
    UINT32 PortNum = 0;
 
    ShowMessages("Debuggee Version: 0x%x\n", InstanceInfo->version);
    ShowMessages("Debuggee Maximum Number Of Stages: 0x%x\n", InstanceInfo->maximumNumberOfStages);
    ShowMessages("Debuggee Script Variable Length: 0x%x\n", InstanceInfo->scriptVariableLength);
    ShowMessages("Debuggee Number of Supported Local (and global) Variables: 0x%x\n", InstanceInfo->numberOfSupportedLocalAndGlobalVariables);
    ShowMessages("Debuggee Number of Supported Temporary Variables: 0x%x\n", InstanceInfo->numberOfSupportedTemporaryVariables);
    ShowMessages("Debuggee Maximum Number Of Supported GET Script Operators: 0x%x\n", InstanceInfo->maximumNumberOfSupportedGetScriptOperators);
    ShowMessages("Debuggee Maximum Number Of Supported SET Script Operators: 0x%x\n", InstanceInfo->maximumNumberOfSupportedSetScriptOperators);
    ShowMessages("Debuggee Shared Memory Size: 0x%x\n", InstanceInfo->sharedMemorySize);
    ShowMessages("Debuggee Debugger Area Offset: 0x%x\n", InstanceInfo->debuggerAreaOffset);
    ShowMessages("Debuggee Debuggee Area Offset: 0x%x\n", InstanceInfo->debuggeeAreaOffset);
    ShowMessages("Debuggee Script Capabilities Mask: 0x%llx\n", InstanceInfo->scriptCapabilities);
 
    //
    // Show script capabilities
    //
    HardwareScriptInterpreterShowScriptCapabilities(&g_HwdbgInstanceInfo);
 
    ShowMessages("Debuggee Number Of Pins: 0x%x\n", InstanceInfo->numberOfPins);
    ShowMessages("Debuggee Number Of Ports: 0x%x\n", InstanceInfo->numberOfPorts);
 
    ShowMessages("Debuggee BRAM Address Width: 0x%x\n", InstanceInfo->bramAddrWidth);
    ShowMessages("Debuggee BRAM Data Width: 0x%x (%d bit)\n", InstanceInfo->bramDataWidth, InstanceInfo->bramDataWidth);
 
    for (auto item : g_HwdbgPortConfiguration)
    {
        ShowMessages("Port number %d ($hw_port%d): 0x%x\n", PortNum, PortNum, item);
        PortNum++;
    }
}

HwdbgWriteTestInstanceInfoRequestIntoFile()

BOOLEAN HwdbgWriteTestInstanceInfoRequestIntoFile	(	HWDBG_INSTANCE_INFORMATION *	InstanceInfo,
		const CHAR *	FileName )

Write test instance info request into a file.

Parameters

InstanceInfo
FileName

Returns

BOOLEAN

{
    TCHAR TestFilePath[MAX_PATH] = {0};
 
    //
    // Write test instance info request into a file
    //
    if (SetupPathForFileName(FileName, TestFilePath, sizeof(TestFilePath), FALSE) &&
        HwdbgInterpreterSendPacketAndBufferToHwdbg(
            InstanceInfo,
            TestFilePath,
            DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGER_TO_DEBUGGEE_HARDWARE_LEVEL,
            hwdbgActionSendInstanceInfo,
            NULL,
            NULL_ZERO))
    {
        ShowMessages("[*] instance info successfully written into file: %s\n", TestFilePath);
        return TRUE;
    }
 
    //
    // Unable to write instance info request into a file
    //
    return FALSE;
}