Copyright: VKDEBUG


About Program
VKDEBUG, v1.1

September 2002

VKDEBUG is software for debugging programs written with help of MASM32 package. Macros and functions of VKDEBUG allow output of different kinds of debugging information into a special window.

Thanks for Help

License Agreement

What’s New in VKDEBUG

Using VKDEBUG


Thanks for Help

First of all I would like to thank Steve Hutchesson for his suggestion to include VKDEBUG into MASM32 package. Due to him VKDEBUG became popular and many users help me to improve this tool. Today I am already not an author of VKDEBUG because too much code and ideas don’t belong to me. I have received much help from NaN, bitRAKE, Thomas and KetilO. Also, some very valuable ideas belong to Iczelion, TTom, huh and Four-F.

vkim,

Almaty, Kazakhstan

vkim@aport2000.ru

http://www.wasm.ru


License Agreement

1.	VKDEBUG is freeware available for debugging of commercial and non-commercial software.
2.	Nobody can sell VKDEBUG or charge for using VKDEBUG.
3.	No part of VKDEBUG can be included with a commercial package.
4.	Authors own their code and applications of VKDEBUG if other conditions not declared.
5.	VKDEBUG distributed “as is”. No warranty of any kind expressed or implied. You use at your own risk.
6.	Installing and using VKDEBUG signifies acceptance of these terms and conditions of the license.
7.	If you do not agree with the terms of this license you must cease to use VKDEBUG.
Thank you for using VKDEBUG!

vkim


What's New in VKDEBUG
What’s New in VKDEBUG

Âåfore this version the name of  VKDEBUG was DbgWin but due to Steve Hutchesson it became famous as VKDEBUG. So I decided to rename it.

VKDEBUG has these new features:

-	Debugging information can be saved in log files.
-	You can remove debug macros from your program by setting DBGWIN_DEBUG_ON to zero.
-	You can print file name and line number by setting DBGWIN_EXT_INFO to one.
-	PrintDouble, ASSERT, TrapException, DumpMem, DumpFPU, DbgDump, Fix macros are added.
-	PrintDec and PrintHex can get 8-32 bit arguments.
-	PrintDec, PrintHex and PrintDouble macros can print short text comments.
-	Debug.inc can be included into different files of a project simultaneously.


Using VKDEBUG

First of all you have to install VKDEBUG. For this there is a file setup.bat in the package. Of course you have to have MASM32 v7 installed.

Using VKDEBUG is very simple. You must include files debug.inc and debug.lib into your program with this manner:

include \masm32\include\debug.inc

includelib \masm32\lib\debug.lib

Note	Debug macros use windows constants and some functions from kernel32.dll and MASM32 library. So files windows.inc, kernel32.inc, kernel32.lib, masm32.inc, masm32.lib must be included before debug.inc and debug.lib.

After that you can use debug macros.

PrintDec

PrintHex

PrintDouble

PrintString

PrintStringByAddr

PrintText

PrintLine

PrintError

PrintException

Spy

ASSERT

TrapException

DumpMem

DbgDump

DumpFPU

Fix

Note	Debug window stores its settings in the registry (HKEY_LOCAL_MACHINE\Software\MASM32\DbgWin). If it doesn’t find needed information it use default settings:  Top = 0 Left = 0 Width = 250 Height = 250


PrintDec

Syntax

PrintDec Value [,Text]

Description

This macro is intended to print 8-32 bit numbers in decimal signed format. An argument Value can be variable or register. You can optionally add a comment with the Text argument in quotes.

Comments

Please use this macro instead of PrintDword macro from previous versions of VKDEBUG.

Example

PrintDec esp, “Esp value”

PrintDec dwMyVar


PrintHex

Syntax

PrintHex Value [,Text]

Description

This macro is intended to print 8-32 bit numbers in hexadecimal format. An argument Value can be variable or register. You can optionally add a comment with the Text argument in quotes.

Example

PrintHex esp, “Esp value”

PrintHex dwMyVar


PrintDouble

Syntax

PrintDouble Value [,Text]

Description

This macro is intended to print real numbers. And argument must be REAL8 type. You can optionally add a comment with the Text argument in quotes.

Example

PrintDouble dblMyVar


PrintString

Syntax

PrintString Text

Description

This macro is intended to print ASCIIZ-strings passed through an argument Text.

Example

.data

szText byte “Test message”, 0

.code

…

PrintString szText


PrintStringByAddr

Syntax

PrintStringByAddr Address

Description

This macro is intended to print ASCIIZ-string by address. An argument Address must be a pointer to ASCIIZ-string.

Example

.data

szText byte “Test message”, 0

pszText dword offset szText

.code

…

mov eax, offset szText

PrintStringByAddr eax

PrintStringByAddr pszText


PrintText

Syntax

PrintText Text

Description

This macro is intended to print text messages passed through an argument Text in quotes.

Example

PrintText “Hello, world!”


PrintLine

Syntax

PrintLine

Description

This macro is intended to print line. Use it for format debug messages.

Example

PrintLine


PrintError

Syntax

PrintError

Description

This macro is intended to print descriptions of errors returned by GetLastError function.

Example

invoke CreateFile,lpszFileName,

            GENERIC_WRITE,

            NULL,

            NULL,

            CREATE_ALWAYS,

            FILE_ATTRIBUTE_NORMAL,

            NULL

PrintError


PrintException

Syntax

PrintException Value

Description

This macro is intended to print descriptions of exceptions occurred in a program. An argument Value must be a pointer to EXCEPTION_RECORD structure.

Example

_except_handler proc C uses edx pExcept: dword, pFrame: dword, pContext: dword, pDispatch: dword

    PrintException pExcept

    mov eax, ExceptionContinueExecution

    ret

_except_handler endp


Spy

Syntax

Spy Var

Description

The macro turns on trace mode of processor and prints a watched variable in signed decimal format after each processor instruction. An argument Var must be a variable of DWORD type.

Comments

The macro uses its own SEH frame. So it can conflict with others SEH frames installed by user.

Example

.data

dwData dword 0

.code

start:

    Spy dwData

    mov dwData, 10

    shr dwData, 1

    sub dwData, 3

    StopSpy

    ret

end start


ASSERT

Syntax

ASSERT Value [,Text]

Description

The macro prints a message if an argument Value is equal to FALSE or 0. The argument Value can have size 8-32 bit. You can optionally add a comment with the Text argument in quotes.

Example

invoke lstrcpy, addr szText1, addr szText2

ASSERT eax


TrapException

Syntax

TrapException SafePlace

Description

This macro is intended to find where an exception occurred. An argument SafePlace must be an address of label for safe exit.

Comments

To use this macro you have to compile your program with debugging options (/Zi for ml and /DEBUG /DEBUGTYPE:CV for linker). The macro uses symbolic processor dbghelp.dll. It is a part of Windows 2000 and Windows XP but under Windows 9x you have to install it yourself. Please copy dbghelp.dll from VKDEBUG\EXTRA\DBGHELP into %system% directory. Microsoft Corporation permits to distribute dbghelp.dll freely as stated in License Agreement of Platform SDK.

.

Example

TrapException <offset EH>

    xor edx, edx

    mov eax, 1

    xor ecx, ecx

    div ecx

EH:

    ret

end start


DumpMem

Syntax

DumpMem Address, Count [,Text]

Description

This macro is intended to print dump of memory. Argument Address must be a begin address and an argument Count must be number of bytes. Short comments can be printed by an argument Text in quotes.

Example

DumpMem offset lpData, 16


DbgDump

Syntax

DbgDump Address, Count

Description

Yet another macro for dumping memory. It additionally prints a dump in symbolic representation. Argument Address must be a begin address and an argument Count must be number of bytes.

Example

DbgDump offset lpData, 32


DumpFPU

Syntax

DumpFPU [Text]

Description

This macro is intended to inform about states of the FPU device. A short comments can be passed through an argument Text in quotes.

Example

finit

DumpFPU "No Numbers"

fld1

DumpFPU "One Number"

fld Three

fld Two

fld One

fldpi

DumpFPU "5 Numbers"


Fix

Syntax

Fix [Text]

Description

Use this macro if you want to mark code that must be fixed later but you don’t want to forget to do it. During assembly reminder text is echoed to the output with file and line number. You can change default message with the Text argument.

Example

Fix <I am going to change it later>