hwdbg-scripts.h File Reference

Headers for the hardware scripts for hwdbg. More...

Go to the source code of this file.

Functions
VOID	HwdbgScriptPrintScriptBuffer (CHAR *ScriptBuffer, UINT32 ScriptBufferSize)
	Print the actual script.
BOOLEAN	HwdbgScriptCreateHwdbgScript (CHAR *ScriptBuffer, UINT32 ScriptBufferSize, const TCHAR *HardwareScriptFilePathToSave)
	Create hwdbg script.
BOOLEAN	HwdbgScriptSendScriptPacket (HWDBG_INSTANCE_INFORMATION *InstanceInfo, const TCHAR *FileName, UINT32 NumberOfSymbols, HWDBG_SHORT_SYMBOL *Buffer, UINT32 BufferLength)
	Sends a HyperDbg (hwdbg) script packet to the hwdbg.
BOOLEAN	HwdbgScriptGetScriptBufferFromRawString (string ScriptString, PVOID *CodeBuffer, UINT64 *BufferAddress, UINT32 *BufferLength, UINT32 *Pointer)
BOOLEAN	HwdbgScriptRunScript (const CHAR *Script, const TCHAR *InstanceFilePathToRead, const TCHAR *HardwareScriptFilePathToSave, UINT32 InitialBramBufferSize)
	Run script in hwdbg.

Detailed Description

Headers for the hardware scripts for hwdbg.

Author

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

Version

0.11

Date

2024-09-30

Copyright

This project is released under the GNU Public License v3.

Function Documentation

HwdbgScriptCreateHwdbgScript()

BOOLEAN HwdbgScriptCreateHwdbgScript	(	CHAR *	ScriptBuffer,
		UINT32	ScriptBufferSize,
		const TCHAR *	HardwareScriptFilePathToSave )

Create hwdbg script.

Parameters

ScriptBuffer
ScriptBufferSize
HardwareScriptFilePathToSave

Returns

BOOLEAN

{
    UINT32               NumberOfStagesForScript               = 0;
    UINT32               NumberOfOperandsImplemented           = 0;
    UINT32               NumberOfOperandsForScript             = 0;
    SIZE_T               NewCompressedBufferSize               = 0;
    SIZE_T               NumberOfNeededFlipFlopsInTargetDevice = 0;
    SIZE_T               NumberOfBytesPerChunk                 = 0;
    HWDBG_SHORT_SYMBOL * NewScriptBuffer                       = NULL;
 
    //
    // *** Check the script capabilities with the generated script ***
    //
    if (!HardwareScriptInterpreterCheckScriptBufferWithScriptCapabilities(&g_HwdbgInstanceInfo,
                                                                          ScriptBuffer,
                                                                          ScriptBufferSize / sizeof(SYMBOL),
                                                                          &NumberOfStagesForScript,
                                                                          &NumberOfOperandsForScript,
                                                                          &NumberOfOperandsImplemented))
    {
        ShowMessages("\n[-] target script is NOT supported by this instance of hwdbg!\n");
        return FALSE;
    }
    else
    {
        ShowMessages("\n[+] target script is supported by this instance of hwdbg!\n");
    }
 
    //
    // *** Compress the script buffer based on the instance info ***
    //
    if (!HwdbgScriptCompressScriptBuffer(&g_HwdbgInstanceInfo,
                                         (SYMBOL *)ScriptBuffer,
                                         ScriptBufferSize,
                                         NumberOfStagesForScript,
                                         &NewScriptBuffer,
                                         &NewCompressedBufferSize,
                                         &NumberOfBytesPerChunk))
    {
        ShowMessages("err, unable to compress the script buffer\n");
        return FALSE;
    }
 
    //
    // Print the hwdbg script buffer
    //
    HwdbgScriptPrintFinalScriptBufferAndHardwareDetails(&g_HwdbgInstanceInfo,
                                                        NewCompressedBufferSize,
                                                        NumberOfStagesForScript,
                                                        NumberOfOperandsForScript,
                                                        NewScriptBuffer,
                                                        NumberOfNeededFlipFlopsInTargetDevice,
                                                        NumberOfBytesPerChunk,
                                                        NumberOfOperandsImplemented);
 
    //
    // *** Write script configuration packet into a file ***
    //
 
    //
    // Write script configuration packet into a file
    //
    if (!HwdbgScriptWriteScriptConfigurationPacketIntoFile(&g_HwdbgInstanceInfo,
                                                           HardwareScriptFilePathToSave,
                                                           NumberOfStagesForScript,
                                                           NumberOfOperandsImplemented,
                                                           NewScriptBuffer,
                                                           NewCompressedBufferSize))
    {
        ShowMessages("err, unable to write script buffer\n");
        return FALSE;
    }
 
    //
    // *** Free the allocated memory ***
    //
 
    //
    // Free the allocated memory for the short symbol buffer
    //
    if (NewScriptBuffer != NULL)
    {
        HardwareScriptInterpreterFreeHwdbgShortSymbolBuffer(NewScriptBuffer);
    }
 
    //
    // The script buffer is created successfully
    //
    return TRUE;
}

HwdbgScriptGetScriptBufferFromRawString()

BOOLEAN HwdbgScriptGetScriptBufferFromRawString	(	string	ScriptString,
		PVOID *	CodeBuffer,
		UINT64 *	BufferAddress,
		UINT32 *	BufferLength,
		UINT32 *	Pointer )

Get script buffer from raw string

Parameters

ScriptBuffer
CodeBuffer
BufferAddress
BufferLength
Pointer

Returns

BOOLEAN

{
    PVOID ResultingCodeBuffer = NULL;
 
    //
    // Run script engine handler
    //
    ResultingCodeBuffer = ScriptEngineParseWrapper((CHAR *)ScriptString.c_str(), TRUE);
 
    if (ResultingCodeBuffer == NULL)
    {
        //
        // return to show that this item contains an script error
        //
        return FALSE;
    }
 
    //
    // Print symbols (test)
    //
    // PrintSymbolBufferWrapper(ResultingCodeBuffer);
 
    //
    // Set the buffer and length
    //
    *BufferAddress = ScriptEngineWrapperGetHead(ResultingCodeBuffer);
    *BufferLength  = ScriptEngineWrapperGetSize(ResultingCodeBuffer);
    *Pointer       = ScriptEngineWrapperGetPointer(ResultingCodeBuffer);
 
    //
    // Set the code buffer
    //
    *CodeBuffer = ResultingCodeBuffer;
 
    //
    // The script buffer is copied successfully
    //
    return TRUE;
}

HwdbgScriptPrintScriptBuffer()

VOID HwdbgScriptPrintScriptBuffer	(	CHAR *	ScriptBuffer,
		UINT32	ScriptBufferSize )

Print the actual script.

Parameters

ScriptBuffer
ScriptBufferSize

Returns

VOID

{
    //
    // Print the actual script
    //
    ShowMessages("\nHyperDbg (general) script buffer (size=%d, flip-flops (just script)=%d):\n\n",
                 ScriptBufferSize,
                 ScriptBufferSize * 8 // Converted to bits
    );
 
    for (SIZE_T i = 0; i < ScriptBufferSize; i++)
    {
        ShowMessages("%02X ", (UINT8)ScriptBuffer[i]);
    }
 
    ShowMessages("\n");
}

HwdbgScriptRunScript()

BOOLEAN HwdbgScriptRunScript	(	const CHAR *	Script,
		const TCHAR *	InstanceFilePathToRead,
		const TCHAR *	HardwareScriptFilePathToSave,
		UINT32	InitialBramBufferSize )

Run script in hwdbg.

Parameters

Script
InstanceFilePathToRead
HardwareScriptFilePathToSave
InitialBramBufferSize

Returns

BOOLEAN

{
    PVOID  CodeBuffer;
    UINT64 BufferAddress;
    UINT32 BufferLength;
    UINT32 Pointer;
 
    //
    // Load the instance info
    //
    if (!HwdbgLoadInstanceInfo(InstanceFilePathToRead, InitialBramBufferSize))
    {
        //
        // Unable to load the instance info
        //
        return FALSE;
    }
 
    //
    // Get the script buffer from the raw string (script)
    //
    if (!HwdbgScriptGetScriptBufferFromRawString(Script,
                                                 &CodeBuffer,
                                                 &BufferAddress,
                                                 &BufferLength,
                                                 &Pointer))
    {
        //
        // Unable to get script buffer from script
        //
        return FALSE;
    }
 
    //
    // Print the actual script
    //
    HwdbgScriptPrintScriptBuffer((CHAR *)BufferAddress, BufferLength);
 
    //
    // Create hwdbg script
    //
    if (!HwdbgScriptCreateHwdbgScript((CHAR *)BufferAddress,
                                      BufferLength,
                                      HardwareScriptFilePathToSave))
    {
        ShowMessages("err, unable to create hwdbg script\n");
        return FALSE;
    }
 
    //
    // Return the result
    //
    return TRUE;
}

HwdbgScriptSendScriptPacket()

BOOLEAN HwdbgScriptSendScriptPacket	(	HWDBG_INSTANCE_INFORMATION *	InstanceInfo,
		const TCHAR *	FileName,
		UINT32	NumberOfSymbols,
		HWDBG_SHORT_SYMBOL *	Buffer,
		UINT32	BufferLength )

Sends a HyperDbg (hwdbg) script packet to the hwdbg.

Parameters

InstanceInfo
FileName
Buffer
BufferLength

Returns

BOOLEAN

{
    HWDBG_SCRIPT_BUFFER ScriptBuffer = {0};
    BOOLEAN             Result       = FALSE;
 
    //
    // Make the packet's structure
    //
    ScriptBuffer.scriptNumberOfSymbols = NumberOfSymbols;
 
    //
    // Allocate a buffer for storing the header packet + buffer (if not empty)
    //
    CHAR * FinalBuffer = (CHAR *)malloc(BufferLength + sizeof(HWDBG_SCRIPT_BUFFER));
 
    if (!FinalBuffer)
    {
        return FALSE;
    }
 
    RtlZeroMemory(FinalBuffer, BufferLength + sizeof(HWDBG_SCRIPT_BUFFER));
 
    //
    // Copy the packet into the FinalBuffer
    //
    memcpy(FinalBuffer, &ScriptBuffer, sizeof(HWDBG_SCRIPT_BUFFER));
 
    //
    // Copy the buffer (if available) into the FinalBuffer
    //
    if (Buffer != NULL)
    {
        memcpy(FinalBuffer + sizeof(HWDBG_SCRIPT_BUFFER), Buffer, BufferLength);
    }
 
    //
    // Here we would send FinalBuffer to the hardware debugger
    //
    Result = HwdbgInterpreterSendPacketAndBufferToHwdbg(
        InstanceInfo,
        FileName,
        DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGER_TO_DEBUGGEE_HARDWARE_LEVEL,
        hwdbgActionConfigureScriptBuffer,
        FinalBuffer,
        BufferLength + sizeof(HWDBG_SCRIPT_BUFFER));
 
    //
    // Free the allocated memory after use
    //
    free(FinalBuffer);
 
    return Result;
}