
Debugging Tools - Choosing the Right Tool for the Job

by Carolyn Scheppner


Note: Some of the debugging tools supplied on the Devcon disk are from 
the CATS support item "Software Toolkit".  Full instructions on the use 
and options of some of the more complex tools such as Wack and Wedge 
may be found in the Software Toolkit manual.

General Warning: Some debugging tools stress the system, or allow you to 
wedge into arbitrary system routines, or attempt to provoke improperly 
written code to crash.  We have attempted to mark these kinds of tools 
with warnings below.  You probably should not write to un-backed-up disks 
or harddisks while using such tools. 

Unless otherwise noted, the following tools are all Copyright (c) 1985,1990 
Commodore-Amiga. Inc.  All Rights Reserved.  They are provided for debugging 
purposes only and may not be redistributed in any manner.

Watchdog Tools

Watchdog tools help trap illegal memory accesses.  Such accesses are 
generally caused by using improperly initialized variables or structures, 
or by accessing structures and memory that have already been freed.  Code 
with illegal accesses may appear to run fine under most circumstances but 
may fail or crash unexpectedly in the field.

Unfortunately, it is currently not possible to trap all illegal accesses.  
If a program is accessing or trashing memory in normal legal user memory 
spaces, or even trashing itself, these tools won't catch it in the act.  
Luckily, a majority of illegal accesses reference low memory or freed 
memory.  By using a freed memory invalidation tool like MungWall in 
conjunction with an illegal access watchdog tool, the majority of these 
problems can be caught.

The best watchdog tools require an MMU.  Processor-based tools such as 
MemWatch and WatchMem can watch for writes to low memory.  But they 
can't catch reads of low memory or other illegal accesses.

The new MMU-based watchdog, Enforcer, can trap all illegal 
accesses of low memory, non-existent memory, and ROM,  reporting the 
exact type of access, as well as the offending code's program counter 
and registers.  The debugging information is sent to a serial terminal 
(or parallel printer with enforcer.par).

If the illegal access occurs in ROM code, you can generally trace forward 
on the stack to find the program address that called the ROM routine.  It 
is then possible to disassemble a program in memory at the point it caused 
the illegal access.  Programmers who like to debug at a low level may then 
either immediately recognize the problem, or can compare the code 
disassembled in memory to disassemblies of their object modules (or to 
their source code if the source is in assembler).

Programmers who prefer to debug at a higher level can compile a debugging 
version of their software to allow them to track which code is executing 
when the illegal access occurs.  This can be accomplished by stepping or 
breakpointing with a debugger, or by inserting remote debugging statements 
(kprintf() or dprintf()) to the same remote device that is receiving the 
watchdog output.  Plain printf() debugging could also be used with Delay()'s 
to allow time for watching both the printf() debugging and the remote 
watchdog output.

All software should be tested with a memory invalidator, such as MungWall, 
running in conjunction with one of the illegal access trappers.  It is 
extremely useful to use such tools while you are developing so that 
you can catch illegal accesses right away - they are much easier to find 
without disassembly if you just wrote or changed the code.

TOOLNAME: Enforcer and Enforcer.par
CATEGORY: MMU-based Watchdog tool
USAGE:    Enforcer [off|on|quiet|fprotect]
USED FOR: Trapping reads and writes of low/non-existent memory 
REQUIRES: MMU that is not being used, serial terminal or parallel printer 
FOUND ON: Devcon disk

TOOLNAME: Lawbreaker 
CATEGORY: Test program for Enforcer
USAGE:    Lawbreaker 
REQUIRES: Enforcer 
FOUND ON: Devcon disk

TOOLNAME: WatchMem  (inspired by MemWatch by John Toebes VIII) 
CATEGORY: Processor-based low memory watchdog
USAGE:    RUN Watchmem [ file | window ] opt n [interval ]  (opt n = nocorrect)
USED FOR: Trapping writes to low memory 
WARNINGS: This processor-based tool can not prevent writes to low memory.    
 	It can correct them after they occur, but you might crash first. 
	If you have an MMU, use Enforcer instead!  
FOUND ON: Devcon disk, Software Toolkit

TOOLNAME: MungWall and Mungwall.par (combination MemMung+MemWall+Snoop++)
CATEGORY: Memory invalidation and memory overwrite/underwrite monitor
USAGE:    Mungwall [UPDATE] [TASK name][WAIT] [NOWAIT]
                   [SNOOP] [NOSNOOP] [INFO]
                   [PRESIZE] [POSTSIZE [FILLCHAR]
USED FOR: Catching accesses of uninitialized and freed memory
    Finding things that write past their allocated memory
    Also for general snooping of memory allocations by one or all tasks
    (See also SnoopStrip for filtering of snoop option output)
REQUIRES: Serial terminal or parallel printer 
WARNINGS: Will provoke bad code to crash if not used with Enforcer 
FOUND ON: Devcon disk

TOOLNAME: MemMung 
CATEGORY: Memory invalidation tool (more pleasant with Enforcer)
USAGE:    RUN MemMung
USED FOR: Catching accesses of uninitialized and freed memory 
WARNINGS: Will provoke bad code to crash if not used with Enforcer 
FOUND ON: Devcon disk, Software Toolkit

TOOLNAME: MemWall 
CATEGORY: Memory allocation overwrite/underwrite monitor
USAGE:    Memwall [all] [fill N] [presize N] [postsize N] [snoop] [supersnoop]
USED FOR: Finding things that write past their allocated memory 
    Also for general snooping of memory allocations. 
REQUIRES: Serial terminal 
WARNINGS: Some things in the system (such as layers) free memory in smaller chunks
    than they allocated.  When this is done, (or when it finds a fill area hit), 
    it does NOT let that area actually be deallocated.  This can lead to loss of 
    memory.  Note that presize or postsize may be 0. 
FOUND ON: Devcon Disk

TOOLNAME: Scratch (by Bill Hawes)
CATEGORY: Scratch register (D1,A0,A1) invalidation tool
USAGE:    See sample script scratch_all
USED FOR: Will provoke code with improper register usage to fail
FOUND ON: Devcon Disk (if available in time)

TOOLNAME: IO_Torture and IO_Torture.par
CATEGORY: Specialized watchdog for IORequest re-use
USAGE:    IO_Torture
USED FOR: Remote monitoring of premature re-use of IORequests 
REQUIRES: Serial terminal or parallel printer
FOUND ON: Devcon disk


Stressing Tools

Some tools are designed to cause stressful conditions for your software
such as low memory and emulation of a heavy multitasking environment.
Testing your software while running such tools can help turn up faulty
or missing error checking code, and race conditions.

TOOLNAME: EatMem
CATEGORY: Low memory test tool
USAGE:    EatMem (adjust gadgets for desired amount/sizes of free memory)
USED FOR: Testing software behavior under low memory conditions
FOUND ON: Devcon disk

TOOLNAME: EatCycles
CATEGORY: Multitasking load test tool
USAGE:    EatCycles (adjust gadgets for desired load)
USED FOR: Testing software behavior under heavy system load
FOUND ON: Devcon disk

TOOLNAME: Memoration (by Bill Hawes)
CATEGORY: Low memory test tool
USAGE:    See doc file
USED FOR: Selectively restricting available memory
FOUND ON: Devcon Disk (if available in time)


Monitoring Tools

TOOLNAME: Tstat 
CATEGORY: Task monitor
USAGE:    Tstat [CLI# | ExecTaskName | CliCommandName] [-tickdelay] 
USED FOR: Monitoring PC, regs, stack, signals, etc. of a running task 
FOUND ON: Devcon disk

TOOLNAME: Wedge 
CATEGORY: System function monitor
USAGE:    Complex and best done with scripts - type Wedge help for help
USED FOR: Monitoring the calls to and results from any system function 
REQUIRES: Limited local monitoring, serial or parallel for full monitoring 
WARNINGS: Can bog system down; can crash if calling task has tiny stack.  
    Local monitoring can cause recursive looping if functions called 
    by text output routines are wedged. 
FOUND ON: Devcon disk, Software Toolkit (full instructions with ToolKit)

TOOLNAME: DevMon (see DEVICE TOOLS)


Crash Trapping Tools

TOOLNAME: SRT 
CATEGORY: Software error trapping wedge (for 1.2/1.3, not 2.0)
USAGE:    SRT [srt.textfile] (default s:srt.text)
USED FOR: Examining name, registers, PC, SP, of crashed task 
FOUND ON: Devcon Disk

TOOLNAME: TNT 
CATEGORY: Software error trap handler (for all version of OS)
USAGE:    TNT  (must be installed before the crash occurs)
USED FOR: Examining name, registers, PC, SP, of crashed task 
WARNINGS: You may need to do TNT OFF before using a trap-based debugger. 
FOUND ON: Devcon disk



General Debuggers and Disassemblers

Many development language packages come with excellent source level 
debuggers and object module disassemblers.  In addition, the following 
tools are useful for debugging executables:

TOOLNAME: Wack (Originated by Carl Sassenrath) 
CATEGORY: Symbolic debugger/disassembler
USAGE:    Wack "program [programargs]" (see SW Toolkit for other opts)
USED FOR: Disassembling, single stepping, breakpointing 
WARNINGS: Improper use could lead to a crash.  Wack1.0 installs/leaves a 
    trap handler.  If used with TNT, RUN Wack so only the handler of the 
    bg run process will be changed. 
FOUND ON: Devcon disk, Software Toolkit

TOOLNAME: RomWack 
CATEGORY: ROM-based debugger
USAGE:    Enter with exec Debug() function or RomWack command (SW Toolkit)
USED FOR: Freezing the Amiga while you examine memory remotely 
REQUIRES: Serial terminal 
WARNINGS: Improper use could lead to a crash. 
FOUND IN: the Amiga OS

TOOLNAME: Metascope (by Metadigm) 
CATEGORY: Multiwindow Intuition interface symbolic debugger/disassembler 
USED FOR: Disassembling, single stepping, breakpointing 
WARNINGS: Improper use could lead to a crash. 
FOUND IN: Stores (Commercial product)


System Configuration Listers

Configuration listers are handy for checking the address, version, or 
presence of various system hardware and software items. If you are working 
with devices or libraries, you can use the memory tool Flush to flush 
your device or library from memory and LibList or DevList will 
check that the device or library has actually been removed from the system.  
Config can be used to check a machine's OS and custom chip versions,  
processor type, and configured devices without taking off the cover.

TOOLNAME: Config 
CATEGORY: Motherboard and Autoconfig configuration lister
USAGE:    Config [debug]
USED FOR: Checking ROM/Processor/Chip versions, and autoconfig devices
      With debug option, for checking all autoconfig params of boards. 
FOUND ON: Devcon disk

TOOLNAME: TaskList, LibList, DevList, ModList, and (C. Sassenrath) IntList 
CATEGORY: System software list display tools
USAGE:    No arguments for any of these
USED FOR: Checking address, version, presence, of tasks, libs, devs, etc. 
FOUND ON: Devcon disk (see also Memory Tool "Flush")

TOOLNAME: MemList - see MEMORY TOOLS

TOOLNAME: DosList - see DOS/DISK TOOLS


Memory Tools

Most memory tools are used to check for, and debug memory losses and other 
memory allocation and deallocation problems. Avail and Flush can be used 
together to make sure that an application is freeing all of its memory.  
Flush is required because libraries, devices, and fonts loaded from disk 
will hang around in memory even after they have been closed until someone 
asks for the memory.  

To check your application for memory loss, arrange your Workbench so that 
you have an open shell (for Avail) and can start your application from a 
different shell or from an icon without rearranging any windows (rearranging 
windows causes memory fluctuations).  If possible, size the shell window 
for Avail tall enough for the output of two avails and a couple of flushes 
(so that you won't have to write down any numbers).

Then, without rearranging any windows, do:

    1. Flush 
    2. Avail (note these pre-application Available totals) 
    3. Start your application 
    4. [ optional Avail here to check run-time memory usage ] 
    5. Exit your application 
    6. Flush 
    7. Avail (the Available totals should match the pre-application ones)


TOOLNAME: Avail 
CATEGORY: Memory free/largest lister 
USAGE:    Avail (2.0 has flush opt; use Flush command with earlier Avails) 
USED FOR: Checking memory usage, and memory loss in conjunction with Flush 
FOUND ON: Workbench

TOOLNAME: Flush 
CATEGORY: Memory flusher (to check for real memory loss)
USAGE:    Flush  (Note - Flush does 3 flushes when invoked)
USED FOR: Flushing all currently unused devices/libraries/fonts from memory 
FOUND ON: Devcon disk (use in conjunction with Avail)

TOOLNAME: MemMon 
CATEGORY: Memory use recorder (helps narrow search for lost memory)
USAGE:    MemMon (>diskfile)
USED FOR: Producing a commented record of memory usage  
FOUND ON: Devcon disk

TOOLNAME: Frags 
CATEGORY: Memory fragmentation summarizer
USAGE:    Frags [full]
USED FOR: Checking for memory fragmentation. 
FOUND ON: Devcon disk, Software Toolkit







TOOLNAME: MemList 
CATEGORY: Full used and free memory chunk lister
USAGE:    Memlist [>diskfile]
USED FOR: Debugging fragmentation/deallocation problems 
FOUND ON: Devcon disk, Extras(?)

TOOLNAME: Owner
CATEGORY: Memory ownership tool
USAGE:    Owner [0x] nnnn... (owner ? for help)
USED FOR: Trying to determine ownership of allocated memory 
FOUND ON: DevCon disk

TOOLNAME: Snoop 
CATEGORY: Remote AllocMem/FreeMem debugger
USAGE:    Snoop (use SnoopStrip on captured output to isolate unfreed Allocs)
USED FOR: Debugging unfreed memory problems 
REQUIRES: Serial terminal 
FOUND ON: Devcon disk, Software Toolkit

TOOLNAME: SnoopStrip
USAGE:    SnoopStrip [>outfile] infile
USED FOR: Stripping matched allocs/frees from captured snoop output 
FOUND ON: Devcon disk

TOOLNAME: Drip 
CATEGORY: Memory loss accumulator
USAGE:    Drip [threshold]
USED FOR: Determining change in free memory since last invocation 
FOUND ON: Devcon disk, Software Toolkit

TOOLNAME: Peek
USAGE:    Peek B|W|L [0x]address [[0x]compvalue] [[0x]mask] 
USED FOR: Checking or script branching on contents of a memory address 
FOUND ON: Devcon disk

TOOLNAME: Poke
USAGE:    Peek B|W|L [0x]address [0x]value [[0x]mask] 
USED FOR: Changing the contents of a memory address 
WARNINGS: Obviously, poking where you shouldn't may crash machine. 
FOUND ON: Devcon disk




OS/Disk Checking Tools

TOOLNAME: DosList 
CATEGORY: Dos device lister
USAGE:    Doslist [DEVS|VOLS|DIRS]
USED FOR: Examining the dos device list 
FOUND ON: Devcon disk

TOOLNAME: ShowLocks (Copyright 1988 Chuck McManis) 
CATEGORY: Filelock lister
USAGE:    ShowLocks [volumename:]
USED FOR: Displaying outstanding locks 
FOUND ON: Software Toolkit

TOOLNAME: DiskEd 
CATEGORY: Disk sector editor
USAGE:    DiskEd drivename:  (see Bantam AmigaDos manual for instructions)
USED FOR: Examining and modifying disk sector data 
WARNINGS: Improper use can trash disk data or structure. 
FOUND ON: Devcon Disk


Performance Checking Tools

TOOLNAME: PerfMon 
CATEGORY: System performance monitor
USAGE:    Perfmon
USED FOR: Checking for busy waiting and other performance problems 
FOUND ON: Devcon Disk, 1.3 Extras


Intuition/Graphics Tools

TOOLNAME: WinList
USED FOR: Examining addresses, titles, flags, sizes of screens and windows 
FOUND ON: Devcon disk

TOOLNAME: ShowGfxBase
USED FOR: Examining GfxBase normal display sizes and flags 
FOUND ON: Devcon disk

TOOLNAME: ReadPixel
USED FOR: Reading the XY screen location and color of pixels.  Can be 
    used to check the size and position of onscreen images.
USAGE:    Readpixel  (then click on pixels to read) 
FOUND ON: Devcon disk

TOOLNAME: MKS_Lens
USED FOR: Examining individual pixels of screen
USAGE:    MKS_lens 
FOUND ON: Devcon disk


TOOLNAME: DevMon 
CATEGORY: Device monitor
USAGE:    Devmon name.device unitnum [remote] [hex] [allunits] [full] 
    (remote is serial output, full has exec wedges in DoIO, ReplyMsg)
USED FOR: Monitoring the calls to a device 
REQUIRES: Nothing for local monitoring. Serial terminal optional (slower) 
WARNINGS: Stresses system if wedged into high-usage or time-critical devices  
    (such stress could lead to crashes or hangs)
FOUND ON: Devcon disk

TOOLNAME: Cmd 
CATEGORY: Parallel/Serial output capture tool
USAGE:    Type cmd help for usage
USED FOR: Debugging printer, serial, and parallel output
FOUND ON: Workbench 2.0

TOOLNAME: PrinterTest 
CATEGORY: Printer driver test suite
USAGE:    Printertest (then answer y when the correct printer is prompted)
USED FOR: Testing printer drivers 
FOUND ON: Devcon disk

TOOLNAME: KTest 
CATEGORY: Serial connection tester
USAGE:    KTest
USED FOR: Checking serial debugging setup 
FOUND ON: Devcon disk

TOOLNAME: DTest 
CATEGORY: Parallel connection tester
USAGE:    DTest
USED FOR: Checking parallel debugging setup
FOUND ON: Devcon disk

TOOLNAME: IO_Torture (see WATCHDOG TOOLS)



Development Time Bug Prevention/Tracking Tools

TOOLNAME: RCS 
CATEGORY: Source/document control
USAGE:    See accompanying docs on Fish Disk 282
USED FOR: Recording changes to source code and documents
FOUND ON: Fish Disk 282

TOOLNAME: Autodoc 
CATEGORY: Source code autodoc extractor
USAGE:    See accompanying autodoc.doc
USED FOR: Extracting standard function documentation from your source code 
FOUND ON: Devcon disk

TOOLNAME: Bumprev 
CATEGORY: Revision bumper
USAGE:    Bumprev version revname  (example:  bumprev 36 my_rev)
USED FOR: Updating revision include files (xxx_rev.h and xxx_rev.i) 
FOUND ON: Devcon disk


