home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 493.lha / OnTrap / ontrap.doc < prev    next >
Encoding:
Text File  |  1991-04-06  |  9.5 KB  |  286 lines
  1.  
  2.      ontrap() & trapcode() for the SAS C(tm) 5.10a developement language.
  3.                     Written by John V. Pope, Turlock CA.
  4.              Plink John*Pope (Sec 11, The Developers' Den)
  5.              CIS   71566,537
  6.  
  7.       The supplied c.o module and related functions improves the multitasking
  8.    friendliness of any program linked with the modified c.o.
  9.  
  10.       The changes simply add an EXCEPTION handler to the programs you link
  11.    with the supplied c.o. The ontrap handler puts up a system requester on
  12.    the workbench screen (similar to break) to inform the user that the
  13.    program hit a TRAP, then exits without a GURU.
  14.  
  15.       That's right, NO GURU!!!
  16.  
  17.       In addition, a simple call to the ontrap function passing a pointer
  18.    to a replacement trap handler can cause a custom trap handler to be
  19.    invoked when the program causes an exception. The custom trap handler
  20.    can close files and explain to the user what happened. Then free all
  21.    allocated memory, close windows, ANYTHING you want done before the code
  22.    is unloaded by AmigaDOS.
  23.  
  24.       The default trap handler cxtrap and code added to c.o and _main
  25.    is about 450 bytes. A very small price to pay for code that won't
  26.    cause a GURU for a simple bug in a program.
  27.  
  28.       You might be asking, "If it's so simple, why isn't an EXECPTION
  29.    HANDLER built into AmigaDOS?".  One IS!! It's the one that put's up
  30.    a system requester saying "Software Failure!!!, System task held".
  31.    That's how our favorite computer handles stray EXCEPTIONS.
  32.  
  33.       The technical reason my code works is this, I didn't really have
  34.    to re-invent the wheel. Just add the spokes.  The Amiga OS is very
  35.    complex.  Exec has the job of signaling task's (or process's) of sevaral
  36.    things.  Messages, software traps and EXCEPTIONS to name a few.
  37.    When a task (or process) is added to the system by AmigaDOS, the task
  38.    structure is initialized with some default information.  One field,
  39.    tc_TrapCode, is initialize with an address. The address of the code
  40.    that puts "Software Failure ..." on the workbench screen.  That is the
  41.    address that is invoked in the event of an exception.  All I had to do
  42.    was give it another location to report to and have that code handle an
  43.    EXCEPTION interrupt.  No sweat! (I can say that now after lots of GURU's).
  44.  
  45.       One important bit of information to keep in mind.  The trap handler
  46.    should NOT call exit(),  _exit() or Exit().  The function MUST return.
  47.    I am actually calling the traphandler function set up by the user as
  48.    a subroutine to the c.o routines.
  49.  
  50.       I am calling the user defined trap function from a point in c.o
  51.    PRIOR to the onexit trap. BEWARE!! If you have set an onexit trap to
  52.    free memeory, it will NOT be neccesary to free the memory from inside
  53.    the user defined trap function.  You'll know this happened if you get
  54.    a FreeTwice error from exec.
  55.  
  56.       As much as I would like for this enhancement to be a fix all for all
  57.    of the GURU problems in the Amiga, it's not.  Some ROM functions call the
  58.    GURU (Alert) directly.  This comepletly bypasses the Exec exception
  59.    handler, thus my trap handler.
  60.  
  61.       One should also know that GOMF appears to set up an exception handler 
  62.    in the hardware vector thus bypassing the Exec exception handler.  All
  63.    my good intentions and all your cleanup code will be completly ignored!
  64.  
  65.       Happy coding!!!
  66.  
  67.         John V. Pope
  68.  
  69.  ---------------------------------------------------------------------------
  70.     NAME
  71.        ontrap()   Plant EXECPTION handler.
  72.  
  73.     SYNOPSIS
  74.        ontrap(function);
  75.  
  76.        int (*function)();  Pointer to the function to be called.
  77.  
  78.        function   The address of the user supplied trap handler.
  79.  
  80.        Function can be 0, this will serve to use the c.o routines to call
  81.    the cxtrap requester.  Thus removing any previously set functions.  The
  82.    program will terminate with the return of 1000+exception value.
  83.  
  84.        The external variable _TRAPCODE contains the trap code that is placed
  85.    on the supervisor stack by the MC680x0 exception interupt routine in c.o.
  86.  
  87.        The external variable _ONTRAP recieves the function address. If this
  88.    variable is zero, no custom or default trap handler is called.  The
  89.    program just terminates quietly with 1000+exception in register D0.
  90.  
  91.    RETURNS
  92.        NONE.
  93.  
  94.    NOTES
  95.        The c.o module can be used with or without the ontrap functions.
  96.  
  97.  ---------------------------------------------------------------------------
  98.     NAME
  99.         trapcode()  Extract the MC68000 exception code.
  100.  
  101.     SYNOPSIS
  102.         code = trapcode(void);
  103.  
  104.     int code;
  105.  
  106.         This function supplies a very simple method of extracting the
  107.    exception value that the exception handler code in c.o recieves.
  108.  
  109.  ---------------------------------------------------------------------------
  110.  
  111.    MC68000 EXCEPTION CODE SUMMARY
  112.  
  113.    2      Bus error
  114.    3      Address error (odd address)
  115.    4      Illegal instruction
  116.    5      Zero divide
  117.    6      CHK instruction (check register bounds)
  118.    7      TRAPV instruction (arithmetic overflow trap)
  119.    8      Priviledge violation
  120.    9      Trace interrupt
  121.    10     Line 1010 emulator ($Axxx instructions)
  122.    11     Line 1111 emulator ($Fxxx instructions)
  123.    37-47  Trap instructions
  124.  
  125.  ---------------------------------------------------------------------------
  126.  
  127.     EXAMPLES    NOTE: These are just examples. Don't try to compile them.
  128.  
  129. /* EXAMPLE. Using ontrap and trapcode */
  130. /* To avoid alot of declaration hassles, put this function ABOVE main() */
  131. int
  132. traphandler()
  133. {
  134.       extern char *_ProgramName;
  135.  
  136.       printf("%s hit trap code %d\n",_ProgramName,trapcode());
  137.       clean_up_allocated_memory();
  138.       return(0);
  139. }
  140.  
  141. void
  142. main()
  143. {
  144.  
  145.       ontrap(traphandler);
  146.       ProneToGuru();
  147.       clean_up_allocated_memory();
  148. }
  149.  
  150.  
  151.     OR you can just do this ...
  152.  
  153. /* EXAMPLE. Using cxtrap requester only */
  154. main()
  155. {
  156.      ontrap(0); /* just put up a requester and exit, don't bother with cleanup */
  157.  
  158.      ProneToGuru();
  159.      clean_up_allocated_memory();
  160. }
  161.  
  162.     This is yet another alternative ...
  163.  
  164. /* EXAMPLE. Not using trapcode */
  165. int
  166. traphandler()
  167. {
  168.       extern char *_ProgramName;
  169.       extern long _TRAPCODE;  /* exception code from the supervisor stack */
  170.  
  171.       printf("%s hit trap code %ld\n",_ProgramName,_TRAPCODE);
  172.       clean_up_allocated_memory();
  173.       return(0);
  174. }
  175.  
  176. void
  177. main()
  178. {
  179.  
  180.       ontrap(traphandler);
  181.       ProneToGuru();
  182.       clean_up_allocated_memory();
  183. }
  184.  
  185.     Then again, this will also work ...
  186.  
  187.     NOTE: Only the new c.o file is required for this one to work.
  188.  
  189. /* EXAMPLE. Not using main, ontrap, or trapcode */
  190. int
  191. traphandler()
  192. {
  193.       extern char *_ProgramName;
  194.       extern long _TRAPCODE;
  195.  
  196.       printf("%s hit trap code %ld\n",_ProgramName,_TRAPCODE);
  197.       clean_up_allocated_memory();
  198.       return(0);
  199. }
  200.  
  201. extern int (*_ONTRAP)();
  202.  
  203. _main()
  204. {
  205.     _ONTRAP = traphandler;
  206.  
  207.     ProneToGuru();
  208.         clean_up_allocated_memory();
  209. }
  210.  
  211.  
  212.  ********************************************************************
  213.  ********************************************************************
  214.  
  215.              Highlights of changes to ontrap for Lattice C 4.01
  216.  
  217.  ********************************************************************
  218.  ********************************************************************
  219.  
  220. 1. You don't need trap.lib or trapnb.lib as in 4.0. The oml program now
  221.    handles indexed libraries, the ontrap function, cxtrap and the modified
  222.    umain.o can actually be placed in lattice libraries.
  223.  
  224. 2. The c.o routines handle 16 or 32 bit int modes a bit better.
  225.  
  226. 3. cxtrap (the default trap handler) is available in both 16 and 32 bit
  227.    linkable versions.
  228.  
  229. 4. A non-GURU exit is ALWAYS taken by the exception handler.  You may
  230.    lose some memory though.
  231.  
  232. 5  1000 is added to the value placed on the supervisor stack by the
  233.    MC68000 exception handler.  This values is returned to AmigaDOS by c.o
  234.    in register D0 upon exiting.
  235.  
  236. 6. The trapcode() funcion is supplied for no nonsense exception code access.
  237.  
  238. 7. The user supplied trap handling routine is no longer passed the exception
  239.    code. I did this because the 16 bit mode of the compiler pulls only
  240.    the upper half of the long word exception value from the stack.
  241.    Instead, the exception value is available in the external longword
  242.    _TRAPCODE or the trapcode function. See the examples above.
  243.  
  244.  
  245.  
  246.  
  247.  ********************************************************************
  248.  ********************************************************************
  249.  
  250.              Highlights of changes to ontrap for Lattice C 5.04
  251.  
  252.  ********************************************************************
  253.  ********************************************************************
  254.  
  255. 1. Simple update to correctly install in the 5.04 environment.
  256.    No functional changes result.
  257. 2. As a result of 1 above, cres.o is now installed.
  258.  
  259.  
  260.  
  261.  
  262.  ********************************************************************
  263.  ********************************************************************
  264.  
  265.              Highlights of changes to ontrap for Lattice C 5.05
  266.  
  267.  ********************************************************************
  268.  ********************************************************************
  269.  
  270. 1. Simple update to correctly install in the 5.05 environment.
  271.    No functional changes result.
  272.  
  273.  
  274.  
  275.  
  276.  ********************************************************************
  277.  ********************************************************************
  278.  
  279.              Highlights of changes to ontrap for SAS C 5.10a
  280.  
  281.  ********************************************************************
  282.  ********************************************************************
  283.  
  284. 1. Simple update to correctly install in the 5.10a environment.
  285.    No functional changes result.
  286.