Unofficial guide to MTDBG
Disclaimer
This is an unofficial guide, targetted at the beginner. The official documentation is called 'mtdbg.txt' and can be found in DOCPACK program in KolibriOS.
Using MTDBG
MTDBG is the application-level debugger for KolibriOS.
It can make your life easier on many occasions. Whether you are still learning assembly and just want to see what's going on, or you are trying to fix that bug that nobody else has the guts for.
Overview
Loading your application
There are several ways to load your application into the debugger.
You could simply click 'MTDBG' icon on the KolibriOS desktop and use the 'load' command from there.
Another option is to load it from FASM (in KolibriOS) with 'debug' button.
The third option is to load directly from tinypad by pressing f10 or choosing "run > run in debugger" from the menu while your source code is opened in tinypad.
Loading symbols
The debugger works with binary code. It views the unassembled code to the developer, but this code has much less information then the original assembly code.
All information such as labels, comments etc. were lost during assembly process.
When working on a binary, this information cannot be recovered.
When you have the original source code however, it can be useful to load this information into the debugger so it displays the original label names additional to the hexadecimal addresses.
In FASM on KolibriOS, select the 'generate debug information' check-box before assembling your code.
FASM will now create a *.dbg file in the same folder as the binary, which should be automatically loaded by MTDBG when loading the binary.
MTDBG versions 0.34 and newer also have support to load symbols from a .map file that can be generated by GCC.
Using breakpoints
Single stepping can be really fun when you have nothing else to do, but most developers probably want to spend their time usefully.
Therefore, you can request the debugger to halt the execution of the program when a given instruction is about to be run.
Lets assume we have our symbols loaded, and we are interested in what happens after the label 'red'.
(Offcourse you can also enter addresses in hexadecimal, when no symbols are loaded, or the instruction of interest has no label)
While the program is suspended (default state after loading a program), type 'bp red' to set the breakpoint.
You will see the label highlighted in blue in the disassembly view.
Now you can run the program (eg by using the command 'g') and the program will suspend when the subroutine of interest is reached.
Commands
loading files into the debugger
load
Load the program you want to debug.
eg. 'load /rd/1/example'
load-symbols
Load the debug symbols.
These symbols can be generated with FASM on KolibriOS by selecting the 'generate debug symbols' option before compiling the code.
The debug symbols have .dbg extension.
If the symbols exist in the same directory, and with the same filename as the binary, they will be loaded automatically.
eg. 'load-symbols /rd/1/example.dbg
controlling the view
d
Dump data at a given addres.
Parameter can be direct hex address, register or label.
eg. 'd esi'
u
Unassemble code at a given addres.
Parameter can be direct hex address, register or label.
eg. 'u redraw'
Stepping and running
s
Single step. Execute the following instruction and then halt.
g
Go on. (Resume execution of program)
Execution will terminate when a breakpoint is reached, the application exits or when there occurs a fault (divide by 0, page fault, ..)
reading/manipulating the registers
?
Calculate the value of an expression (and print the value to the debugger).
eg. '? eax - ebx'
r
Change the value of a register to a given expression.
eg. 'r eax 1234'
eg. 'r eax edx'
breakpoints
bp
Set a (regular) breakpoint.
The debugger will suspend the debugged process whenever such a point is reached.
eg. 'bp redraw'
eg. 'bp 1234'
bpm
Set a data breakpoint.
The debugger will suspend the debugged process when the data at the given address is being accessed.
You must give the size of the data type (b = byte, w = word, d = dword) and the type of access on which you want to break (r = read/write [default], w = write only)
eg. 'bpmw 1234'
bc
Clear a breakpoint (remove it completely).
eg. 'bc 0'
bd
Disable a breakpoint (but remember the address in list).
eg. 'bd 1'
be
Enable a previously disabled breakpoint.
eg. 'be 0'
bl
List all active breakpoints.
Expressions
Some of the previously listed commands accept so called expressions as an input.
Expressions can include:
- Hexadecimal constants.
- Names of general-purpose registers.
- +, -, *, / arithmetic symbols (with standard priorities) and brackets.
- labels from symbol file.
some examples:
eax
eip+2
ecx-esi-1F
al+ah*bl
ax+2*bh*(eip+ a73)
*esi*di/eax
User breakpoints
Another way of inserting breakpoints into the program you want to debug, is by putting them inside the binary.
This can be done with a hex editor, your assembler, or even your compiler.
MTDBG will recognize all "int 3" instructions as so called user breakpoints. So all you need to do is place "int 3" assembly code at the place where you'd like the program to halt for inspection. (Or you can try to be hardcore and just use 0xCC hexadecimal code.)