F. GURU-MEDITATION F.1 INTRODUCTION If you have been programming the Amiga for a while you have most certainly seen your nice Amiga 'blow up' in front of your eyes. However, the Amiga is a nice computer, and if it crashes it will try to do that as neatly as possible. You are usually (!) allowed to save any important files, and when the Amiga goes down it will give you a last message, trying to tell you what went wrong. Many novice programmers have not realized how important that last message is. For them, it is just a collection of strange numbers. But those numbers can actually tell you what exactly went wrong, and once you know what went wrong, it is usually no problem to find the bug. F.2 AMIGA CRASHING When the Amiga is about to crash, Exec may be able to intervene prior to the crash occurring proper. Exec will first halt the offending task, and then open a System Requester with a warning message: -------------------------------- | Software error - task held | | Finish ALL disk activity | | Select CANCEL to reset/debug | | | | --------- ---------- | | | Retry | | Cancel | | | --------- ---------- | -------------------------------- You can then save any important files to a disk before you answer the requester (once you have pressed CANCEL the Guru will visit you!). Important, since the Amiga is in trouble it can crash any second, and if you were saving anything onto a disk at that moment, the disk may become corrupted, and all data lost. The best solution is to have an empty emergency disk that you only use when the Amiga is about to crash. Sometimes Exec may find it impossible to halt the task, and the Guru will immediately visit you. This is particularly a hazard faced by Intuition application developers if they are using complex input/output regimes to perform complex display manipulations. F.3 GURU ALERTS Once the Amiga really crashes, the power LED will flash for some seconds, and an Alert will be activated. For example: ---------------------------------------------------------- | Software failure. Press left mouse button to continue. | | Guru Meditation #84010007.00C13870 | ---------------------------------------------------------- Now you only need to decode the message and you have found the error. Advanced programmers please see my special notes at the end of this DOC file. F.4 GURU MEDITATION NUMBERS There exist two different types of Guru Meditation Numbers: - CPU Errors (680x0 Processor Traps) - System Software Errors These are covered below. F.5 CPU ERRORS CPU Errors look like this: Guru Meditation #0000000x.yyyyyyyy x is one of the following values: 2 Bus Error Hardware error (e.g., memory addressing fault, or MMU chip signals bus error on higher-specification Amigas). 3 Address Error Word or longword access on odd byte boundary. 4 Illegal Instruction Usu. $4AFC opcode or 68010/68020 instruction on 68000 machine. 5 Divide by zero Self-explanatory. 6 CHK Instruction CHK instruction out of bounds trap. Can be circumvented by a user CHK handler. 7 TRAPV Instruction Self-explanatory. Again can be circumvented by a user TRAPV handler. 8 Privilege Violation MOVE to SR in user mode, for example. 9 Trace Occurs when trace bit of SR set. User trace handler can be written to handle it. A Opcode 1010 Emulation Instruction word with a value between A000-AFFF. Again, a Line-A handler can be written. B Opcode 1111 Emulation Instruction word with a value between F000-FFFF, usually coprocessor instructions on machines lacking them. Again a Line-F handler can be written (e.g., 68881 FPCP emulator). yyyyyyyy is the address of the task which went wrong. (It is normally your own program that caused the problem.) If the Guru Meditation number #00000005.00C13870 appears, it means that a program, at the address C13870, tried to divide a value by zero. Since the error is now known, it is a matter of locating all of the division operations within the program and spotting the errant division. This is not quite so easy for some other errors, particularly address errors, unless a good debugger is available (e.g., HiSoft's MonAm). F.6 SYSTEM SOFTWARE ERRORS System Software errors look like this: Guru Meditation #aabbcccc.dddddddd (all numbers in hexadecimal). The first field of the number tells us if the error is a Recoverable Error or if it is a Deadend Alert. If the error is a Deadend Alert the number will begin with 8, otherwise it will begin with a 0. Furthermore, Recoverable Alerts cause the currently active screen to be moved down to make way for the alert, whereas Deadend Alerts blank the entire display area except for the alert box at the top of the display area. The first field of the number tells us also which Device, Library or Resource went wrong: 01 Exec Library LIBRARIES 02 Graphics Library 03 Layers Library 04 Intuition Library 05 Math Library 06 CList Library 07 AmigaDOS Library 08 RAM Handler Library 09 Icon Library 10 Audio Device DEVICES 11 Console Device 12 GamePort Device 13 Keyboard Device 14 Trackdisk Device 15 Timer Device 20 CIA Resource RESOURCES 21 Disk Resource 22 Misc Resource 30 BootStrap OTHERS 31 Workbench 32 Disk Copy For example:if the 'aa' field of the error number is 04, this identifies the error as a Recoverable Alert occurring within the Intuition library. If the 'aa' field of the error number is 84, this identifies the error as a Deadend Alert occurring within the Intuition library (and thus is a fatal error). The second field (bb) of the Guru Meditation number identifies the general cause of the problem: 01 No Memory/Insufficient Memory 02 Unable to Create Library 03 Unable to Open Library 04 Unable to Open Device 05 Unable to Open Resource 06 Input/Output (I/O) Error 07 No Signal So a number of the form 8201cccc means a fatal error occurred in the Graphics library, the problem being caused by insufficient memory. The last field (cccc) before the dot gives some more specific information. Here is a list of some common Guru Meditation Numbers: (This information is taken form the headerfile "exec/alerts.h" [V1.3]:) Exec Library: 01000000 81000001 68000 exception vector checksum 81000002 Execbase checksum 81000003 Library checksum failure 81000004 No memory to make library 81000005 Corrupted memory list 81000006 No memory for interrupt servers 81000007 InitStruct() of an APTR source 81000008 A semaphore is in illegal state 81000009 Freeing memory already freed (FreeMem() twice bug) 8100000A Illegal 680x0 exception taken Graphics Library: 02000000 82010000 Graphics out of memory 82010006 Long frame, no memory 82010007 Short frame, no memory 02010009 Text, no memory for TmpRas 8201000A BltBitMap, no memory 8201000B Regions, memory not available 82010030 MakeVPort, no memory 82011234 Emergency memory not available * Layers Library: 03000000 83010000 Layers out of memory Intuition Library: 04000000 84000001 Unknown gadget type 04000001 Recovery form of AN_GadgetType 84010002 Create port, no memory 04010003 Item plane alloc, no memory 04010004 Sub alloc, no memory 84010005 Plane alloc, no memory 84000006 Item box top < RelZero 84010007 Open screen, no memory 84010008 Open screen, raster alloc, no memory 84000009 Open sys screen, unknown type 8401000A Add SW gadgets, no memory 8401000B Open window, no memory 8400000C Bad State Return entering Intuition 8400000D Bad Message received by IDCMP 8400000E Weird echo causing incomprehension 8400000F Couldn't open the Console Device DOS Library: 07000000 07010001 No memory at startup 07000002 EndTask didn't 07000003 Qpkt failure 07000004 Unexpected packet received 07000005 Freevec failed 07000006 Disk block sequence error 07000007 Bitmap corrupt 07000008 Key already free 07000009 Invalid checksum 0700000A Disk Error 0700000B Key out of range 0700000C Bad overlay RAM Library: 08000000 08000001 No overlays in library seglists Trackdisk Device: 14000000 14000001 Calibrate: seek error 14000002 Delay: error on timer wait Timer Device: 15000000 15000001 Bad request 15000002 Power supply does not supply ticks Disk Resource: 21000000 21000001 Get unit: already has disk 21000002 Interrupt: no active unit BootStrap: 30000000 30000001 Boot code returned an error The number after the dot (dddddddd) can be one of three things: 1. Address of the task which went wrong. 2. If the error occured because of some sort of memory allocation/deallocation, it is the address of that memory block. 3. If Exec is realy confused the number is 48454C50, which stands for HELP. (48=H, 45=E, 4C=L, 50=P). This typically occurs with some of the Intuition Deadend alerts (alert number 8400000D being a particular favourite). My Own Comments --------------- Personally, I HATE the Guru Meditation. As a REAL debugging aid in some situations, it is little short of useless (Intuition applications are a prime example-with some code, Gurus appear after spectacular code blow- outs and debuggers just can't catch them). Since Motorola went to enormous trouble to provide a processor chip with comprehensive built-in error trapping, why didn't Commodore come up with something better than this? Special Notes For Advanced Programmers -------------------------------------- Advanced programmers can use the Amiga's built-in debugger. Yes, for those who did not know about it, there does exist a built-in debugger! This debugger is called ROM-Wack, being a slightly slimmer and ROM-based version of a debugger tool used in minicomputer and mainframe environments called, surprise, surprise, Wack. However, to use this built-in debugger requires an extra piece of hardware. Either a second Amiga is required, plus a cable to connect the two Amigas' RS-232 serial ports, or a terminal such as those used as local terminals for minicomputers and mainframes (an ability to handle 9600 baud operation is mandatory). The full command sequence is available in the Amiga ROM Kernel Manual for those with the necessary serial comms equipment. There is a range of software debuggers available (the bset-known and one of the better ones being HiSoft's MonAm) but my experience is that they do not always trap the more insidious causes of the dreaded Guru Meditation. Complex Intuition applications fall prey to the worst of these (especially if numerous windows are opened & they require a fast IDCMP message turnaround) and even good RAM- resident debuggers cannot catch these all of the time.