home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / FSDB091A.ZIP / MANUAL < prev    next >
Text File  |  1994-03-14  |  14KB  |  360 lines
  1.  
  2. -------------------------------------------------------------------------
  3.               Sally Full Screen Debugger version 0,91 beta
  4. -------------------------------------------------------------------------
  5.  
  6.  
  7. 1. Introduction
  8.  
  9. This is the user's manual for Sally Full Screen Debugger, a new user
  10. interface to the old djgpp debugger.  The interface was inspired by
  11. Borland's Turbo Debugger, the very best debugger that I have ever seen.
  12. Too bad it doesn't work for 32 bit programs.
  13.  
  14. The debugger and this manual are copyright 1994 by Morten Welinder
  15. (terra@diku.dk) and are distributed under the terms of the GNU General
  16. Public License as specified in the files "fullscr.c" and "copying".  You
  17. should have received a copy of the GNU General Public License together with
  18. the debugger.
  19.  
  20. The debugger comes with no warranty what-so-ever and you use it at your own
  21. risk or not at all.  If, however, you should discover `bugs' in the program,
  22. I'd like to hear about it.  I can be reached by email as "terra@diku.dk"
  23. and by snail-mail as
  24.  
  25.         Morten Welinder
  26.         Borups Alle 249b, 3tv
  27.         DK-2400  Koebenhavn NV
  28.         DENMARK
  29.  
  30. Other kinds of feedback is also welcome, be it proposals for extensions,
  31. manual improvements, or donations.
  32.  
  33.  
  34.  
  35. 1.1 Hardware
  36.  
  37. The debugger has been tested under the following conditions only, but I
  38. expect no problems in other environments except as noted below:
  39.  
  40.         * Cpu: 486 (i.e., with fpu)
  41.         * Colour Vga screen, text mode.
  42.         * Vcpi mode of the extender.
  43.  
  44. I expect no problems when used with the 387 emulator, but without that or a
  45. fpu you should not call up the npx window.  I don't know whether it will
  46. work under Dpmi.
  47.  
  48. I have no problems with speed, even on large programs like Gnu Emacs, but
  49. some of the redisplay routines are quite greedy.  A few caches might help,
  50. but I don't feel like doing it right now.  The way it works now, I'm sure
  51. that consistency is enforced.
  52.  
  53.  
  54.  
  55. 1.2 Display modes
  56.  
  57. The debugger works with all text modes having at least 80 columns and 25
  58. rows.  The more columns and rows you've got, the more you see.  The
  59. debugger automatically adjusts itself to maximize the useful information on
  60. the screen.  Graphics mode does not work -- a little work in get_screen()
  61. and put_screen() could fix that, but it might be slow.
  62.  
  63. The debugger works with both mono and colour displays, but it certainly
  64. looks best with colour.
  65.  
  66. Unlike the original djgpp debugger, this debugger accesses the video
  67. hardware without ever going through Dos.  Therefore it does not depend on
  68. the Ansi.Sys driver for colours.  You should not use the topline display
  69. together with this debugger -- it's ugly because go32 does not provide
  70. a way for the debugger to turn it off while the debugger screen is being
  71. displayed.
  72.  
  73.  
  74.  
  75. 1.3 Installation
  76.  
  77. To install the debugger, go through the following steps
  78.  
  79.         1. Backup the files in `djgpp\go32\ed', and the binaries
  80.            in `djgpp\bin' (the files `edebug32' and `ed32-dpm').
  81.         2. Go to the djgpp\go32\ed directory.
  82.         3. Unzip the archive files.
  83.         4. Compile the debugger: "make" or "gmake" or whatever your
  84.            make utility is called.
  85.         5. Copy the new debugger executeables to the binary directory:
  86.            "copy edebug32 ..\..\bin" then "copy ed32-dpm ..\..\bin" 
  87.  
  88. You can now use the new debugger in the same way as you used to use the old
  89. one, i.e., if you want to execute "myprog 42 a:\out" under the debugger,
  90. you do
  91.  
  92.         go32 -d edebug32 myprog 42 a:\out
  93.  
  94. if you use the non-dpmi version, or 
  95.  
  96.         go32 -d ed32-dpm myprog 42 a:\out
  97.  
  98. if you are debugging under dpmi.  [Which you would be if you are running
  99. under Windows or OS/2 -- see also the section about known problems below.]
  100.  
  101.  
  102.  
  103. 1.4 Known Problems
  104.  
  105. A mysterious problem has been reported with operation under dpmi (OS/2 to
  106. be precise).  The problem does not seem to be in the debugger, but in
  107. go32.  Reportedly, it manifests itself by the debugger not working at all.
  108. The problem can be *circumvented* by changing the library source file
  109. "djgpp\libsrc\c\sys\read.s" line #25 to "ja old_way".  The library must
  110. be recompiled.
  111.  
  112. Data read breakpoints will be triggered by the debugger itself causing
  113. termination.  This is a bug in go32.  Actually the same is true for data
  114. write breakpoints, but this is rarely a problem.
  115.  
  116.  
  117.  
  118. 2. Key Bindings
  119.  
  120. This section describes the meaning of keys, which are classified either as
  121. "global" if the work no matter what the focus is, or "local" if they only
  122. work in some special pane.  Some keys have been assigned aliases; these
  123. aliases are not shown in the key descriptions here.
  124.  
  125. In version 0,90 beta of the debugger, the cursor keys on the key pad did
  126. not work.  This should now be fixed.
  127.  
  128.  
  129.  
  130. 2.1 Global Keys
  131.  
  132. The following keys are defined no matter where the current focus is.
  133.  
  134.         Tab         Go to next pane (clockwise).
  135.         BackTab     Go to previous pane.
  136.         Alt-C       Put the code pane in upper left part of the screen.
  137.         Alt-E       Evaluate expression.
  138.         Alt-I       Put the info pane in upper left part of the screen.
  139.         Alt-N       Put the npx pane in upper left part of the screen.
  140.         Alt-S       Put the stack pane in upper left part of the screen.
  141.         Alt-W       Put the whereis pane in upper left part of the screen.
  142.         Alt-X       Exit.  Your program's exit code (atexit functions) is
  143.                     *not* run so you might get trouble if you have installed
  144.                     hardware interrupt handlers.
  145.         Alt-F5      Show user program screen.  Press any key to redisplay the
  146.                     debugger screen.
  147.         F7          Single step program.
  148.         F8          Single step program, but step over calls.  As a special
  149.                     exception, F8 means "goto `_main'" if it is used before
  150.                     any instruction is executed.
  151.         F9          Run or continue program.
  152.  
  153.  
  154.  
  155. 2.2 Code Pane Keys
  156.  
  157. The following keys work when focus is in the code pane.  The code pane is
  158. selected by default and can be reselected with Alt-C.  All instructions are
  159. displayed in Intel syntax, i.e., as `instr dst,src' as opposed to the 
  160. syntax that is used by Gnu Assembler (`instr src,dst').
  161.  
  162.         Up          One instruction backwards (only 99% perfect).
  163.         Down        One instruction forwards.
  164.         PgUp        A screenful (paneful? :-) of instructions backwards.
  165.         PgDn        A screenful of instructions forwards.
  166.         Ctrl-Left   Start instruction display one byte earlier.  This is
  167.                     useful in the rare case where backward instruction scroll
  168.                     gets out of syncronization.
  169.         Ctrl-Right  Start instruction display one byte later.
  170.         Ctrl-G      Go to (i.e., display the instruction at) specified 
  171.                     address.
  172.         Ctrl-N      Set eip to instruction under cursor.  Be careful with
  173.                     this function -- it assumes that the stack is in the
  174.                     same situation before and after, and that the same set
  175.                     of variables are in the same registers.
  176.         Ctrl-O      Go to origin, i.e., current eip.
  177.         F2          Set/reset breakpoint.  Any number can be set at any time.
  178.         F4          Set temporary breakpoint at cursor and run.  Usually this
  179.                     means that the program will stop at the specified
  180.                     location, but it might also hit another breakpoint.
  181.  
  182. When a code breakpoint is triggered, it is a "fault" using the Intel
  183. terminology.  This means that the instruction is not carried through.
  184. Instructions affected by code breakpoints are shown highlighted.
  185.  
  186. I have corrected a number of bugs in the disassembly tables; the
  187. disassembly of instructions "jc", "jc", "jnc", "jnc", "setc", "setnc",
  188. "aad", and "aam" are now correct.  (No, I have not been drinking -- there
  189. are two "jc" and "jnc" instructions; figure it out yourself.)  See the file
  190. "unassmbl.c" for further details.
  191.  
  192.  
  193.  
  194. 2.3 Register Pane Keys
  195.  
  196. The following keys work when focus is in the register pane.  The register
  197. pane is always displayed.
  198.  
  199.         Up/Down     What you expect.
  200.         Other       Enter new value for register.
  201.  
  202. Note that you cannot change the flags register to an arbitrary 32-bit
  203. value; all non-user bits are masked.
  204.  
  205.  
  206.  
  207. 2.4 Flag Pane Keys
  208.  
  209. The following keys work when focus is in the flag pane.  The flag pane is
  210. always displayed.  Only user flags are present in this pane, partly
  211. because there is not enough room, and partly because a user-level program
  212. cannot reliably detect other flags and therefore should not depend on
  213. their values.
  214.  
  215.         Up/Down     What you expect.
  216.         Space       Toggle flag.
  217.         S           Set flag.
  218.         R           Reset flag.
  219.  
  220.  
  221.  
  222. 2.5 Breakpoint Pane Keys
  223.  
  224. The following keys work when focus is in the breakpoint pane.  The
  225. breakpoint pane is always displayed.
  226.  
  227.         Up/Down     What you expect.
  228.         Delete      Reset breakpoint.
  229.         Return      Go to breakpoint.
  230.  
  231.  
  232.  
  233. 2.6 Data Pane Keys
  234.  
  235. The following keys work when focus is in the data pane.  The data pane is
  236. always displayed.
  237.  
  238. When a data breakpoint is triggered, it is a "trap" using the Intel
  239. terminology.  This means that the instruction that triggeres the breakpoint
  240. will be completed first, and that eip will be left after that instruction.
  241. Bytes affected by data breakpoints are shown highlighted.  There can be
  242. only four data breakpoints active at any one time, but the display will not
  243. reflect this; if you set more than four then they simply will not be
  244. triggered, ever.
  245.  
  246. Due to a bug/feature in the current version of go32, data breakpoints as
  247. set with F2/Alt-F2 will trigger on debugger access and crash your program.
  248. (A breakpoint is actually first activated when the next instruction is
  249. executed; then it stays activated until another instruction is executed
  250. without that breakpoint set.)  Data read breakpoints are thus not very
  251. useful at this moment.  Hopefully, the next release of go32 will fix this.
  252.  
  253.         Up/Down     What you expect.
  254.         Left/Right  What you expect.
  255.         PgUp/PgDn   What you expect.
  256.         Ctrl-Left   Start data display one byte earlier.
  257.         Ctrl-Right  Start data display one byte later.
  258.         Ctrl-B      Display data as bytes.
  259.         Ctrl-C      Go to the the current instruction.
  260.         Ctrl-G      Go to specified address.
  261.         Ctrl-L      Display data as 32 bit words (`longs').
  262.         Ctrl-S      Go to the stack.
  263.         Ctrl-W      Display data as 16 bit words.
  264.         F2          Set data write breakpoint at focus.  The data size used 
  265.                     is the same as currently selected.
  266.         Alt-F2      Set data read/write breakpoint at focus.  The data size 
  267.                     used is the same as currently selected.
  268.         Other       Enter new byte values separated by commas.  String in
  269.                     double quotes imply a terminating '\0', strings in 
  270.                     single quotes do not.
  271.  
  272. For the time being at least, all data displayed in the data pane is
  273. unsigned.
  274.  
  275.  
  276.  
  277. 2.7 Npx Pane Keys
  278.  
  279. The following keys work when focus is in the npx pane.  The npx pane is not
  280. displayed by default, but can be called up with Alt-N.  The npx pane should
  281. not be called up if no floating point processor or emulator is present.
  282.  
  283.         Up/Down     What you expect.
  284.         Ctrl-E      Empty register.
  285.         Ctrl-Z      Zero register.
  286.         Ctrl-N      Negate register.
  287.         Other       Enter new value for register.
  288.  
  289.  
  290.  
  291. 2.8 Stack Pane Keys
  292.  
  293. The following keys work when focus is in the stack pane.  The stack pane
  294. is not displayed by default, but can be called up with Alt-S.
  295.  
  296.         Up/Down     What you expect.
  297.         Return      Go to code and active the code pane.
  298.  
  299.  
  300.  
  301. 2.9 Info Pane Keys
  302.  
  303. No special keys are recognized in the info pane.  The info pane is not
  304. displayed by default, but can be called up with Alt-I.
  305.  
  306.  
  307.  
  308. 2.10 Whereis Pane Keys
  309.  
  310. The following keys work when focus is in the whereis pane.  The whereis
  311. pane is not displayed by default, but can be called up with Alt-W.  When
  312. it is first called up it will be empty.
  313.  
  314.         Up/Down     What you expect.
  315.         PgUp/PgDn   What you expect.
  316.         Return      Go to the highlighted symbol, either in the code pane
  317.                     (text based symbols) or in the data pane (data or bss
  318.                     based symbols).
  319.         Other       Enter search expression.  Wildcards "*" and "?" are
  320.                     recognized.  To list all symbols, you thus enter "*".
  321.                     If ten or more symbols match, the number of matches is
  322.                     displayed.
  323.  
  324. You might fear that entering a wildcard search expression like "*" would
  325. give you more symbols that the debugger can handle.  Don't worry!  Symbols
  326. are stored in virtual memory, and not even Gnu Emacs 19.22's nearly 3000
  327. symbols cause any kind of trouble.
  328.  
  329.  
  330.  
  331. 3. To Do
  332.  
  333. I ought to do this one day, but did not feel like it right now
  334.  
  335.         * Alt-? to swap in the source in place of the disassembly.
  336.  
  337.         * Handle screen mode switch gracefully.
  338.         * Handle graphics modes.
  339.  
  340.         * F4/F8/F9 should step over breakpoint at cursor like F7 does.
  341.         * Conditional breakpoints.
  342.  
  343.         * Improve precision of npx display.
  344.         * Enhance expression evaluator.
  345.         * Debug logs.
  346.         * Restart capability.
  347.         * On-line help.
  348.         * Ctrl-Break catch.
  349.  
  350.  
  351.  
  352. 3.1 Scary Codes
  353.  
  354. These codes ought to be explained.  Nobody did.
  355.  
  356. Local Variables: ***
  357. mode: text ***
  358. fill-column: 75 ***
  359. End: ***
  360.