home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 138.lha / LDebugDemo / ldebug.doc < prev    next >
Encoding:
Text File  |  1986-11-20  |  8.7 KB  |  199 lines
  1.  
  2. **********************************************************************
  3. **********************************************************************
  4. **********************************************************************
  5.  
  6. LDebug -- Source level & symbolic debugger for the Lattice C compiler
  7.  
  8. **********************************************************************
  9. **********************************************************************
  10. **********************************************************************
  11.  
  12. Available from:
  13.  
  14. SoftCircuits Inc.
  15. 701 Nw 13th Street, Suite C-4
  16. Boca Raton, Florida, USA
  17. 33432
  18.  
  19. For information call:
  20. 407-368-7024   9am - 12 noon / 1pm - 5pm Eastern
  21.  
  22.  
  23.  
  24. Information about LDebug V2.0 demo:
  25.  
  26. **********************************************************************
  27. **********************************************************************
  28. **********************************************************************
  29.  
  30. This demo lets you see what LDebug V2.0 can do.
  31.  
  32. It allows you to load your program and trace by individual source line
  33. or 68000 instruction.
  34.  
  35. Note: The trace source and trace instruction items may be selected from the
  36.       menu with the mouse or use the command key sequences of <Right Amiga><T>
  37.       or <Right Amiga><I>.  The latter is much quicker! In the release
  38.       version of LDebug 2.0 you may also use the function keys to control
  39.       stepping thru the source. The function keys are disabled in the
  40.       demo version.
  41.  
  42.       When you run the demo with the included test program you may get a
  43.       warning from the debugger that the source file has been updated since
  44.       the last link.  This is due to the fact that the dates have been changed
  45.       from the copying of the source and executable files and the time of
  46.       the source file is more recent than the time of the executable.
  47.        
  48.  
  49. Installation:
  50.  
  51. The program Startit should be placed in the LC: directory that contains your
  52. compiler and compiler utilities.  If you have no LC: directory, you may use
  53. the cli command ASSIGN to assign LC: to the directory that Startit is in.
  54. Startit is run by the debugger for communication between the debugger and the
  55. program being debugged.  It is not written to run without LDebug and should
  56. never be executed by you directly.
  57.  
  58.  
  59. Note:  Programs linked for use with LDebug must be linked WITHOUT the
  60.        SMALLCODE option on Blink versions before 7.2.
  61.        Blink versions prior to 7.2 did not properly combine the HUNK_DEBUG
  62.        hunks in the executable file when SMALLCODE was specified.
  63.  
  64. LDebug V2.0 works as follows:
  65.  
  66. All available 'C' source modules compiled with the -d option are loaded
  67. automatically and their names make-up menu selections under the Source menu
  68. item.  It aquires the source module names from the Hunk_debug blocks in the
  69. executable program. 
  70.  
  71. Selecting the appropriate source menu item will display the source file with
  72. line-numbers on the left side.  The window title tells what source module is
  73. being displayed.  Clicking on the line number will automatically set a
  74. breakpoint (and display the address if the breakpoint window is open) and
  75. highlight the selected line.  Double clicking on the source code itself will
  76. open a window and disassemble the 68000 code that the line of source produces.
  77. The disassembly also includes the source code lines interspersed with the
  78. assembly code similar to what OMD does.  All known symbols are resolved in the
  79. disassembly so that it is more meaningful to the user.  For example a line may
  80. look like:  JSR _printf.
  81.  
  82. With the disassembly window open it is interesting to trace by instruction
  83. and watch the code execution and register updating.  When tracing by
  84. instruction the next instruction to be executed will be outlined just as in
  85. the source window.  As you trace by instruction, you may also note that the
  86. source window is being updated as the next source line is reached.
  87.  
  88. Memory may be displayed by entering an address into the Memory gadget in
  89. the Register display area or entering M ADDRESS | SYMBOLNAME on the
  90. command line.
  91.  
  92. LDebug V2.0 allows memory to be edited directly in the memory display
  93. window.  A cursor appears when the user clicks on the desired memory
  94. location and this indicates that the memory window is in the edit mode.
  95. The user may then enter either hex digits in the hex display area or ASCII
  96. characters in the ASCII display area.  The actual editing of memory is
  97. disabled in this demo.
  98.  
  99. The contents of the 68000 registers may be changed by clicking in the desired
  100. register gadget and editing the hex number displayed there.  It is recommended
  101. that you have a good understanding of what you are modifying because if not
  102. careful, you may bring the system down.
  103.  
  104. When disassembling or displaying memory, any address shown that is out of the
  105. space of the loaded segments for the program is displayed in workbench color
  106. #3 (usually orange).  This was done so the user knows when he steps past the
  107. end of the segment.
  108.  
  109. Breakpoints may be entered by address in the BreakPoint Window.  A corresponding
  110. repeat count may also be entered.  Selecting Add from the Breakoint Window will
  111. add the entered address into the list of breakpoints.  Upto 256 breakpoints may
  112. be entered.  Breakpoints in the Source and Disassembly windows are written in
  113. workbench color #2 (usually black) to inform the user that a breakpoint is set
  114. there.  To delete a breakpoint, click on the Source or Disassembly line that
  115. has the breakpoint already set or click on its address in the Breakpoint
  116. Window and then click on Delete.  If desired, a repeat count may be specified
  117. for each breakpoint.  This will not stop execution of the users program until
  118. the breakpoint repeat count has been exhausted.  This is handy for loops
  119. where the user wishes to stop the program when a section of code will be
  120. executed for say, the 40th time.  
  121.  
  122. The breakpoints that are set from clicking on a line of source may be saved
  123. to a file.  This is very handy for automatically setting them in the next
  124. debugging session.
  125.  
  126. Athough you may set breakpoints in the demo, they are of little value since
  127. the GO! command is disabled.  When a window is closed, the debugger remembers
  128. the size and location so that when it gets opened again, it will hopefully be
  129. in the desired area on the screen.
  130.  
  131. *****************************************************************************
  132.  
  133. To start the debugger, cd to the directory in which the executable program
  134. to debug and its corresponding 'C' source files are located.
  135. Then, from cli enter:
  136.  
  137. 1> LDebugdemo [-sxxxx] filename [arg1] [arg2] [arg3] ... [argN]
  138.  
  139.     The optional -sxxxx sets the size of the debuggers internal
  140.             symbol table to xxxx bytes.  (xxxx is a decimal number)
  141.  
  142.     filename is the name of the executable file to debug
  143.  
  144. If the -sxxxx is not specified, LDebug V2.0 autosizes the symboltable by
  145. making an initial pass through the executable file.
  146.  
  147. Included is a sample program to use the debugger demo on.  It is composed of
  148. two modules: Test.c and Module1.c .  These were compiled with the -d option
  149. to put debugging information in them and were linked WITHOUT SMALLCODE.
  150.  
  151. To debug the program Test, enter the following command:
  152.  
  153.   1> LDebugdemo Test this is a test
  154.  
  155. This will debug the program disassem with an argument list of "this is a test"
  156. passed to the disassem program.
  157.  
  158. There are several commands currently supported by the command line. They are:
  159.  
  160.     D xxxxxx        : Disassembles code at the given address
  161.                           where xxxxxx is an address or symbol name. 
  162.  
  163.     M xxxxxx        : Displays Memory at the given address
  164.                           where xxxxxx is an address or symbol name. 
  165.  
  166.     G [xxxxxx]        : DISABLED IN DEMO
  167.                           Go!  starts executing code in the program
  168.                                being debugged at the optional address or
  169.                                symbol name. 
  170.  
  171.     T [xx]              : DISABLED IN DEMO
  172.                            Trace for [xx] number of sourcecode lines.
  173.                            If no [xx] given, trace 1 line.
  174.  
  175.     I [xx]              : DISABLED IN DEMO
  176.                            Trace for [xx] number of 68000 instructions.
  177.                            If no [xx] given, trace 1 instruction.
  178.  
  179.     ? SYMBOLNAME[,Nx]    : DISABLED IN DEMO
  180.                           This prints the value of the given
  181.                           SYMBOLNAME (Note: lattice 'c' pre-pends
  182.                           "_" to all symbol names generated by the
  183.                           compiler).  The optional Nx  specifies
  184.                           the width of the symbol and the printing
  185. format.
  186.  
  187. Valid print formats are d,x,c,f,s.
  188.  
  189. These correspond to decimal, hex, char,
  190. float and string respectively.
  191.  
  192. Valid widths are 1,2,4,8.
  193.  
  194.  
  195. To enter a hexadecimal address on the command line, use the C syntax of
  196. starting the hex number with "0x".
  197.  
  198. ******************************************************************************
  199.