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