----------------------------------------------------------------------------- SIMBug Preliminary S.I.M. Debug Server Version 0.70 Copyright © 1990-1993 by Stefan Walter ALL RIGHTS RESERVED ----------------------------------------------------------------------------- Documentation last edited on: 15.12.93 ============================================================================= 1. Introduction ============================================================================= SIMBug provides an easy way to use SIM as debugger for different kinds of programs: Executables, bootblocks, files, tasks and programs that are already in memory. Support of multiple task debugging is still only not available. You also should not run two copies of SIMBug because they both share the same copy of SIM. This version is still only preliminary and not quite comfortable. ============================================================================= 2. Startup ============================================================================= SIMBug can only be started from CLI, not from Workbench. When started, SIM looks for the system symbols definition file which, if available, is loaded and compiled to a symbol list. If no SIM is in memory yet, SIMBug automatically enters the SIM load menu. ============================================================================= 3. Commands ============================================================================= The following case unsensitive commands are known by SIMBug: x Quits SIMBug. h Lists all commands. k Removes a previously installed copy of SIM and frees the memory if it was allocated. This command needs to be called when you need to load a fresh copy of SIM. s Loads SIM. SIMBug first determines a suitable location for SIM, display and backup. SIM is searched in the current directory, 'C:', 'DH0:', 'C+:' and 'DF0:'. Then you are asked the address for SIM, display and backup. By entering nothing, the computed default values printed in brackets are used. You can then either allocate memory for SIM or not, default is to do so. Finally you need to confirm if all entered addresses are right. e Simply enters SIM through the JSR entrance. The PC then points somewhere in SIMBug. This function is mainly supported for short calls to SIM. You should not change the PC or stack. l Debugs an executable. You are asked for the name of the program and a command line which is then passed to the program in a0/d0. After sucessfully loading the executable, SIMBug scans the hunk structure for symbol hunks. If it encounters any, a symbol list is created. After the program terminates, SIMBug waits for you to press once more before it frees symbol lists and unloads the program. Useful if the program detaches from CLI. b Debugs a bootblock. You are asked for the drive number from which to load the bootblock. Only DF0:-DF3: are allowed. The bootblock of that drive is loaded to an allocated block of chip memory. f Debugs a file. You are asked for the file name and the address to which it shall be loaded. If no address is specified, the default address is used. Memory is allocated, if it can't, the command fails. The PC is set to the start of the file in memory. m Debugs a program already in memory. You are asked for the address to be used as PC. t Debugs an existing task. You are asked for the task control blocks address of the task to intercept. If interception was successful, the task enters SIM when it becomes the running task again. w Lists all tasks. n Creates a new CLI. ============================================================================= 4. BTW ============================================================================= A loaded copy of SIM is kept resident in memory. Some virus protection programs may complain about the resident structure SIMBug creates for that purpose. When debugging anything except tasks, the processing power of the CLI process of SIMBug is used. ============================================================================= 5. The Quit Feature ============================================================================= SIMBug uses the debug server entrance of SIM when debugging executables, files, bootblocks and programs in memory, thus enabling aborting the program. By leaving SIM with one of the quit commands or shortcuts, SIMBug is called again. You can then either continue debugging or abort the program. If you abort, the program is unloaded but resources allocated by the program are not freed. The continue function is useful if you need to suspend debugging and temporarily work on something else. The quit feature only works if the running task is the CLI process of SIMBug. If you quit SIM from the wrong process, a requester pops up. You can then choose to either continue or to suspend the process. ============================================================================= 6. Bugs ============================================================================= If you find any bugs in SIMBug, the system symbol definition files or SIM, you are kindly asked to report these to me in order to get them fixed. Please look at the end of the documentation of SIM for both my physical or e-mail address.