Subversion Repositories Kolibri OS

Rev

Rev 2742 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed

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