PostSIM v0.80 ============= Short Documentation 1. Introduction ==================== PostSIM basically is a simple crash handler. It will catch all exceptions which do not occur in supervisor mode and all calls to Alert(). Additionally to basic features like ending or suspending the crashed tasks, PostSIM also allows symbolic postmortem debugging. PostSIM can be used for different objectives. It can be used as preventive mesurement against crashes and software failure requesters, giving you the chance not only to suspend or end the crashed process but also to have a closer look at what went wrong. If you are developing applications, having PostSIM waiting in the background is can be quite useful. You can debug right when the program fails which is a big help for searching the reason for these nasty hard_to_reproduce crashes. It also allows you to partially fix programs that break on higher versions of the OS or 680x0 processors, due to cache problems or the typical 'MOVE SR,' instruction. Finally PostSIM allows also active debugging. If you know that your program has a bug, you can insert and assemble or compile ILLEGAL instructions at strategic places in your program or where you assume the bug to be. When you run the program then, PostSIM gets invoked due to one of the ILLEGALS and you can monitor the program from then on. Very useful to debug objects like file handlers etc. 2. Installation ==================== To install PostSIM, first copy the main program 'PostSIM' to the 'C' directory. Then copy either 'bug.libfile20', 'bug.libfile30' or 'bug.libfile30' to 's:bug.libfile', depending on the version of the OS you have installed. PostSIM should be installed from the startup-sequence, but it can also be started later from the CLI/Shell. Start from the Workbench is not allowed. PostSIM accepts some options when started: -s (path) (path) specifies where PostSIM shall look for SIM. This must be stated if you do not have stored SIM in either the current or the 'C' directory. -k (key) (key) specifies the shortcut with which PostSIM can be invoked. It must be stated as rawkey, default is $00190019 (Ctrl-LShift-Lalt-p). Commodities is not supported yet. -w (specs) (specs) specifies the console window PostSIM shall open when invoked. Default is 'CON:0/0/550/150/PostSIM v0.80'. If the default window is too small to contain the full texts with the system font you use, use this option to specify a larger window. -q Supresses the title text when installing and only prints the installation message. Useful when installing PostSIM in the startup-sequence. ? Prints a brief overview of the options and does not install PostSIM. A full example: PostSIM -q -s bin/sim -k $190030 -w CON:0/0/640/200/My_PostSIM When executing PostSIM for the first time, you may get the following messages: PostSIM successfully installed. PostSIM could be installed and is now working. Unable to open port. PostSIM could not open the port needed to handle crashes and was therefore not installed. Executing PostSIM again has the same effect as pressing the shortcut. While PostSIM waits in the background, memory consumption limits itself to ca. 27 KBytes. 3. Invoking PostSIM and Commands ===================================== If PostSIM is invoked, it will first try to load a copy of SIM if it hasn't done yet. If it can't, a filerequester pops up. If you cancle it, SIM will not be loaded. PostSIM then loads the symbol definition file if it could be found and generates a symbol list if no error in the definition file was found. Finally the reason for the invokation, the results of a few sanity checks and the list of available commands is displayed. The sanity checks consist on a informing you if Forbid() or Disable() was broken, if the stackpointer is not within the stack of the crashed task/process and if its PC is not within the ROM or any hunks of the program. Not all commands are allowed at every kind of invokation, i.e. the 'D'/Debug command has no sence if PostSIM was invoked by shortcut. The following commands exist: Q Terminates PostSIM. Is only allowed when no crash is pending, the storage list is empty and debugging is not in progress. H Holds PostSIM. If no crash is pending, this command puts PostSIM on stand-by. N Creates a new CLI/Shell. E Enters SIM. Basically of use if you lost control while debugging or for short peeking of the system. System symbols are available. I If a crash is pending, further information about register contents and the task of the crash are given. R Reloads the system symbols, i.e. to update device or library base symbols. U Updates the traphandlers of all tasks. This command may be used after another program (i.e. another debugger) changed the traphandler of a task and you want this traphandler pointing at PostSIM again. If a changed task traphandler is found, information about the task is given and the possibilities to update this one or all, not to update it, not to update any more or cancle. S Suspends the task that crashed. X Ends the task of the crash by either calling Exit() or by performing an additional RTS. O Lets the old traphandler deal with the crash. Y Loads symbols from an executable. The symbols are relocated on the segment list of the loaded command of the crashed process. Problems may occur with CLI detaching programs where the segment list of the program in memory does not match the hunk structure of the executable. D Invokes SIM to debug. C Terminates debugging and lets go the task that crashed. A If the invokation reason was a call to Alert(), this command lets the task complete the call. G Terminates debugging and resets SIM. This command needs to be executed if you terminated debugging of the last crash and didn't leave SIM with 'Quit' then. P Stores the crash in the storage list. W (num) Gets the first or (num)th crash from the storage list. L Lists all crashes in the storage list. ? Displays all available commands. 4. Debugging ================= When a task crashes, it is put to waitstate by calling Wait(), regardless whether it has called Disable() or Forbid() before. This can remotely lead to futher crashes depending what the program was doing when it crashed, i.e. if it was meddling with the task or memory lists. When you intend to debug a crashed task, you can do this with the 'D' command. If an exception caused the crash, the PC points to the instruction which caused the exception. If it was Alert(), The PC points to the real Alert() function, if you don't want to see the alert, perform an RTS. If you need to suspend debugging for whatever reason, use the 'Quit' command of SIM. You return to PostSIM where you can use the 'D' command again to continue or the 'C' command to continue execution of the program and to end the debugging job on this task. When you have finished debugging, don't leave SIM with 'Exit'. Use 'Quit' instead. You return to PostSIM. There you finish debugging by entering the 'C' command. 5. Bugs ============ If you find any bugs in PostSIM, the system symbol definition files or SIM, you are kindly asked to report these to me in order to fix them. Look in the documentation to SIM for both my physical or e-mail address. Stefan Walter, 28.Dec.92