home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / devcon / milan_1991 / devcon91.3 / debug / readme next >
Text File  |  1992-09-01  |  18KB  |  474 lines
  1.  
  2. Debugging Tools - Choosing the Right Tool for the Job
  3.  
  4. by Carolyn Scheppner
  5.  
  6.  
  7. Note: Some of the debugging tools supplied on the Devcon disk are from 
  8. the CATS support item "Software Toolkit".  Full instructions on the use 
  9. and options of some of the more complex tools such as Wack and Wedge 
  10. may be found in the Software Toolkit manual.
  11.  
  12. General Warning: Some debugging tools stress the system, or allow you to 
  13. wedge into arbitrary system routines, or attempt to provoke improperly 
  14. written code to crash.  We have attempted to mark these kinds of tools 
  15. with warnings below.  You probably should not write to un-backed-up disks 
  16. or harddisks while using such tools. 
  17.  
  18. Unless otherwise noted, the following tools are all Copyright (c) 1985,1990 
  19. Commodore-Amiga. Inc.  All Rights Reserved.  They are provided for debugging 
  20. purposes only and may not be redistributed in any manner.
  21.  
  22. Watchdog Tools
  23.  
  24. Watchdog tools help trap illegal memory accesses.  Such accesses are 
  25. generally caused by using improperly initialized variables or structures, 
  26. or by accessing structures and memory that have already been freed.  Code 
  27. with illegal accesses may appear to run fine under most circumstances but 
  28. may fail or crash unexpectedly in the field.
  29.  
  30. Unfortunately, it is currently not possible to trap all illegal accesses.  
  31. If a program is accessing or trashing memory in normal legal user memory 
  32. spaces, or even trashing itself, these tools won't catch it in the act.  
  33. Luckily, a majority of illegal accesses reference low memory or freed 
  34. memory.  By using a freed memory invalidation tool like MungWall in 
  35. conjunction with an illegal access watchdog tool, the majority of these 
  36. problems can be caught.
  37.  
  38. The best watchdog tools require an MMU.  Processor-based tools such as 
  39. MemWatch and WatchMem can watch for writes to low memory.  But they 
  40. can't catch reads of low memory or other illegal accesses.
  41.  
  42. The new MMU-based watchdog, Enforcer, can trap all illegal 
  43. accesses of low memory, non-existent memory, and ROM,  reporting the 
  44. exact type of access, as well as the offending code's program counter 
  45. and registers.  The debugging information is sent to a serial terminal 
  46. (or parallel printer with enforcer.par).
  47.  
  48. If the illegal access occurs in ROM code, you can generally trace forward 
  49. on the stack to find the program address that called the ROM routine.  It 
  50. is then possible to disassemble a program in memory at the point it caused 
  51. the illegal access.  Programmers who like to debug at a low level may then 
  52. either immediately recognize the problem, or can compare the code 
  53. disassembled in memory to disassemblies of their object modules (or to 
  54. their source code if the source is in assembler).
  55.  
  56. Programmers who prefer to debug at a higher level can compile a debugging 
  57. version of their software to allow them to track which code is executing 
  58. when the illegal access occurs.  This can be accomplished by stepping or 
  59. breakpointing with a debugger, or by inserting remote debugging statements 
  60. (kprintf() or dprintf()) to the same remote device that is receiving the 
  61. watchdog output.  Plain printf() debugging could also be used with Delay()'s 
  62. to allow time for watching both the printf() debugging and the remote 
  63. watchdog output.
  64.  
  65. All software should be tested with a memory invalidator, such as MungWall, 
  66. running in conjunction with one of the illegal access trappers.  It is 
  67. extremely useful to use such tools while you are developing so that 
  68. you can catch illegal accesses right away - they are much easier to find 
  69. without disassembly if you just wrote or changed the code.
  70.  
  71. TOOLNAME: Enforcer and Enforcer.par
  72. CATEGORY: MMU-based Watchdog tool
  73. USAGE:    Enforcer [off|on|quiet|fprotect]
  74. USED FOR: Trapping reads and writes of low/non-existent memory 
  75. REQUIRES: MMU that is not being used, serial terminal or parallel printer 
  76. FOUND ON: Devcon disk
  77.  
  78. TOOLNAME: Lawbreaker 
  79. CATEGORY: Test program for Enforcer
  80. USAGE:    Lawbreaker 
  81. REQUIRES: Enforcer 
  82. FOUND ON: Devcon disk
  83.  
  84. TOOLNAME: WatchMem  (inspired by MemWatch by John Toebes VIII) 
  85. CATEGORY: Processor-based low memory watchdog
  86. USAGE:    RUN Watchmem [ file | window ] opt n [interval ]  (opt n = nocorrect)
  87. USED FOR: Trapping writes to low memory 
  88. WARNINGS: This processor-based tool can not prevent writes to low memory.    
  89.      It can correct them after they occur, but you might crash first. 
  90.     If you have an MMU, use Enforcer instead!  
  91. FOUND ON: Devcon disk, Software Toolkit
  92.  
  93. TOOLNAME: MungWall and Mungwall.par (combination MemMung+MemWall+Snoop++)
  94. CATEGORY: Memory invalidation and memory overwrite/underwrite monitor
  95. USAGE:    Mungwall [UPDATE] [TASK name][WAIT] [NOWAIT]
  96.                    [SNOOP] [NOSNOOP] [INFO]
  97.                    [PRESIZE] [POSTSIZE [FILLCHAR]
  98. USED FOR: Catching accesses of uninitialized and freed memory
  99.     Finding things that write past their allocated memory
  100.     Also for general snooping of memory allocations by one or all tasks
  101.     (See also SnoopStrip for filtering of snoop option output)
  102. REQUIRES: Serial terminal or parallel printer 
  103. WARNINGS: Will provoke bad code to crash if not used with Enforcer 
  104. FOUND ON: Devcon disk
  105.  
  106. TOOLNAME: MemMung 
  107. CATEGORY: Memory invalidation tool (more pleasant with Enforcer)
  108. USAGE:    RUN MemMung
  109. USED FOR: Catching accesses of uninitialized and freed memory 
  110. WARNINGS: Will provoke bad code to crash if not used with Enforcer 
  111. FOUND ON: Devcon disk, Software Toolkit
  112.  
  113. TOOLNAME: MemWall 
  114. CATEGORY: Memory allocation overwrite/underwrite monitor
  115. USAGE:    Memwall [all] [fill N] [presize N] [postsize N] [snoop] [supersnoop]
  116. USED FOR: Finding things that write past their allocated memory 
  117.     Also for general snooping of memory allocations. 
  118. REQUIRES: Serial terminal 
  119. WARNINGS: Some things in the system (such as layers) free memory in smaller chunks
  120.     than they allocated.  When this is done, (or when it finds a fill area hit), 
  121.     it does NOT let that area actually be deallocated.  This can lead to loss of 
  122.     memory.  Note that presize or postsize may be 0. 
  123. FOUND ON: Devcon Disk
  124.  
  125. TOOLNAME: Scratch (by Bill Hawes)
  126. CATEGORY: Scratch register (D1,A0,A1) invalidation tool
  127. USAGE:    See sample script scratch_all
  128. USED FOR: Will provoke code with improper register usage to fail
  129. FOUND ON: Devcon Disk (if available in time)
  130.  
  131. TOOLNAME: IO_Torture and IO_Torture.par
  132. CATEGORY: Specialized watchdog for IORequest re-use
  133. USAGE:    IO_Torture
  134. USED FOR: Remote monitoring of premature re-use of IORequests 
  135. REQUIRES: Serial terminal or parallel printer
  136. FOUND ON: Devcon disk
  137.  
  138.  
  139. Stressing Tools
  140.  
  141. Some tools are designed to cause stressful conditions for your software
  142. such as low memory and emulation of a heavy multitasking environment.
  143. Testing your software while running such tools can help turn up faulty
  144. or missing error checking code, and race conditions.
  145.  
  146. TOOLNAME: EatMem
  147. CATEGORY: Low memory test tool
  148. USAGE:    EatMem (adjust gadgets for desired amount/sizes of free memory)
  149. USED FOR: Testing software behavior under low memory conditions
  150. FOUND ON: Devcon disk
  151.  
  152. TOOLNAME: EatCycles
  153. CATEGORY: Multitasking load test tool
  154. USAGE:    EatCycles (adjust gadgets for desired load)
  155. USED FOR: Testing software behavior under heavy system load
  156. FOUND ON: Devcon disk
  157.  
  158. TOOLNAME: Memoration (by Bill Hawes)
  159. CATEGORY: Low memory test tool
  160. USAGE:    See doc file
  161. USED FOR: Selectively restricting available memory
  162. FOUND ON: Devcon Disk (if available in time)
  163.  
  164.  
  165. Monitoring Tools
  166.  
  167. TOOLNAME: Tstat 
  168. CATEGORY: Task monitor
  169. USAGE:    Tstat [CLI# | ExecTaskName | CliCommandName] [-tickdelay] 
  170. USED FOR: Monitoring PC, regs, stack, signals, etc. of a running task 
  171. FOUND ON: Devcon disk
  172.  
  173. TOOLNAME: Wedge 
  174. CATEGORY: System function monitor
  175. USAGE:    Complex and best done with scripts - type Wedge help for help
  176. USED FOR: Monitoring the calls to and results from any system function 
  177. REQUIRES: Limited local monitoring, serial or parallel for full monitoring 
  178. WARNINGS: Can bog system down; can crash if calling task has tiny stack.  
  179.     Local monitoring can cause recursive looping if functions called 
  180.     by text output routines are wedged. 
  181. FOUND ON: Devcon disk, Software Toolkit (full instructions with ToolKit)
  182.  
  183. TOOLNAME: DevMon (see DEVICE TOOLS)
  184.  
  185.  
  186. Crash Trapping Tools
  187.  
  188. TOOLNAME: SRT 
  189. CATEGORY: Software error trapping wedge (for 1.2/1.3, not 2.0)
  190. USAGE:    SRT [srt.textfile] (default s:srt.text)
  191. USED FOR: Examining name, registers, PC, SP, of crashed task 
  192. FOUND ON: Devcon Disk
  193.  
  194. TOOLNAME: TNT 
  195. CATEGORY: Software error trap handler (for all version of OS)
  196. USAGE:    TNT  (must be installed before the crash occurs)
  197. USED FOR: Examining name, registers, PC, SP, of crashed task 
  198. WARNINGS: You may need to do TNT OFF before using a trap-based debugger. 
  199. FOUND ON: Devcon disk
  200.  
  201.  
  202.  
  203. General Debuggers and Disassemblers
  204.  
  205. Many development language packages come with excellent source level 
  206. debuggers and object module disassemblers.  In addition, the following 
  207. tools are useful for debugging executables:
  208.  
  209. TOOLNAME: Wack (Originated by Carl Sassenrath) 
  210. CATEGORY: Symbolic debugger/disassembler
  211. USAGE:    Wack "program [programargs]" (see SW Toolkit for other opts)
  212. USED FOR: Disassembling, single stepping, breakpointing 
  213. WARNINGS: Improper use could lead to a crash.  Wack1.0 installs/leaves a 
  214.     trap handler.  If used with TNT, RUN Wack so only the handler of the 
  215.     bg run process will be changed. 
  216. FOUND ON: Devcon disk, Software Toolkit
  217.  
  218. TOOLNAME: RomWack 
  219. CATEGORY: ROM-based debugger
  220. USAGE:    Enter with exec Debug() function or RomWack command (SW Toolkit)
  221. USED FOR: Freezing the Amiga while you examine memory remotely 
  222. REQUIRES: Serial terminal 
  223. WARNINGS: Improper use could lead to a crash. 
  224. FOUND IN: the Amiga OS
  225.  
  226. TOOLNAME: Metascope (by Metadigm) 
  227. CATEGORY: Multiwindow Intuition interface symbolic debugger/disassembler 
  228. USED FOR: Disassembling, single stepping, breakpointing 
  229. WARNINGS: Improper use could lead to a crash. 
  230. FOUND IN: Stores (Commercial product)
  231.  
  232.  
  233. System Configuration Listers
  234.  
  235. Configuration listers are handy for checking the address, version, or 
  236. presence of various system hardware and software items. If you are working 
  237. with devices or libraries, you can use the memory tool Flush to flush 
  238. your device or library from memory and LibList or DevList will 
  239. check that the device or library has actually been removed from the system.  
  240. Config can be used to check a machine's OS and custom chip versions,  
  241. processor type, and configured devices without taking off the cover.
  242.  
  243. TOOLNAME: Config 
  244. CATEGORY: Motherboard and Autoconfig configuration lister
  245. USAGE:    Config [debug]
  246. USED FOR: Checking ROM/Processor/Chip versions, and autoconfig devices
  247.       With debug option, for checking all autoconfig params of boards. 
  248. FOUND ON: Devcon disk
  249.  
  250. TOOLNAME: TaskList, LibList, DevList, ModList, and (C. Sassenrath) IntList 
  251. CATEGORY: System software list display tools
  252. USAGE:    No arguments for any of these
  253. USED FOR: Checking address, version, presence, of tasks, libs, devs, etc. 
  254. FOUND ON: Devcon disk (see also Memory Tool "Flush")
  255.  
  256. TOOLNAME: MemList - see MEMORY TOOLS
  257.  
  258. TOOLNAME: DosList - see DOS/DISK TOOLS
  259.  
  260.  
  261. Memory Tools
  262.  
  263. Most memory tools are used to check for, and debug memory losses and other 
  264. memory allocation and deallocation problems. Avail and Flush can be used 
  265. together to make sure that an application is freeing all of its memory.  
  266. Flush is required because libraries, devices, and fonts loaded from disk 
  267. will hang around in memory even after they have been closed until someone 
  268. asks for the memory.  
  269.  
  270. To check your application for memory loss, arrange your Workbench so that 
  271. you have an open shell (for Avail) and can start your application from a 
  272. different shell or from an icon without rearranging any windows (rearranging 
  273. windows causes memory fluctuations).  If possible, size the shell window 
  274. for Avail tall enough for the output of two avails and a couple of flushes 
  275. (so that you won't have to write down any numbers).
  276.  
  277. Then, without rearranging any windows, do:
  278.  
  279.     1. Flush 
  280.     2. Avail (note these pre-application Available totals) 
  281.     3. Start your application 
  282.     4. [ optional Avail here to check run-time memory usage ] 
  283.     5. Exit your application 
  284.     6. Flush 
  285.     7. Avail (the Available totals should match the pre-application ones)
  286.  
  287.  
  288. TOOLNAME: Avail 
  289. CATEGORY: Memory free/largest lister 
  290. USAGE:    Avail (2.0 has flush opt; use Flush command with earlier Avails) 
  291. USED FOR: Checking memory usage, and memory loss in conjunction with Flush 
  292. FOUND ON: Workbench
  293.  
  294. TOOLNAME: Flush 
  295. CATEGORY: Memory flusher (to check for real memory loss)
  296. USAGE:    Flush  (Note - Flush does 3 flushes when invoked)
  297. USED FOR: Flushing all currently unused devices/libraries/fonts from memory 
  298. FOUND ON: Devcon disk (use in conjunction with Avail)
  299.  
  300. TOOLNAME: MemMon 
  301. CATEGORY: Memory use recorder (helps narrow search for lost memory)
  302. USAGE:    MemMon (>diskfile)
  303. USED FOR: Producing a commented record of memory usage  
  304. FOUND ON: Devcon disk
  305.  
  306. TOOLNAME: Frags 
  307. CATEGORY: Memory fragmentation summarizer
  308. USAGE:    Frags [full]
  309. USED FOR: Checking for memory fragmentation. 
  310. FOUND ON: Devcon disk, Software Toolkit
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318. TOOLNAME: MemList 
  319. CATEGORY: Full used and free memory chunk lister
  320. USAGE:    Memlist [>diskfile]
  321. USED FOR: Debugging fragmentation/deallocation problems 
  322. FOUND ON: Devcon disk, Extras(?)
  323.  
  324. TOOLNAME: Owner
  325. CATEGORY: Memory ownership tool
  326. USAGE:    Owner [0x] nnnn... (owner ? for help)
  327. USED FOR: Trying to determine ownership of allocated memory 
  328. FOUND ON: DevCon disk
  329.  
  330. TOOLNAME: Snoop 
  331. CATEGORY: Remote AllocMem/FreeMem debugger
  332. USAGE:    Snoop (use SnoopStrip on captured output to isolate unfreed Allocs)
  333. USED FOR: Debugging unfreed memory problems 
  334. REQUIRES: Serial terminal 
  335. FOUND ON: Devcon disk, Software Toolkit
  336.  
  337. TOOLNAME: SnoopStrip
  338. USAGE:    SnoopStrip [>outfile] infile
  339. USED FOR: Stripping matched allocs/frees from captured snoop output 
  340. FOUND ON: Devcon disk
  341.  
  342. TOOLNAME: Drip 
  343. CATEGORY: Memory loss accumulator
  344. USAGE:    Drip [threshold]
  345. USED FOR: Determining change in free memory since last invocation 
  346. FOUND ON: Devcon disk, Software Toolkit
  347.  
  348. TOOLNAME: Peek
  349. USAGE:    Peek B|W|L [0x]address [[0x]compvalue] [[0x]mask] 
  350. USED FOR: Checking or script branching on contents of a memory address 
  351. FOUND ON: Devcon disk
  352.  
  353. TOOLNAME: Poke
  354. USAGE:    Peek B|W|L [0x]address [0x]value [[0x]mask] 
  355. USED FOR: Changing the contents of a memory address 
  356. WARNINGS: Obviously, poking where you shouldn't may crash machine. 
  357. FOUND ON: Devcon disk
  358.  
  359.  
  360.  
  361.  
  362. OS/Disk Checking Tools
  363.  
  364. TOOLNAME: DosList 
  365. CATEGORY: Dos device lister
  366. USAGE:    Doslist [DEVS|VOLS|DIRS]
  367. USED FOR: Examining the dos device list 
  368. FOUND ON: Devcon disk
  369.  
  370. TOOLNAME: ShowLocks (Copyright 1988 Chuck McManis) 
  371. CATEGORY: Filelock lister
  372. USAGE:    ShowLocks [volumename:]
  373. USED FOR: Displaying outstanding locks 
  374. FOUND ON: Software Toolkit
  375.  
  376. TOOLNAME: DiskEd 
  377. CATEGORY: Disk sector editor
  378. USAGE:    DiskEd drivename:  (see Bantam AmigaDos manual for instructions)
  379. USED FOR: Examining and modifying disk sector data 
  380. WARNINGS: Improper use can trash disk data or structure. 
  381. FOUND ON: Devcon Disk
  382.  
  383.  
  384. Performance Checking Tools
  385.  
  386. TOOLNAME: PerfMon 
  387. CATEGORY: System performance monitor
  388. USAGE:    Perfmon
  389. USED FOR: Checking for busy waiting and other performance problems 
  390. FOUND ON: Devcon Disk, 1.3 Extras
  391.  
  392.  
  393. Intuition/Graphics Tools
  394.  
  395. TOOLNAME: WinList
  396. USED FOR: Examining addresses, titles, flags, sizes of screens and windows 
  397. FOUND ON: Devcon disk
  398.  
  399. TOOLNAME: ShowGfxBase
  400. USED FOR: Examining GfxBase normal display sizes and flags 
  401. FOUND ON: Devcon disk
  402.  
  403. TOOLNAME: ReadPixel
  404. USED FOR: Reading the XY screen location and color of pixels.  Can be 
  405.     used to check the size and position of onscreen images.
  406. USAGE:    Readpixel  (then click on pixels to read) 
  407. FOUND ON: Devcon disk
  408.  
  409. TOOLNAME: MKS_Lens
  410. USED FOR: Examining individual pixels of screen
  411. USAGE:    MKS_lens 
  412. FOUND ON: Devcon disk
  413.  
  414.  
  415. TOOLNAME: DevMon 
  416. CATEGORY: Device monitor
  417. USAGE:    Devmon name.device unitnum [remote] [hex] [allunits] [full] 
  418.     (remote is serial output, full has exec wedges in DoIO, ReplyMsg)
  419. USED FOR: Monitoring the calls to a device 
  420. REQUIRES: Nothing for local monitoring. Serial terminal optional (slower) 
  421. WARNINGS: Stresses system if wedged into high-usage or time-critical devices  
  422.     (such stress could lead to crashes or hangs)
  423. FOUND ON: Devcon disk
  424.  
  425. TOOLNAME: Cmd 
  426. CATEGORY: Parallel/Serial output capture tool
  427. USAGE:    Type cmd help for usage
  428. USED FOR: Debugging printer, serial, and parallel output
  429. FOUND ON: Workbench 2.0
  430.  
  431. TOOLNAME: PrinterTest 
  432. CATEGORY: Printer driver test suite
  433. USAGE:    Printertest (then answer y when the correct printer is prompted)
  434. USED FOR: Testing printer drivers 
  435. FOUND ON: Devcon disk
  436.  
  437. TOOLNAME: KTest 
  438. CATEGORY: Serial connection tester
  439. USAGE:    KTest
  440. USED FOR: Checking serial debugging setup 
  441. FOUND ON: Devcon disk
  442.  
  443. TOOLNAME: DTest 
  444. CATEGORY: Parallel connection tester
  445. USAGE:    DTest
  446. USED FOR: Checking parallel debugging setup
  447. FOUND ON: Devcon disk
  448.  
  449. TOOLNAME: IO_Torture (see WATCHDOG TOOLS)
  450.  
  451.  
  452.  
  453. Development Time Bug Prevention/Tracking Tools
  454.  
  455. TOOLNAME: RCS 
  456. CATEGORY: Source/document control
  457. USAGE:    See accompanying docs on Fish Disk 282
  458. USED FOR: Recording changes to source code and documents
  459. FOUND ON: Fish Disk 282
  460.  
  461. TOOLNAME: Autodoc 
  462. CATEGORY: Source code autodoc extractor
  463. USAGE:    See accompanying autodoc.doc
  464. USED FOR: Extracting standard function documentation from your source code 
  465. FOUND ON: Devcon disk
  466.  
  467. TOOLNAME: Bumprev 
  468. CATEGORY: Revision bumper
  469. USAGE:    Bumprev version revname  (example:  bumprev 36 my_rev)
  470. USED FOR: Updating revision include files (xxx_rev.h and xxx_rev.i) 
  471. FOUND ON: Devcon disk
  472.  
  473.  
  474.