home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -seriously_amiga- / programming / other / blowup / blowup.doc < prev    next >
Encoding:
Text File  |  1998-04-27  |  9.4 KB  |  224 lines
  1. Blowup -- Catches and displays task errors
  2.  
  3. Written by Olaf `Olsen' Barthel <olsen@sourcery.han.de>
  4. Public Domain
  5.  
  6. ------------------------------------------------------------------------------
  7.  
  8. 1. What is it?
  9.  
  10. Blowup catches tasks, processes and programs trapped in exceptional error
  11. conditions. Such conditions include attempts to execute unimplemented CPU
  12. instructions, trying to divide a number by zero, to access data/instructions
  13. located at invalid addresses and many others. This is also what the operating
  14. system does, but Blowup adds to this by providing additional information on
  15. the cause of the error. Also, Blowup will attempt to safely catch errors
  16. caused by tasks; the operating system does not do this: once a plain Task is
  17. trapped in exceptional error conditions, the exec kernal will trigger a
  18. dead-end alert and reboot the machine. Blowup is a quality assurance tool
  19. which in the right hands can be used to detect and remove errors in Amiga
  20. software.
  21.    Blowup works best if used together with tools like Enforcer, SegTracker,
  22. Memoration, Scratch and Wipeout (the first four are all part of the Software
  23. Toolkit, as distributed in the 3.1 Native Developer Kit or on the Amiga
  24. Developer CD v1.1). Blowup does not work with the "tnt" program; it is meant
  25. to be an alternative to tnt.
  26.    Blowup is related to the tnt and GOMF tools, but unlike these offers more
  27. and different functionality. It is definitely not a replacement for the
  28. Enforcer tool; all it can do is complement its functionality. But then, if
  29. your Amiga has no MMU, Blowup and Wipeout provide functionality similar to
  30. Enforcer; this is as close as it could get.
  31.  
  32.  
  33. 2. Requirements
  34.  
  35. Blowup requires an Amiga equipped with Kickstart 2.04 or better. Aside from
  36. the operating system version, there are no special requirements.
  37.  
  38. Since Blowup sends its output to the built-in Amiga serial port or the
  39. parallel port, you should either have a terminal or a printer connected to
  40. your machine, or you should run a program like Sashimi or Sushi to capture its
  41. output.
  42.  
  43.  
  44. 3. What Blowup does
  45.  
  46. Blowup installs custom trap handlers for every task, process and program
  47. currently running and also patches the exec kernal AddTask() routine to the
  48. effect that every new task added will also have the custom trap handler
  49. installed. This custom trap handler will be invoked every time the
  50. corresponding task is trapped in an exceptional error condition. When this
  51. happens, Blowout will output information on the task, the location of the
  52. error and bring up an error requester prompting you to choose whether the task
  53. that triggered the error should be suspended until the system is rebooted or
  54. whether you want to reboot the system immediately.
  55.  
  56.  
  57. 4. Interaction with other programs
  58.  
  59. Blowup should be smart enough not to interfere with trap based debuggers, such
  60. as the SAS/C CodeProbe debugger. It will install the custom trap handler only
  61. if the task to be modified does not already have a custom trap handler
  62. installed.
  63.  
  64.  
  65. 5. Command line options
  66.  
  67. Blowup can be started only from Shell. If it is started for the first time, it
  68. will patch the exec kernal and modify all currently running tasks, processes
  69. and programs to use the custom trap handler. I recommend to always run Blowup
  70. in the background, like this:
  71.  
  72.    run >nil: Blowup
  73.  
  74. Every other attempt to start Blowup will only cause the running Blowup
  75. configuration to be updated.
  76.  
  77. The following command line options are available:
  78.  
  79. OFF                This turns off an already running Blowup.
  80.  
  81. PARALLEL           This option activates parallel port output; default is
  82.                    serial port output through kprintf().
  83.  
  84. NOBANNER           This option will cause Blowup not to print its banner
  85.                    message when it is started.
  86.  
  87. AREGCHECK          These options tell Blowup that you wish all the values
  88. NOAREGCHECK        in the address registers to be checked via SegTracker;
  89.                    default is NOAREGCHECK.
  90.  
  91. DREGCHECK          These options tell Blowup that you wish all the values
  92. NODREGCHECK        in the data registers to be checked via SegTracker;
  93.                    default is NODREGCHECK.
  94.  
  95. STACKCHECK         These options tell Blowup that you wish all the values
  96. NOSTACKCHECK       displayed in the stack to be checked against the
  97.                    global segment lists via SegTracker. This will tell
  98.                    you in what segment lists various return addresses on
  99.                    the stack are found, which may help in tracing the
  100.                    location of an offending command. Default is NOSTACKCHECK.
  101.  
  102. STACKLINES=number  This option lets you pick the number of lines of stack
  103.                    backtrace to display. The default is 2. If set to 0,
  104.                    no stack backtrace will be displayed. There is NO ENFORCED
  105.                    LIMIT on the number of lines.
  106.  
  107.  
  108. 7. Signals
  109.  
  110. Blowup watches for one signal that can be sent to it either by holding down
  111. the [Ctrl]-C keys or through the Shell "Break" command:
  112.  
  113. [Ctrl]-C  Turns off Blowup
  114.  
  115.  
  116.  
  117. 8. What is in a Blowup report?
  118.  
  119. Here is a sample Blowup report with a few annotations:
  120.  
  121.    TASK TRAPPED
  122. 1) 18-Apr-98 12:46:06
  123. 2) Address error
  124. 3) TRAP=0x03  SR=0x0000  PC=0x084A1416  TCB=0x08571F20
  125. 4)   PC: 4EB90000 00014E75 31323334 35363738 0000084A 1DC80000 00300212 850E0000
  126. 5) Data: 00000000 00000001 00000002 00000003 00000004 00000005 00000006 00000007
  127. 6) Addr: 00000010 00000011 084A1416 0869075C 00000014 00000015 00000016 0869075C
  128. 7) Stck: CACACACA 0819F59C 00004E20 08572944 00000000 086B8E90 000039D8 2053746F
  129.    Stck: 7054696D 65722856 4F494429 3B0A564F 49442053 74617274 54696D65 7228554C
  130. 8) Name: "Background_WShell"  CLI: "crash3"  "crash3" Hunk 0000 Offset 00000046
  131.  
  132.  
  133. 1) This is the time and date of the Blowup hit, i.e. the point of time when
  134.    an error condition was triggered.
  135.  
  136. 2) This indicates what type of problem occured; in this case an address
  137.    error has occured.
  138.  
  139. 3) This line shows the error type ("TRAP=0x03") which corresponds to the
  140.    description in 2), the contents of the status register ("SR=0x0000"),
  141.    the address of the program counter ("PC=0x084A1416") and the address
  142.    of the task that triggered the error condition ("TCB=0x08571F20").
  143.    The program counter refers to the location of the error; in some cases
  144.    it points to the instruction that caused the error, in some it points
  145.    behind it. For more information, see the CPU User's Manual (such as
  146.    the "MC68040 User's Manual" available from Motorola). The status
  147.    register is of particular interest. In the case shown above it reads
  148.    0x0000 which among other things tells that the error occured while a
  149.    program was executing in user mode. The status register consists of
  150.    two bytes, with the upper being the system byte and the lower the
  151.    user byte. If the system byte is non-zero, Blowout will never show
  152.    a requester to prompt you what to do next, it will always drop into
  153.    a dead-end alert.
  154.  
  155. 4) These are the first few long words located around the program
  156.    counter address listed under 3); they show you the command to
  157.    be executed when the error condition was triggered.
  158.  
  159. 5) This is a dump of the MC68000 data registers
  160.  
  161. 6) This is a dump of the MC68000 address registers
  162.  
  163. 7) This is a dump of the stack active at the time the error condition
  164.    was triggered.
  165.  
  166. 8) This is the name of the task and the program name that triggered the
  167.    error condition; first the task name, then the CLI program name and
  168.    the location of the call in that program. In some cases, the CLI
  169.    program name may be omitted or the hunk/offset information may not
  170.    be available.
  171.  
  172.  
  173. 9. How useful is a Blowup report?
  174.  
  175. While Blowup performs a service which Enforcer cannot, it is by no means a
  176. replacement for Enforcer. Blowup is particularly useful when tracking down
  177. comparatively "harmless" errors like a division by zero or an attempt to
  178. execute an unimplemented instruction (e.g. caused by trying to execute a
  179. program on a plain 68k machine which was compiled for use on 68020 machines).
  180. As for the rest, it might still prove useful, but due to the nature of the
  181. errors it traps, the reason for the error might not be directly related to the
  182. error the CPU has detected. For example, trying to access uninitialized memory
  183. can cause the CPU to keep following further unitialized memory references,
  184. eventually resulting in an illegal instruction error or an address error.
  185. Trying to trace back the cause based upon the symptom may thus prove
  186. impossible; who knows, maybe the error occured due to which random patterns
  187. memory was initialized at the time of the crash -- which may not be
  188. reproduceable. In those cases, Enforcer scores much higher as it will detect
  189. illegal memory accesses as soon as they occur, and not just when the CPU has
  190. hit a dead end.
  191.    Concluding, Blowup may help to provide the key to solving a software
  192. problem, it is unlikely that it provides sufficient information to solve it
  193. all on its own. Therefore, always run Blowup with Enforcer, SegTracker and
  194. possibly Wipeout.
  195.  
  196.  
  197. 10. Source code
  198.  
  199. For your convenience, the complete program source code is included in the
  200. distribution. Should you find bugs, make updates or enhancements, feel free to
  201. contact me. The source code was written for the SAS/C compiler.
  202.  
  203.  
  204. 11. Author information
  205.  
  206. If you wish to contact me about Blowup, you can use the following postal
  207. address:
  208.  
  209.    Olaf Barthel
  210.    Brabeckstrasse 35
  211.    D-30559 Hannover
  212.    Federal Republic of Germany
  213.  
  214. or you can use this e-mail address:
  215.  
  216.    olsen@sourcery.han.de
  217.  
  218.  
  219. 12. Release history
  220.  
  221. Blowup 1.3 (18.4.98)
  222.  
  223.     - Initial public release
  224.