kolibrios-gitea/data/en_US/docs/MTDBG.TXT

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 <full name of executable file> [<parameters>]
Examples:
load /sys/example
LOAD   /sys/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<hex_value_of_addr> <name>
(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 <full name of symbols file>
Furthermore, when the debugger executes the command "load", it checks for
presence of file with name as of loading binary and extension '.dbg'
(/sys/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 <Enter>), 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 <last program name> <last program arguments>
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 <last program name> <last program arguments>,
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 <expression>
The command "d" without arguments flicks dump window down.
The same is for code window and the command
u <expression>
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
? <expression>
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 <register> <expression>
r <register>=<expression>
(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 <expression>
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=<given value>. Such breakpoints are set by the command
bp <expression>
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 <expression> - breaks at any access to byte at given address
bpm w <expression> - breaks at write to byte at given address
bpmb,bpmw,bpmd <expression> - breaks to access correspondingly to byte, word
or dword at given address. bpm <20> 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 <expression> - similar to break on write.

To see the list of set breakpoints use the command "bl", to obtain information
on concrete breakpoint use "bl <number>". Unnecessary breakpoints can be
deleted with the command "bc <number>", temporarily unnecessary can be
disabled by the command "bd <number>", when they will be needed again,
use the command "be <number>".

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