Exception Handler V1.01 beta. User Documentation. NOTE!: The 'disk contents' section of these dox was just for the beneift of the A-Level examiners. The only files distributed with Exception handler are 'Except' and 'EH_manual.txt~. NOTE!: This manual was written for an A-Level project so please excuse it's simplicity, there may be the odd bit which is relevant but most coders will find this manual well basic... I know people are going to say: 'Software debugging, that's EASY you just ripped of 2-Cool's source code from GRAPEVINE (The most fantastic disk mag ever.)' Well this project was started BEFORE 2-Cool released his source code. If you are still an unbeliever write to me and I will send you the source of Exception Handler so that you can compare them. HAS ANYONE OUT THERE GOT A COPY OF THE SNES DEVELOPERS MANUAL? IF YOU HAVE PLEASE CONTACT ME! Look out for 'SCoPE' my 'second generation' debugging system. I AM CURRENTLY 'BETWEEN GROUPS', ANY TAKERS? Disclaimer. I, Oliver Norton take no responsibility for any damage to data, hardware or software arising through use of this program. Every effort has been made to ensure that this program is as reliable and bug free as possible but recovery from all crashes cannot be guaranteed. Distribution and copyright.. This program is copyright Oliver Norton 1992,93 it may be freely distributed and sold by PD libraries etc. providing that the following conditions are adhered to:- All files relating to EH are present. Any disk containing EH must not be sold for more than £1.50 (UK currency) or equivalent. All files are unchanged, this includes the omission or inclusion of any data. Commercial organisations should contact and arrive at an agreement with me before using EH in the production of software for commercial release. Updates. This version of EH is only compatible with Amigas containing a 68000 CPU, it is not compatible with other 680x0 series processors. If you want a 680x0 version of EH you can contact me and we can arrange a registration fee. Commercial organisations should contact me for registration details before using EH (See above.) Credits. Exception Handler v1.01a C Copyright 1992,93 Oliver Norton. All rights reserved. Program & Design: Oliver Norton aka. EDGE. Font: Seen/Melon Dezign (?) Alpha testing: Mista Are/Indy Beta testing: Paul Toyne, Mista Are/Indy Manual: Oliver Norton Distribution: Mista Are/Indy Proof reading: Mista Are/Indy Acknowledgements. Commodore and Amiga are registered trademarks of Commodore Business Machines Ltd. Hisoft, Devpac, Monam and Genam are all copyright Hisoft. Introduction. Exception Handler (called simply 'EH' from now on) is system designed to provide a fast, efficient means of debugging of assembly language programs on the Amiga computer. The Amigas CPU is of the Motorola 68000 type, this processor already has several inbuilt features to help with the debugging of software under development. The processor can be set up in such a way that every time an error occurs a custom error handling routine is called. This is known as exception handling. Unfortunately the custom error handler provided by the Amiga's operating system does not allow recovery from the error, it reports that an error has occurred and resets the Amiga, losing all your unsaved work in the process. EH utilises the 680x0's exception handling features to provide a much more useful and user friendly error handling system. In the majority of cases exception handler will allow you to return to what you were doing before the crash occurred without system reset of loss of data. The complete EH system consists of only one part, the EH program itself. Despite this you will need at least one more item of software to use EH, namely an assembler such as HiSoft's Devpac in order to generate machine code programs to be debugged. This chapter is an introduction to this manual which attempts to explain all aspects of installing and using EH on your Amiga. This manual assumes that you already have a reasonably comprehensive understanding of Amiga programming and Motorola 680x0 assembler in generally. This manual will not teach you to program in 680x0 assembly language, if you want to learn 680x0 assembly language see the Bibliography for further reading examples. We strongly suggest that you read this manual through before trying to use EH in order to get maximum benefit from both EH and this manual. System requirements EH will run on any Amiga 68000 computer (A500, A500+, A600, A1000, A1500, A2000 etc.) with at least 40Kb of chip memory and Kickstart 1.2+. This preview version of EH will not run on 680x0 processors where x>0, full registered versions of EH will have complete 680x0 support. Although EH will run alongside a decent sized assembly development system (ie. Devpac) on a 512Kb Amiga this leaves very little space for source code and code generation. We strongly suggest that 512Kb users purchase an upgrade to 1Mb if they want to develop assembly language programs on their Amiga. This is not just for EH but for general program development and use aswell. In order to trap the majority of program errors before large scale memory corruption can occur EH must attach itself to the Amigas operating system at very low level, because of this complete compatibility with existing software is virtually impossible to achieve although we have made every effort to make EH as system friendly as possible. See the compatibility section for a list of software which has been tested with EH. Disk contents. The distribution disk should contain the following:- Except - The exception handler program. EH_MANUAL.txt - This manual as an ASCII test file. EH_README.txt - A list of last minute manual additions, bugs, `undocumented features =8-)' etc. Installation. The only file necessary for EH to operate is the file 'Except' from the distribution disk, just copy this file plus any others you require to your boot disk. You must also have a copy of the AmigaDos 'RUN' command suitable for your Kickstart version in your C: directory. (In Kickstart 2 and higher this command is built in) To run EH from your boot disk just type the following at the CLI or Shell prompt:- RUN Except {-M} [Return] The parenthesis around the '-M' indicate that it is an optional parameter and can be omitted. Specifying the -M parameter causes EH to startup in MONAM compatible mode (See the compatibility and trouble shooting chapters for further details.) The README file. As with the majority of application software EH is being updated constantly and the latest details that could not be included in this manual have been included in the ASCII file 'EH_README.txt' which can be viewed with PPMORE or another suitable ASCII viewer. A walk through EH. On starting EH from either the Shell or CLI you should see a message similar to the following displayed in the main window:- Exception Handler v1.01a (04-03-93). æ1992-93 Oliver Norton. All rights reserved. EH installed sucessfully in normal mode. Under normal circumstances you will only see EH's main screen when an exception occurs. How is EH started. Once you have sucessfully installed EH the EH debugging system will be invoked whenever one of the following exceptions is generated. Bus error. This exception will be generated if a program tries to access an area of memory which does not exist. It may also be caused by external hardware. Address error. This exception will be generated if an attempt to access 16 bit (Word) or 32 bit (Long word) data at an odd address is made. Illegal instruction. This exception is generated when the CPU's program counter reaches an address whose contents do not relate to a 68000 op code. All 68000 opcodes are 16 bits long giving a total of 65536 possible combinations, the 68000 does not have that many op codes. If EH was started in Monam compatible mode EH will not be invoked by this exception. Zero divide. This exception is caused by an attempt to divide a number by zero using the DIVU or DIVS instructions. Since a divide by zero does not give an answer (it is mathematically undefined) an exception is generated. Chk instruction. This exception is generated when the CHK instruction is used to check the bounds of a register or effective address. Trapv instruction. This exception is caused by the overflow bit in the condition code register being set when a TRAPV instruction is executed. Trace. This exception is designed to help programmers single step through their code. If the trace bit is set in the status register then this exception is generated after each instruction is executed. If EH was started in Monam compatible mode EH will not be invoked by this exception. LineA & LineF. LineA and LineF exceptions are generated when the last op code to be executed started with a $A or $F respectively. These exceptions allow programmers to effectively write their own instructions. A walk through EH. This chapter will show you how to use EH when an exception is generated. a). Start EH in either normal mode or Monam compatible mode. b). Load up your assembler (eg. Devpac or Asm-One ). c). Using the assemblers editor, key in the following source code:- opt c- section example,code_c Start1: Move.l #$1.w,a0 Move.w (a0),d0 Moveq.l #0,d0 Rts d.) Assemble the above source code to memory. As you can see the two lines after the label 'Start1' will cause an address error as they try to read a word of data from an odd address ($1). e.) Now execute the assembled program in memory (Use Left Amiga-X on Genam2). f.) The power light should flash and a blue and black screen should be displayed similar to the following:- Exception Handler v1.01a Main Menu. Display CPU Status. Display system information. View stack and program counter areas. View interrupt vectors. Structure search. System reset. *Greets* Exit exception handler. A yellow and black rotating mouse pointer will also be displayed, this is not a wait pointer as you might expect but along with the flashing power light it is an indicator that EH is working. If at any time the power light stops flashing and the mouse pointer stops rotating a serious error has occurred and the only way to continue is to reboot your Amiga. To select a menu item move the mouse pointer so that it is over the desired item, the item will become highlighted. To select the item press the left mouse button. The functions of the main menu items will be detailed below:- Display CPU Status. This option displays the contents of the CPU registers at the time of crash including a bit by bit display of the condition code register. If the exception which invoked EH was either a Bus error or an Address error the following additional information is also displayed:- Type of program to cause the exception. The op code of the command which caused the exception. The address of the memory location being accessed. Whether the processor was reading or writing main store. To return to the main menu select the 'Return to main menu.' option. Display system information. This option displays information about your Amiga system as a whole. This information is particularly useful for solving incompatibility problems between different Amiga hardware setups. With this information you can tell if your program is crashing because it expects a certain hardware configuration but is not running on an Amiga with that particular configuration. Execbase reset vectors (If these are all 0 your are free from any virus infection which may have caused the crash.) Total chip and slow memory and their locations in the Amigas address space. (Does your program require a particular type of memory?) Power supply and PSU frequency. (Does your program require a particular screen update frequency?) Denise chip type (Was your program written with the enhanced chip set in mind?) Location of EH in memory. You can return to the main menu by selecting the 'Return to main menu' option. View stack and program counter areas. This option the contents of the 12 long words of memory around the program counter, user stack and supervisor stacks at the time of the exception. The information is listed in the form address, contents of address. The actual values of the program counter, user stack and supervisor stack are shown by arrows on either side of each list. You can return to the main menu by selecting the 'Return to main menu.' option. View interrupt vectors. This option displays the contents of the CPU interrupt vectors, levels 1 to 7 along with their addresses and abbreviations of which hardware items generate each level of interrupt. You can return to the main menu by selecting the 'Return to main menu.' option. Structure search. This option allows you to search through memory for commonly used data structures. On selecting this option you will be presented with a list of structures which can be search for. After you have selected the data structure to search for, a message will be displayed to tell you that EH is searching. If the structure is found it's address will be displayed along with a menu allowing you to either continue searching or return to the search menu. If the structure is not found only an option to return to the search menu. You can return from the search menu to the main menu by selecting the 'Return to main menu.' option. Search for structure. Protracker/Noisetracker module. Devpac source code. Electronic Arts IFF header. Powerpacker 2+ header. AmigaDos boot block. Fairlight 4 channel module. Fairlight 8 channel module. Crunchmania data file. Powerpacker encrypted file. Return to main menu. System reset. This option allows you to reboot the Amiga in the event of an unrecoverable crash (See the unrecoverable crashes chapter.). When you select this option you will see a screen similar to the one below. System reset page. Hard reset (Total memory clear). Soft reset (Majority of memory unchanged). Return to main menu. As the menu items suggest 'Hard reset' will clear all of the main store as if the Amiga had been switched on. 'Soft reset' leaves the majority of memory unchanged. It is suggested that you use the 'Soft reset' option if you intend to salvage data from main store after the Amiga has rebooted (See the unrecoverable crashes chapter.). As always you can return to the main menu with the 'Return to main menu.' option. Greets. Option displays a page of credits and hellos to my friends as well as bit of advertising for forthcoming programs and my address. Exit exception handler. This option allows you to exit EH and (Hopefully) return to your development environment or continue your programs execution. When this option is selected the following screen will be displayed:- Select return point. Safe return (More likely to terminate a rogue program.) Continue directly after point where error occurred. If you select the 'Safe return' option EH will execute an RTS instruction as soon as it has returned from the exception which invoked EH. This is likely to return you to your development environment. The 'Continue' option will continue execution of your program directly after the point where it caused the exception. In the case of the example program either exit option should return you directly to your development environment (eg. Devpac). Unrecoverable errors. If EH is invoked immediately after you exit from EH then it is likely that an unrecoverable crash has occurred and the following procedure should be followed. a.) Try exiting from EH three or four times using a combination of both exit options (Try one then the other.) If EH is still invoked as soon you exit go on to step 'b'. Otherwise you will be returned to your development environment, if this happens it is suggested that you save any unsaved data and reboot your Amiga. b.) Use the 'Structure search' option to find the location of any unsaved data (eg. Devpac source code) and note down the location of the data on somewhere. Now return to the main menu and select the 'System reset' option and perform a SOFT reset. c.) Once the Amiga has finished rebooting load up a program which allows you to save areas of main store to backing store. (eg. Monam 2, Disk monitor professional.) And save the data from the addresses you noted down in step 'b'. Trouble shooting and errors. Error description: If the following message is displayed when EH is started then there is insufficient memory for EH's screen:- EH Error 01: Insufficient memory for screen. Exiting.. Remedy: If this happens close down other background tasks, accessories etc. in order to free some chip memory (Approximately 20K is required for EH's screen). Now try to install EH again. Error description: If the following messages is displayed when EH is started your Amiga is fitted with accelerated processing hardware such as a faster CPU (ie. 68030) or a memory management(MMU) or floating point(FPU) unit. This version (1.01a) of EH does not support any CPU hardware other than the 68000 fitted to standard A500's A500+'s etc. (See system requirements). EH Error 02: Accelerated processing hardware detected. Exiting.. Remedy: If your accelerator has a 68000 fall back mode enable this and attempt to start EH again. Alternatively register your version of EH and you will be sent the enhanced version of EH which includes full support for all 68xxx series CPU's, MMU's and FPU's. Error description: EH starts up OK but crashes or keeps being invoked when I run MONAM. Remedy: Startup EH with the following command line: RUN Except -M [Return] This will start EH in MONAM compatible mode. When in MONAM compatible mode EH does not detect TRACE or ILLEGAL INSTRUCTION exceptions so if your program causes either of these exceptions when you are not using MONAM your Amiga will GURU! Compatibility: In order to trap exceptions as quickly as possible writes itself into into some of the CPU exception vectors at very low level. Because of this other software which also writes to these vectors is unlikely to be compatible with EH. This chapter details the problems with pieces of software which have been tested with EH and have been found to be incompatible. Program name: Asm-One Version tested: 1.05 Asm-One's monitor and debug functions patch exceptions at low level and set up their own system stacks (Both user and supervisor). EH will be invoked correctly when an error occurs but will hang up the Amiga when you try exit form EH. Program name: Monam Version tested: 2.14 The majority of Monam's exception patching is done legally (Via the operating system) but the TRACE and ILLEGAL INSTRUCTION vectors are both patched directly. This will cause the Amiga to crash or hang up if EH has been started in normal mode. If you want to use Monam in conjunction with EH (This provides a VERY powerful debugging environment.) you must start EH using the -M option. (See the trouble shooting chapter for further details of the -M option.) Bibliography. The following books were used in the production of this project and are particularly useful to any one interested in Amiga hardware or programming the Amiga in general. Assembly language. Amiga machine language. By Dittrich. Published by Abacus. M68000 16/32-bit microprocessor, programmers reference manual. Published by Motorola semiconductors. Amiga hardware. Amiga Hardware Reference Manual. By Commodore Amiga Technical Support (CATS). Published by Addison-Wesley. Mapping the Amiga. By Rhett Anderson and Randy Thompson. Published Compute! books. Amiga programming. Amiga System Programmers Guide. By Dittrich, Gelfand and Schemmel. Published by Abacus. Amiga ROM Kernal Manual. By Commodore Amiga Technical Support (CATS) Published by Addison-Wesley. Contact address. If you want to register, get updates, send comments or bug reports contact me at the following address:- Oliver Norton 5 Huntingdon Close Burton on the Wolds Loughborough Leicestershire LE12 4AE.