SIMBug v0.60 ============ Preliminary SIM Debug Server 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 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, a titlepage is printed. Then 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 yes. 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 the address to be used as PC. 'T' Debugs an existing task. You are asked the task structure 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 enabeling aborting of 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. 6. System Symbols ---------------------- SIMBug can load a definition file containing information about symbols to be created in general, i.e. library functions, system variables and hardware registers. The definition file is written in a simple script language enabeling easy adding of further libraries or custom data by the user. It must be stored in the 'S:' directory as 'bug.libfile'. The compiler uses an accumulator for the address that is used for the value of the next symbol to be defined. Strings beginning with a dollar sign are concidered to be commands, other strings are concidered to be symbol names. One command or symbol name is accepted per line. Symbols can consist of any characters except dollar signs, spaces and periods. If a symbol name ends on a space, a symbol with that name is added to the symbol list and the default size is added to the accumulator. If the symbol ends on a period, what is after the period is interpreted as hexadecimal number. A symbol with this name is added and the value of that number is added to the accumulator. I.e.: ExecBase.22 ;This is ExecBase SoftVer ;Softver Commands begin with a dollar sign. The following commands are currently known: $ADDR [addr] Directly sets the accumulator to [addr]. $JUMP [offset] Adds [offset] to the accumulator. $END Ends symbol definition. $ENDNODE Ends a symbol node. This is usefull for optimisation. Before changeing to i.e. another library, execute this command. $APTR Reads the longword at the address in the accumulator and stores it in the accumulator. $BCPL Same as $APTR but the pointer at that address is concidered to be a BCPL pointer and multiplied by four. $SIZE [size] Sets the default size which is added to symbols withou '.[size]'. $SAVE [num] Stores the accumulator in memory [num]. [num] can vary from 1 to 8. $LOAD [num] Loads Memory [num] to accumulator. $LIST The memory the accumulator points currently to is interpreted as a list and symbols with the names of all nodes and their addresses are created. The accumulator is then increased by the default size. $NODE The memory the accumulator currently points to is interpreted as a node structure and a symbol with the node address and its name is created. The accumulator is not changed. $LIBRARY [name] Tests if a node with the name [name] is in $DEVICE [name] the system list named by the command. If it $RESOURCE [name] is, the accumulator is loaded with the node $MEMORY [name] address. If it isn't, all symbol definitions $INTERRUPT [name] are ignored until a $ADDR, $ENDTYPE or one of $PORT [name] these commands is encountered. $LOADLIB [name] Opens and closes a library once to load it if it hasn't been instelled yet. $ENDTYPE Enables symbol definition again. SIMBug is distributed with both a definition file for Kickstart 1.3, 2.04 and 3.0 libraries. 7. 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. You can reach me by e-mail under avalon.physik.unizh.ch!swalter or at the physical address stated in the documentation to SIM. Stefan Walter, 28.Dec.92