Rev 2370 | Go to most recent revision | Only display areas with differences | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed
Rev 2370 | Rev 2742 | ||
---|---|---|---|
1 | Introduction. |
1 | Introduction. |
2 | 2 | ||
3 | mtdbg is a debugger for Kolibri operating system. This documentation describes |
3 | mtdbg is a debugger for Kolibri operating system. This documentation describes |
4 | debugger features and work with it. If you need some features which are |
4 | debugger features and work with it. Feel free to ask on our board (mostly |
5 | not presented yet, either write to the forum meos.sysbin.com (if you can |
- | |
6 | read russian texts) or mail me to address given in the end of this file. |
5 | in Russian, but has an English forum) -- board.kolibrios.org. |
7 | 6 | ||
8 | General description. |
7 | General description. |
9 | 8 | ||
10 | In each moment of time mtdbg can debug only one program. I will call it |
9 | In each moment of time mtdbg can debug only one program. I will call it |
11 | loaded program. If no program is loaded, overwhelming majority of debugging |
10 | loaded program. If no program is loaded, overwhelming majority of debugging |
12 | actions is disabled. |
11 | actions is disabled. |
13 | 12 | ||
14 | mtdbg is controlled by command line, entering from keyboard. Command line |
13 | mtdbg is controlled by command line, entering from keyboard. Command line |
15 | is drawn in the bottom part of debugger window. Debugger handles standard |
14 | is drawn in the bottom part of debugger window. Debugger handles standard |
16 | input keys Backspace,Delete,Home,End,left/right arrows. |
15 | input keys Backspace,Delete,Home,End,left/right arrows. |
17 | Commands are case-insensitive. Delimiter is arbitrary nonzero number of spaces. |
16 | Commands are case-insensitive. Delimiter is arbitrary nonzero number of spaces. |
18 | 17 | ||
19 | At any moment mtdbg can be terminated by command "quit" (without arguments). |
18 | At any moment mtdbg can be terminated by command "quit" (without arguments). |
20 | You can also simply press to close button in the right upper corner of window. |
19 | You can also simply press to close button in the right upper corner of window. |
21 | 20 | ||
22 | When debugger is started without command string parameters, no program is |
21 | When debugger is started without command string parameters, no program is |
23 | loaded. Also mtdbg can be started with command string, in this case it tries |
22 | loaded. Also mtdbg can be started with command string, in this case it tries |
24 | to load program with the name pointed to in first parameter in command string |
23 | to load program with the name pointed to in first parameter in command string |
25 | and parameters pointed to following (if present). |
24 | and parameters pointed to following (if present). |
26 | 25 | ||
27 | If no program is loaded, you can load a program with the command |
26 | If no program is loaded, you can load a program with the command |
28 | load |
27 | load |
29 | Examples: |
28 | Examples: |
30 | load /rd/1/example |
29 | load /rd/1/example |
31 | LOAD /rd/1/aclock w200 h200 |
30 | LOAD /rd/1/aclock w200 h200 |
32 | LoaD /hd0/1/menuetos/dosbox/dosbox |
31 | LoaD /hd0/1/menuetos/dosbox/dosbox |
33 | All that stays after first space after executable file name, is exactly passed |
32 | All that stays after first space after executable file name, is exactly passed |
34 | to program as command string. |
33 | to program as command string. |
35 | The command "load" reports result in the messages window (a little higher |
34 | The command "load" reports result in the messages window (a little higher |
36 | than command line window). If program was loaded successfully, there will |
35 | than command line window). If program was loaded successfully, there will |
37 | be the appropriate message; otherwise the message will contain error reason. |
36 | be the appropriate message; otherwise the message will contain error reason. |
38 | Most probable error is "file not found" if wrong file name is given. |
37 | Most probable error is "file not found" if wrong file name is given. |
39 | 38 | ||
40 | The debugger can load files with information on symbols in the program |
39 | The debugger can load files with information on symbols in the program |
41 | (labels, global variables) - text files, each line of which has format |
40 | (labels, global variables) - text files, each line of which has format |
42 | 0x |
41 | 0x |
43 | (lines, which do not have such format, are ignored). Such file can be created |
42 | (lines, which do not have such format, are ignored). Such file can be created |
44 | by hand or generated automatically by fasm. Evident load can be done by command |
43 | by hand or generated automatically by fasm. Evident load can be done by command |
45 | load-symbols |
44 | load-symbols |
46 | Furthermore, when the debugger executes the command "load", it checks for |
45 | Furthermore, when the debugger executes the command "load", it checks for |
47 | presence of file with name as of loading binary and extension '.dbg' |
46 | presence of file with name as of loading binary and extension '.dbg' |
48 | (/rd/1/example.dbg in the first of examples above), and if such file exists, |
47 | (/rd/1/example.dbg in the first of examples above), and if such file exists, |
49 | the debugger loads it automatically (with the message "Symbols loaded", if |
48 | the debugger loads it automatically (with the message "Symbols loaded", if |
50 | all is OK). |
49 | all is OK). |
51 | 50 | ||
52 | It can happen so that loaded program is packed. General principle of |
51 | It can happen so that loaded program is packed. General principle of |
53 | program packing is following: at first input file is packed (by some |
52 | program packing is following: at first input file is packed (by some |
54 | pack algorithm), then is appended small code which gets control at program |
53 | pack algorithm), then is appended small code which gets control at program |
55 | start, unpacks input code in the memory and then passes control to it. |
54 | start, unpacks input code in the memory and then passes control to it. |
56 | If program is packed, it "real" code is not visible and for debugging it is |
55 | If program is packed, it "real" code is not visible and for debugging it is |
57 | needed previously to pass through unpacker code. |
56 | needed previously to pass through unpacker code. |
58 | mtdbg determines most of existing packers (mxp,mxp_lzo,mxp_nrv,mtappack) |
57 | mtdbg determines most of existing packers (mxp,mxp_lzo,mxp_nrv,mtappack) |
59 | and in this case suggests to automatically go to "real" code. It is recommended |
58 | and in this case suggests to automatically go to "real" code. It is recommended |
60 | to accept (press 'y' or |
59 | to accept (press 'y' or |
61 | program is packed by something unknown the command "unpack" (without arguments) |
60 | program is packed by something unknown the command "unpack" (without arguments) |
62 | can be used. Call it only in the case when you are sure that program is packed |
61 | can be used. Call it only in the case when you are sure that program is packed |
63 | and control has not already went to main code! [Starting from Kolibri 0.6.5.0, |
62 | and control has not already went to main code! [Starting from Kolibri 0.6.5.0, |
64 | this paragraph is no more actual, because one can pack applications as all |
63 | this paragraph is no more actual, because one can pack applications as all |
65 | binary files with kpack and the unpacker code in this case is located in the |
64 | binary files with kpack and the unpacker code in this case is located in the |
66 | kernel and is transparent for debug.] |
65 | kernel and is transparent for debug.] |
67 | 66 | ||
68 | Loaded program can be terminated by the command "terminate" (without |
67 | Loaded program can be terminated by the command "terminate" (without |
69 | arguments). The command "detach" (without arguments) detaches from program, |
68 | arguments). The command "detach" (without arguments) detaches from program, |
70 | after that program continues execution normally, as if there was no debugger. |
69 | after that program continues execution normally, as if there was no debugger. |
71 | After both this commands program stops to be debugged. |
70 | After both this commands program stops to be debugged. |
72 | 71 | ||
73 | It is possible to anew load program for debugging by the command "reload" |
72 | It is possible to anew load program for debugging by the command "reload" |
74 | (without arguments). If there is already loaded program, it is terminated |
73 | (without arguments). If there is already loaded program, it is terminated |
75 | and new instance is started (from the beginning) (with the same command |
74 | and new instance is started (from the beginning) (with the same command |
76 | string), in this case the command is similar to the commands |
75 | string), in this case the command is similar to the commands |
77 | terminate |
76 | terminate |
78 | load |
77 | load |
79 | Otherwise is loaded anew latest program, which was debugged (in the current |
78 | Otherwise is loaded anew latest program, which was debugged (in the current |
80 | seance of work with mtdbg) (with the same command string), i.e. is similar to |
79 | seance of work with mtdbg) (with the same command string), i.e. is similar to |
81 | load |
80 | load |
82 | but the command "reload" in both cases is shorter and more convenient; |
81 | but the command "reload" in both cases is shorter and more convenient; |
83 | moreover, "load" thinks that new program is loaded and moves data window |
82 | moreover, "load" thinks that new program is loaded and moves data window |
84 | (see below) to zero address, and "reload" keeps current address. |
83 | (see below) to zero address, and "reload" keeps current address. |
85 | 84 | ||
86 | The command "help", which can be shorten to "h", is always available. |
85 | The command "help", which can be shorten to "h", is always available. |
87 | All commands are divided on groups. |
86 | All commands are divided on groups. |
88 | "help" without arguments displays the list of command groups. |
87 | "help" without arguments displays the list of command groups. |
89 | "help" with group name displays the list of commands in this group with short |
88 | "help" with group name displays the list of commands in this group with short |
90 | comments. |
89 | comments. |
91 | "help" with command name displays information about given command. |
90 | "help" with command name displays information about given command. |
92 | Examples: |
91 | Examples: |
93 | help |
92 | help |
94 | help control |
93 | help control |
95 | h LoaD |
94 | h LoaD |
96 | 95 | ||
97 | The debugger window consists from the following items enumerated from up |
96 | The debugger window consists from the following items enumerated from up |
98 | to down: |
97 | to down: |
99 | - status string. If there is loaded program, shows its name and state |
98 | - status string. If there is loaded program, shows its name and state |
100 | ("Running/Paused"), otherwise reports "No program loaded". |
99 | ("Running/Paused"), otherwise reports "No program loaded". |
101 | - registers window - shows values of general-purpose registers, register eip |
100 | - registers window - shows values of general-purpose registers, register eip |
102 | and states of single flags: CF,PF,AF,ZF,SF,DF,OF: if flag is cleared, then |
101 | and states of single flags: CF,PF,AF,ZF,SF,DF,OF: if flag is cleared, then |
103 | is displayed lower-case letter, if flag is set, then upper-case one. |
102 | is displayed lower-case letter, if flag is set, then upper-case one. |
104 | Registers which are changed from previous moment are highlighted in green. |
103 | Registers which are changed from previous moment are highlighted in green. |
105 | - data window (dump window) - shows memory contains of loaded program |
104 | - data window (dump window) - shows memory contains of loaded program |
106 | - code window (disassembler window) - shows program code as disassembled |
105 | - code window (disassembler window) - shows program code as disassembled |
107 | instructions |
106 | instructions |
108 | - messages window |
107 | - messages window |
109 | - command line window |
108 | - command line window |
110 | 109 | ||
111 | Dump window can display data starting from any address, to this serves |
110 | Dump window can display data starting from any address, to this serves |
112 | the command |
111 | the command |
113 | d |
112 | d |
114 | The command "d" without arguments flicks dump window down. |
113 | The command "d" without arguments flicks dump window down. |
115 | The same is for code window and the command |
114 | The same is for code window and the command |
116 | u |
115 | u |
117 | or simply "u". |
116 | or simply "u". |
118 | Examples: |
117 | Examples: |
119 | d esi - displays data at address esi (e.g. is useful before execution of |
118 | d esi - displays data at address esi (e.g. is useful before execution of |
120 | instruction rep movsb) |
119 | instruction rep movsb) |
121 | d esp - displays stack |
120 | d esp - displays stack |
122 | u eip - disassembles instruction starting from the current |
121 | u eip - disassembles instruction starting from the current |
123 | 122 | ||
124 | Expressions in mtdbg can include |
123 | Expressions in mtdbg can include |
125 | - hexadecimal constants |
124 | - hexadecimal constants |
126 | - names of all general-purpose registers (8 32-bits, 8 16-bits and |
125 | - names of all general-purpose registers (8 32-bits, 8 16-bits and |
127 | 8 8-bits) and register eip; values of 16- and 8-bits registers are padded |
126 | 8 8-bits) and register eip; values of 16- and 8-bits registers are padded |
128 | with zeroes to 32 bits |
127 | with zeroes to 32 bits |
129 | - four arithmetic operations +,-,*,/ (with standard priorities) and |
128 | - four arithmetic operations +,-,*,/ (with standard priorities) and |
130 | brackets |
129 | brackets |
131 | - [if symbols information was loaded] names, loaded from dbg-file |
130 | - [if symbols information was loaded] names, loaded from dbg-file |
132 | All calculations are realized modulo 2^32. |
131 | All calculations are realized modulo 2^32. |
133 | Examples of expressions: |
132 | Examples of expressions: |
134 | eax |
133 | eax |
135 | eip+2 |
134 | eip+2 |
136 | ecx-esi-1F |
135 | ecx-esi-1F |
137 | al+AH*bl |
136 | al+AH*bl |
138 | ax + 2* bH*(eip+a73) |
137 | ax + 2* bH*(eip+a73) |
139 | 3*esi*di/EAX |
138 | 3*esi*di/EAX |
140 | The command |
139 | The command |
141 | ? |
140 | ? |
142 | calculates value of specified expression. |
141 | calculates value of specified expression. |
143 | 142 | ||
144 | Values of registers in loaded program can be changed by the command "r", which |
143 | Values of registers in loaded program can be changed by the command "r", which |
145 | has two absolutely equivalent forms: |
144 | has two absolutely equivalent forms: |
146 | r |
145 | r |
147 | r |
146 | r |
148 | (in both cases you can place spaces as you want). Register can be any of |
147 | (in both cases you can place spaces as you want). Register can be any of |
149 | above-mentioned - 24 general-purpose registers and eip. |
148 | above-mentioned - 24 general-purpose registers and eip. |
150 | 149 | ||
151 | 150 | ||
152 | Let us assume that the command "load" was successfully load program for |
151 | Let us assume that the command "load" was successfully load program for |
153 | debugging. |
152 | debugging. |
154 | Immediately after loading program is suspended and does not execute. |
153 | Immediately after loading program is suspended and does not execute. |
155 | Press Ctrl+F7 (command-line analog is the command "s") to make one step |
154 | Press Ctrl+F7 (command-line analog is the command "s") to make one step |
156 | in loaded program, after that control returns to debugger which displays |
155 | in loaded program, after that control returns to debugger which displays |
157 | new contains of registers and memory. The system call "int 40h" is considered |
156 | new contains of registers and memory. The system call "int 40h" is considered |
158 | as one step. |
157 | as one step. |
159 | Pressing Ctrl+F8 (command-line analog is the command "p") also makes step in |
158 | Pressing Ctrl+F8 (command-line analog is the command "p") also makes step in |
160 | loaded program, but procedure calls, string operations with prefix |
159 | loaded program, but procedure calls, string operations with prefix |
161 | rep/repz/repnz and 'loop' cycles are executed as one step. |
160 | rep/repz/repnz and 'loop' cycles are executed as one step. |
162 | The one-step commands are used usually on single program sections, |
161 | The one-step commands are used usually on single program sections, |
163 | when it is needed, for example, to regularly trace registers value and/or |
162 | when it is needed, for example, to regularly trace registers value and/or |
164 | some variables in memory. |
163 | some variables in memory. |
165 | The command |
164 | The command |
166 | g |
165 | g |
167 | resumes program execution and waits until control goes to eip=given address, |
166 | resumes program execution and waits until control goes to eip=given address, |
168 | and in this moment suspends program. The command "g" without arguments |
167 | and in this moment suspends program. The command "g" without arguments |
169 | simply resumes execution. |
168 | simply resumes execution. |
170 | 169 | ||
171 | To suspend program use the command "stop" (without arguments). |
170 | To suspend program use the command "stop" (without arguments). |
172 | 171 | ||
173 | In the typical situation it is required that program is executed normally, |
172 | In the typical situation it is required that program is executed normally, |
174 | but when some conditions are satisfied, program suspends and debugger receives |
173 | but when some conditions are satisfied, program suspends and debugger receives |
175 | control. The corresponding conditions are called breakpoints or simply breaks. |
174 | control. The corresponding conditions are called breakpoints or simply breaks. |
176 | Primary type of breakpoints is to concrete address, i.e. stop execution at |
175 | Primary type of breakpoints is to concrete address, i.e. stop execution at |
177 | eip= |
176 | eip= |
178 | bp |
177 | bp |
179 | Note that if there is only one such breakpoint, there is more convenient to use |
178 | Note that if there is only one such breakpoint, there is more convenient to use |
180 | the command "g" with argument instead. |
179 | the command "g" with argument instead. |
181 | 180 | ||
182 | Other type of breakpoints is on access to given memory area. Maximum |
181 | Other type of breakpoints is on access to given memory area. Maximum |
183 | numbers of such breakpoints is 4 (because hardware features of x86 processors |
182 | numbers of such breakpoints is 4 (because hardware features of x86 processors |
184 | are used and they allows only 4). |
183 | are used and they allows only 4). |
185 | bpm |
184 | bpm |
186 | bpm w |
185 | bpm w |
187 | bpmb,bpmw,bpmd |
186 | bpmb,bpmw,bpmd |
188 | or dword at given address. bpm ¨ bpmb are synonyms. When bpmw,bpmd are used, |
187 | or dword at given address. bpm ¨ bpmb are synonyms. When bpmw,bpmd are used, |
189 | address must be aligned according to correspondingly word bound (i.e. be even) |
188 | address must be aligned according to correspondingly word bound (i.e. be even) |
190 | or dword bound (i.e. be divisible by 4). |
189 | or dword bound (i.e. be divisible by 4). |
191 | bpmb,bpmw,bpmd w |
190 | bpmb,bpmw,bpmd w |
192 | 191 | ||
193 | To see the list of set breakpoints use the command "bl", to obtain information |
192 | To see the list of set breakpoints use the command "bl", to obtain information |
194 | on concrete breakpoint use "bl |
193 | on concrete breakpoint use "bl |
195 | deleted with the command "bc |
194 | deleted with the command "bc |
196 | disabled by the command "bd |
195 | disabled by the command "bd |
197 | use the command "be |
196 | use the command "be |
198 | 197 | ||
199 | Remarks. |
198 | Remarks. |
200 | 199 | ||
201 | 1. When debugging your own programs you can put in code instructions |
200 | 1. When debugging your own programs you can put in code instructions |
202 | int3 (pay attention to absence of space!). Such instruction causes |
201 | int3 (pay attention to absence of space!). Such instruction causes |
203 | exception at normal run, which leads to process termination, but |
202 | exception at normal run, which leads to process termination, but |
204 | at work under debugger it is simply activated (with the message |
203 | at work under debugger it is simply activated (with the message |
205 | "int3 command at xxx"). This feature allows to not think about addresses |
204 | "int3 command at xxx"). This feature allows to not think about addresses |
206 | to use in the commands g and/or bp. |
205 | to use in the commands g and/or bp. |
207 | 2. All output and all input is oriented on hexadecimal scale of notation. |
206 | 2. All output and all input is oriented on hexadecimal scale of notation. |
208 | 3. When program is executed, registers and data window shows information |
207 | 3. When program is executed, registers and data window shows information |
209 | regarding to moment before resume; you can not set registers value in this |
208 | regarding to moment before resume; you can not set registers value in this |
210 | mode. Nevertheless the command "d" in this mode shows information that |
209 | mode. Nevertheless the command "d" in this mode shows information that |
211 | was true in the moment of command delivery. |
210 | was true in the moment of command delivery. |
212 | 211 | ||
213 | diamond |
212 | diamond |
214 | mailto:diamondz@land.ru |
- |