Subversion Repositories Kolibri OS

Introduction.

mtdbg is a debugger for Kolibri operating system. This documentation describes

debugger features and work with it. Feel free to ask on our board (mostly

in Russian, but has an English forum) -- board.kolibrios.org.

General description.

In each moment of time mtdbg can debug only one program. I will call it

loaded program. If no program is loaded, overwhelming majority of debugging

actions is disabled.

mtdbg is controlled by command line, entering from keyboard. Command line

is drawn in the bottom part of debugger window. Debugger handles standard

input keys Backspace,Delete,Home,End,left/right arrows.

Commands are case-insensitive. Delimiter is arbitrary nonzero number of spaces.

At any moment mtdbg can be terminated by command "quit" (without arguments).

You can also simply press to close button in the right upper corner of window.

When debugger is started without command string parameters, no program is

loaded. Also mtdbg can be started with command string, in this case it tries

to load program with the name pointed to in first parameter in command string

and parameters pointed to following (if present).

If no program is loaded, you can load a program with the command

load  []

Examples:

load /rd/1/example

LOAD   /rd/1/aclock w200 h200

  LoaD  /hd0/1/menuetos/dosbox/dosbox

All that stays after first space after executable file name, is exactly passed

to program as command string.

The command "load" reports result in the messages window (a little higher

than command line window). If program was loaded successfully, there will

be the appropriate message; otherwise the message will contain error reason.

Most probable error is "file not found" if wrong file name is given.

The debugger can load files with information on symbols in the program

(labels, global variables) - text files, each line of which has format

0x 

(lines, which do not have such format, are ignored). Such file can be created

by hand or generated automatically by fasm. Evident load can be done by command

load-symbols 

Furthermore, when the debugger executes the command "load", it checks for

presence of file with name as of loading binary and extension '.dbg'

(/rd/1/example.dbg in the first of examples above), and if such file exists,

the debugger loads it automatically (with the message "Symbols loaded", if

all is OK).

It can happen so that loaded program is packed. General principle of

program packing is following: at first input file is packed (by some

pack algorithm), then is appended small code which gets control at program

start, unpacks input code in the memory and then passes control to it.

If program is packed, it "real" code is not visible and for debugging it is

needed previously to pass through unpacker code.

mtdbg determines most of existing packers (mxp,mxp_lzo,mxp_nrv,mtappack)

and in this case suggests to automatically go to "real" code. It is recommended

to accept (press 'y' or ), but you can refuse too. At refusal and if

program is packed by something unknown the command "unpack" (without arguments)

can be used. Call it only in the case when you are sure that program is packed

and control has not already went to main code! [Starting from Kolibri 0.6.5.0,

this paragraph is no more actual, because one can pack applications as all

binary files with kpack and the unpacker code in this case is located in the

kernel and is transparent for debug.]

Loaded program can be terminated by the command "terminate" (without

arguments). The command "detach" (without arguments) detaches from program,

after that program continues execution normally, as if there was no debugger.

After both this commands program stops to be debugged.

It is possible to anew load program for debugging by the command "reload"

(without arguments). If there is already loaded program, it is terminated

and new instance is started (from the beginning) (with the same command

string), in this case the command is similar to the commands

terminate

load  

Otherwise is loaded anew latest program, which was debugged (in the current

seance of work with mtdbg) (with the same command string), i.e. is similar to

load  ,

but the command "reload" in both cases is shorter and more convenient;

moreover, "load" thinks that new program is loaded and moves data window

(see below) to zero address, and "reload" keeps current address.

The command "help", which can be shorten to "h", is always available.

All commands are divided on groups.

"help" without arguments displays the list of command groups.

"help" with group name displays the list of commands in this group with short

comments.

"help" with command name displays information about given command.

Examples:

help

help control

h LoaD

The debugger window consists from the following items enumerated from up

to down:

- status string. If there is loaded program, shows its name and state

  ("Running/Paused"), otherwise reports "No program loaded".

- registers window - shows values of general-purpose registers, register eip

  and states of single flags: CF,PF,AF,ZF,SF,DF,OF: if flag is cleared, then

  is displayed lower-case letter, if flag is set, then upper-case one.

  Registers which are changed from previous moment are highlighted in green.

- data window (dump window) - shows memory contains of loaded program

- code window (disassembler window) - shows program code as disassembled

  instructions

- messages window

- command line window

Dump window can display data starting from any address, to this serves

the command

d 

The command "d" without arguments flicks dump window down.

The same is for code window and the command

u 

or simply "u".

Examples:

d esi - displays data at address esi (e.g. is useful before execution of

  instruction rep movsb)

d esp - displays stack

u eip - disassembles instruction starting from the current

Expressions in mtdbg can include

- hexadecimal constants

- names of all general-purpose registers (8 32-bits, 8 16-bits and

  8 8-bits) and register eip; values of 16- and 8-bits registers are padded

  with zeroes to 32 bits

- four arithmetic operations +,-,*,/ (with standard priorities) and

  brackets

- [if symbols information was loaded] names, loaded from dbg-file

All calculations are realized modulo 2^32.

Examples of expressions:

eax

eip+2

ecx-esi-1F

al+AH*bl

ax + 2* bH*(eip+a73)

3*esi*di/EAX

The command

? 

calculates value of specified expression.

Values of registers in loaded program can be changed by the command "r", which

has two absolutely equivalent forms:

r  

r =

(in both cases you can place spaces as you want). Register can be any of

above-mentioned - 24 general-purpose registers and eip.

Let us assume that the command "load" was successfully load program for

debugging.

Immediately after loading program is suspended and does not execute.

Press Ctrl+F7 (command-line analog is the command "s") to make one step

in loaded program, after that control returns to debugger which displays

new contains of registers and memory. The system call "int 40h" is considered

as one step.

Pressing Ctrl+F8 (command-line analog is the command "p") also makes step in

loaded program, but procedure calls, string operations with prefix

rep/repz/repnz and 'loop' cycles are executed as one step.

The one-step commands are used usually on single program sections,

when it is needed, for example, to regularly trace registers value and/or

some variables in memory.

The command

g 

resumes program execution and waits until control goes to eip=given address,

and in this moment suspends program. The command "g" without arguments

simply resumes execution.

To suspend program use the command "stop" (without arguments).

In the typical situation it is required that program is executed normally,

but when some conditions are satisfied, program suspends and debugger receives

control. The corresponding conditions are called breakpoints or simply breaks.

Primary type of breakpoints is to concrete address, i.e. stop execution at

eip=. Such breakpoints are set by the command

bp 

Note that if there is only one such breakpoint, there is more convenient to use

the command "g" with argument instead.

Other type of breakpoints is on access to given memory area. Maximum

numbers of such breakpoints is 4 (because hardware features of x86 processors

are used and they allows only 4).

bpm  - breaks at any access to byte at given address

bpm w  - breaks at write to byte at given address

bpmb,bpmw,bpmd  - breaks to access correspondingly to byte, word

or dword at given address. bpm ¨ bpmb are synonyms. When bpmw,bpmd are used,

address must be aligned according to correspondingly word bound (i.e. be even)

or dword bound (i.e. be divisible by 4).

bpmb,bpmw,bpmd w  - similar to break on write.

To see the list of set breakpoints use the command "bl", to obtain information

on concrete breakpoint use "bl ". Unnecessary breakpoints can be

deleted with the command "bc ", temporarily unnecessary can be

disabled by the command "bd ", when they will be needed again,

use the command "be ".

Remarks.

1. When debugging your own programs you can put in code instructions

   int3 (pay attention to absence of space!). Such instruction causes

   exception at normal run, which leads to process termination, but

   at work under debugger it is simply activated (with the message

   "int3 command at xxx"). This feature allows to not think about addresses

   to use in the commands g and/or bp.

2. All output and all input is oriented on hexadecimal scale of notation.

3. When program is executed, registers and data window shows information

   regarding to moment before resume; you can not set registers value in this

   mode. Nevertheless the command "d" in this mode shows information that

   was true in the moment of command delivery.

						diamond