doc/em/traps.nr

   1 .bp
   2 .P1 "TRAPS AND INTERRUPTS"
   3 .PP
   4 EM provides a means for the user program to catch all traps
   5 generated by the program itself, the hardware, or external conditions.
   6 This mechanism uses five instructions: LIM, SIM, SIG, TRP and RTT.
   7 This section of the manual may be omitted on the first reading since it
   8 presupposes knowledge of the EM instruction set.
   9 .PP
  10 The action taken when a trap occurs is determined by the value
  11 of an internal EM trap register.
  12 This register contains a pointer to a procedure.
  13 Initially the pointer used is zero and all traps halt the
  14 program with, hopefully, a useful message to the outside world.
  15 The SIG instruction can be used to alter the trap register,
  16 it pops a procedure pointer from the
  17 stack into the trap register.
  18 When a trap occurs after storing a nonzero value in the trap
  19 register, the procedure pointed to by the trap register
  20 is called with the trap number
  21 as the only parameter (see below).
  22 SIG returns the previous value of the trap register on the
  23 stack.
  24 Two consecutive SIGs are a no-op.
  25 When a trap occurs, the trap register is reset to its initial
  26 condition, to prevent recursive traps from hanging the machine up,
  27 e.g. stack overflow in the stack overflow handling procedure.
  28 .PP
  29 The runtime systems for some languages need to ignore some EM
  30 traps.
  31 EM offers a feature called the ignore mask.
  32 It contains one bit for each of the lowest 16 trap numbers.
  33 The bits are numbered 0 to 15, with the least significant bit
  34 having number 0.
  35 If a certain bit is 1 the corresponding trap never
  36 occurs and processing simply continues.
  37 The actions performed by the offending instruction are
  38 described by the Pascal program in appendix A.
  39 .br
  40 If the bit is 0, traps are not ignored.
  41 The instructions LIM and SIM allow copying and replacement of
  42 the ignore mask.~
  43 .PP
  44 The TRP instruction generates a trap, the trap number being found on the
  45 stack.
  46 This is, among other things,
  47 useful for library procedures and runtime systems.
  48 It can also be used by a low level trap procedure to pass the trap to a
  49 higher level one (see example below).
  50 .PP
  51 The RTT instruction returns from the trap procedure and continues after the
  52 trap.
  53 In the list below all traps marked with an asterisk ('*') are
  54 considered to be fatal and it is explicitly undefined what happens when
  55 restarting after the trap.
  56 .PP
  57 The way a trap procedure is called is completely compatible
  58 with normal calling conventions. The only way a trap procedure
  59 differs from normal procedures is the return. It has to use RTT instead
  60 of RET. This is necessary because the complete runtime status is saved on the
  61 stack before calling the procedure and all this status has to be reloaded.
  62 Error numbers are in the range 0 to 252.
  63 The trap numbers are divided into three categories:
  64 .IP "\0\00\-\063" 12
  65 EM machine errors, e.g. illegal instruction.
  66 .RS
  67 .IP "\00\-15" 8
  68 maskable
  69 .IP "16\-63" 8
  70 not maskable
  71 .RE
  72 .IP "\064\-127" 12
  73 Reserved for use by compilers, run time systems, etc.
  74 .IP "128\-252" 12
  75 Available for user programs.
  76 .LP
  77 EM machine errors are numbered as follows:
  78 .TS
  79 tab(@);
  80 n l l.
  81 0@EARRAY@Array bound error
  82 1@ERANGE@Range bound error
  83 2@ESET@Set bound error
  84 3@EIOVFL@Integer overflow
  85 4@EFOVFL@Floating overflow
  86 5@EFUNFL@Floating underflow
  87 6@EIDIVZ@Divide by 0
  88 7@EFDIVZ@Divide by 0.0
  89 8@EIUND@Undefined integer
  90 9@EFUND@Undefined float
  91 10@ECONV@Conversion error
  92 16*@ESTACK@Stack overflow
  93 17@EHEAP@Heap overflow
  94 18*@EILLINS@Illegal instruction
  95 19*@EODDZ@Illegal size argument
  96 20*@ECASE@Case error
  97 21*@EMEMFLT@Addressing non existent memory
  98 22*@EBADPTR@Bad pointer used
  99 23*@EBADPC@Program counter out of range
 100 24@EBADLAE@Bad argument of LAE
 101 25@EBADMON@Bad monitor call
 102 26@EBADLIN@Argument of LIN too high
 103 27@EBADGTO@GTO descriptor error
 104 .TE
 105 .PP
 106 As an example,
 107 suppose a subprocedure has to be written to do a numeric
 108 calculation.
 109 When an overflow occurs the computation has to be stopped and
 110 the higher level procedure must be resumed.
 111 This can be programmed as follows using the mechanism described above:
 112 .LP
 113 .KS
 114 .nf
 115 .ta 1n 24n
 116         mes 2,2,2       ; set sizes
 117 ersave
 118         bss 2,0,0       ; Room to save previous value of trap procedure
 119 msave
 120         bss 2,0,0       ; Room to save previous value of trap mask
 121
 122         pro $calcule,0  ; entry point
 123         lxl 0   ; fill in non-local goto descriptor with LB
 124         ste jmpbuf+4
 125         lor 1   ; and SP
 126         ste jmpbuf+2
 127         lim     ; get current ignore mask
 128         ste msave       ; save it
 129         lim
 130         loc 16  ; bit for EFOVFL
 131         ior 2   ; set in mask
 132         sim     ; ignore EFOVFL from now on
 133         lpi $catch      ; load procedure identifier
 134         sig     ; catch wil get all traps now
 135         ste ersave      ; save previous trap procedure identifier
 136                 ; perform calculation now, possibly generating overflow
 137 1               ; label jumped to by catch procedure
 138         loe ersave      ; get old trap procedure
 139         sig     ; refer all following trap to old procedure
 140         asp 2   ; remove result of sig
 141         loe msave       ; restore previous mask
 142         sim     ; done now
 143                 ; load result of calculation
 144         ret 2   ; return result
 145 jmpbuf
 146         con *1,0,0
 147         end
 148 .KE
 149 .KS
 150 .LP
 151 Example of catch procedure
 152 .LP
 153 .nf
 154 .ta 1n 24n
 155         pro $catch,0    ; Local procedure that must catch the overflow trap
 156         lol 2   ; Load trap number
 157         loc 4   ; check for overflow
 158         bne *1  ; if other trap, call higher trap procedure
 159         gto jmpbuf      ; return to procedure calcule
 160 1               ; other trap has occurred
 161         loe ersave      ; previous trap procedure
 162         sig     ; other procedure will get the traps now
 163         asp 2   ; remove the result of sig
 164         lol 2   ; stack trap number
 165         trp     ; call other trap procedure
 166         rtt     ; if other procedure returns, do the same
 167         end
 168 .KE
 169 .fi