Software Design Notes                              Error Handling






                           SECTION 17

                         Error Handling



17.1  INTRODUCTION

This section explains the signalling of errors.  It explains  how
the  microcode  signals an error condition to a program or to the
user.

This section is organized from  the  abstract  to  the  concrete.
First,  the  error  conditions are described.  Then prograssively
lower levels of the implementation ade discussed.



17.2  MICROCODE ERROR CONDITIONS

There are a number of conditions that are signalled by the system
microcode.  Listed below are the condition flavors, all of  which
are  built  directly  or  indirectly upon ERROR.  A later section
covers the names of the microcode traps themselves.  All  of  the
symbols  listed  are  in  the ERROR-HANDLER (EH:)  package unless
another package name is present.

     ARG-TYPE-ERROR:  an argument to an operation is  not  of  an
     acceptable type.

     ARRAY-NUMBER-DIMENSIONS-ERROR:   attempt  to access an array
     with greater of fewer dimensions than the array has.   Built
     on BAD-ARRAY-ERROR.

     BAD-ARRAY-ERROR:  generic array problems that lack their own
     condition.

     CALL-TRAP-ERROR:   break on entry to a function or on normal
     exit from a CATCH.

     CANT-INITIATE-ON-THIS-DEVICE-TYPE:  tried to initiate I/O on
     an unknown device type.

     CELL-CONTENTS-ERROR:  the transporter  found  something  bad
     (but  not fatal) in memory.  Unboxed variables and undefined
     functions signal other conditions.

     DANGEROUS-ERROR:   virtual-memory   overflow,   region-table
     overflow.


                             17-1

Error Handling                              Software Design Notes



     SYS:DIVIDE-BY-ZERO:  division by zero.

     EXIT-TRAP-ERROR:  break on exit from a function.

     FLOATING-EXPONENT-OVERFLOW-ERROR:   result  is  too large in
     magnitude to be represented as a floating point number.

     FLOATING-EXPONENT-UNDERFLOW-ERROR:  result is too  small  in
     magnitude to be represented as a floating point number.

     FUNCTION-ENTRY-ERROR:  a problem was encountered in entering
     a  function,  like  too  many  or  too  few arguments, or an
     argument of a wrong data type.

     INTERNAL-MEMORY-LOCATION-OOB:  out-of-bounds reference to an
     internal processor memory.

     INVALID-FUNCTION:  some non-functional object was called  as
     a function.

     MAR-BREAK:   the Memory Address Register comparator caused a
     break on a read or write.

     PDL-OVERFLOW-ERROR:   stack  overflow  on  the  regular   or
     special variable PDL.

     STEP-BREAK-ERROR:   signalled  by  breakpoints,  signle-step
     breaks, and trace breaks.

     SUBSCRIPT-ERROR:  a subscript for an array access is out-of-
     bounds, negative, or otherwise in error.

     THROW-EXIT-TRAP-ERROR:  break  on  THROW  through  a  marked
     catch.

     THROW-TAG-NOT-FOUND:   a  THROW  was done to a tag for which
     there is no pending CATCH.

     UNBOUND-VARIABLE:  an access to a symbol's value cell or  to
     a  closure  variable  found it unbound (DTP-NULL).  Built on
     CELL-CONTENTS-ERROR.

     UNDEFINED-FUNCTION:  an access to a symbol's  function  cell
     or  to  a  method  of a select-method found it unbound (DTP-
     NULL).  Built on CELL-CONTENTS-ERROR.

     UNIMPLEMENTED-HARDWARE:  tried some  operation  on  XBUS  or
     UNIBIS, neither of which exists in the Explorer System.

     USER-NUBUS-ERROR:  error in user NuBus operation.

     SYS:ZERO-TO-NEGATIVE-POWER:   attempt was made to raise zero
     to a negative power.


                             17-2

Software Design Notes                              Error Handling



17.2.1  Microcode Error Table.

This paragraph is a description of microcode error table entries.
The microcode   error   table   is   read   from   SYS:UBIN;EXP1-
UCODE.TBL#nnn  (where nnn is the microcode version) and stored as
the value of the variable MICROCODE-ERROR-TABLE.  The error table
provides  information  about  error  trapping  locations  in  the
microcode.   Each  entry  in  the MICROCODE ERROR TABLE is a list
which associates a microcode PC to a symbolic description of  the
error called an Error Table Entry (ETE).  The CAR of the ETE list
contains  information  about  how  to  construct  the appropriate
condition  instance.   This  information  is  fully  defined   in
SYS:EH;ERROR-CONDITION-DEFINITIONS and is described below.

Each  location  in  the  microcode  where  TRAP  can be called is
followed by an ERROR-TABLE pseudo-op.  This pseudo-op appears  at
the  PC  which  is going to be TRAP's return address.  An example
is:

      (ERROR-TABLE ARGTYP FIXNUM M-T 0)

The CDR of this list is the ETE.  The ETE's first element is  the
name  of the error and the second is the first "argument" to that
error's assocuated routines.  Note that all ETEs are lists  whose
CARs  are  symbols.   The  symbol is defined by a DEF-UCODE-ERROR
form  in   SYS:EH;ERROR-CONDITION-DEFINITIONS.    DEF-UCODE-ERROR
tells  what flavor of condition instance to build and what to put
in it for every microcode trap, keyed by the name of the error.

Error-table entries are listed below alphabetically by type, with
the args as a lambda-list.  Types not used in  the  error-handler
are  marked *.  These types seem to be historical remnants.  Some
of these types are used in CARD or Lambda microcode; they  aren't
used on the Explorer.

In  the  argument  lists  below,  an  argument  of the form "FOO-
location" will have the value of one of the  following  registers
when the trap occurs:  M-A, M-B, M-C, M-D, M-E, M-F, M-G, M-H, M-
I,  M-J,  M-K, M-L, M-Q, M-R, M-S, M-T, M-1, M-2, M-3, M-4, A-SG-
PREVIOUS-STACK-GROUP, PP (the top of the PDL), VMA,  MD,  or  (PP
number)  where  number  is  a negative index into the PDL.  These
locations are saved in stack groups and are  accessed  by  EH:SG-
CONTENTS  for  the  purposes  of  examination,  replacement,  and
restarting from errors.

Since these registers are the ones saved in  stack  groups,  they
will  be  pushed  on the PDL, written to memory, GC-WRITE-TESTed,
and so forth.  Therefore, they must be fully tagged or  have  all
ones  or  zeros in the data type field (M-1, M-2, M-3 and M-4 are
exempt from this restriction).

An argument of the form "FOO-tag" is a pseudo-label defined by  a
RESTART entry.  See section on restart below.


                             17-3

Error Handling                              Software Design Notes



17.2.1.1  Special Error Table Entries.

The  error  table  entries in this section are those not directly
related  to  trap  messages.   They  provide   useful   ancillary
information for the processing of traps.

*  ARG-POPPED  arg1  arg2 arg3 arg4....  Saves (arg1 arg2...)  as
info on where to find popped arts if trap after pop.   The  error
handler collects these but never uses them.

CALLS-SUB  subroutine-tag.  The subroutine-tag will appear on the
>>TRAP line after "->", as an indication of what function  called
the trapping routine.

*  DEFAULT-ARG-LOCATIONS arg1 arg2 arg3....  Saves (arg1 arg2...)
as info on where args may be found if no other info is available.
The error handler collects these but never uses them.

RESTART restart-tag.  Defines restart-tag to be this micro-pc, as
a pseudo-lable for other  error  table  entries.   A  restart-tag
marks  the micro-pc at which to resume execution, for proceedable
traps.  Note:  RESTART is the only way  to  define  restart-tags.
It  is not important whether or not the restart-tag is defined as
a label in the microcode (they  tend  to  be  similar,  just  for
mnemonic value), but it must be unique among restart-tags.

17.2.1.2  Normal Error Table Entries.

The  error  table  entries in this section are used to signal the
actual traps.   Their  names  are  used  in  DEF-UCODE-ERRORs  to
generate condition instances.

AREA-OVERFLOW   area-number-location.   Signalled  during  region
consing when the area has a maximum size "Allocation  in  the  ~A
area exceeded the maximum of ~D.  words."

ARGTYP  description arg-location &optional arg-number restart-tag
function-name.  Description is what was expected -  see  EH:DATA-
TYPE-NAMES.  It can be a list of allowable types.

     Arg-location contains the failing arg.  M-1, M-2, M-3 and M-
     4 are currently not allowed, because the error handler wants
     a  locative  to  the slot in the erring stack group, and the
     high bits of M-1, M-2, M-3 and  M-4  are  stored  separately
     from   the   pointer  field  (thats  how  all  32  bits  are
     preserved).  VMA is also not allowed.

     Arg-number is hte bad argument's number, zero origin.

     Restart-tag is the label to restart from, if other than  the
     current pc.

     Function-name  is  the  erring  function, if that is not the


                             17-4

Software Design Notes                              Error Handling



     obvious one.

ARRAY-HAS-NO-LEADER  array-location  restart-tag.    Some   array
leader operation was attempted on an array with no leader.

ARRAY-NUMBER-DIMENSIONS     ignore    number-of-dimensions array-
location restart-tag.  Number-of-dimensions is a constant (array-
decode-*), or nil if variable (most cases).

     Array-location is where to find the array.

     Restart-tag is the label to restart from, if other than  the
     current pc.

BAD-ARRAY-DIMENSION-NUMBER       array-location dimension-number-
location.  "The dimension number ~S is out of range for ~S."

BAD-ARRAY-TYPE array-header-location.  The  array  type  of  this
array was not one of the legal types.

BAD-CDR-CODE  address-location.   "A  bad  cdr-code  was found in
memory (at address ~O)".

BAD-INTERNAL-MEMORY-SELECTOR-ARG  object-location.   "~S  is  not
valid   as   the   first  argument  to %WRITE-INTERNAL-PROCESSOR-
MEMORIES."  Currently, only 1, 2, 4, and 5 are legal.

BIGNUM-NOT-BIG-ENOUGH-DPB.   "There  is  an  internal  error   in
bignums, please report this bug."

BITBLT-ARRAY-FRACTIONAL-WORD-WIDTH.   "An  array passed to BITBLT
has an invalid width.  The width, times the number  of  bits  per
pixel, must be a multiple of 32."

BITBLT-DESTINATION-TOO-SMALL.   "The  destination of a BITBLT was
too small."

BREAKPOINT.  Caused by executing a BPT instruction.  This is  the
misc entry smashed in for breakpoints in FEFs.

CALL-TRAP.   Microcode  support for things like BREAKON.  This is
the entry half.

CANT-INITIATE-ON-THIS-DEVICE-TYPE  device-type-location.   "Can't
initiate on device type ~S."

CONS-ZERO-SIZE location.  Attempt to allocate zero storage.

DATA-TYPE-SCREWUP  name.   This  happens  when some internal data
structure contains the wrong data type.   Name  is  the  type  of
structure.




                             17-5

Error Handling                              Software Design Notes



DIVIDE-BY-ZERO &optional dividend-location.

EXIT-TRAP.   Microcode  support for things like breakon.  This is
the exit half.

FILL-POINTER-NOT-FIXNUM array-location  restart-tag  "The   fill-
pointer of the array given to ~S, ~S, is not a fixnum."

FLOATING-EXPONENT-OVERFLOW arg "~S produced a result too large in
magnitude  to  be a :[ ;small ] flonum."  "Result is to be placed
in M-T and pushed on the pdl.  Arg is SFL or FLO.  In the case of
SFL the PDL has already been pushed."

FLOATING-EXPONENT-UNDERFLOW arg.  "~S produced a result too small
in magnitude to be a :[ ;small ] flonum."  "Arg is SFL or FLO."

FLONUM-NO-GOOD.  A subset of argtyp.  ARGTYP is not usable.

TOO-FEW-ARGS "Function ~S called with only ~D argument ~1@*~P."

TOO-MANY-ARGS "Function ~S called with too many arguments (~D)."

ILLEGAL-AREA "Tried  to  cons  in  free,  fixed,  or  unused-code
region.  Please report this error."

ILLEGAL-INSTRUCTION.    Illegal   macroinstructions  that  aren't
unimplemented miscops.  "There  was  an  attempt  to  execute  an
invalid instruction.  ~O."

INDIVIDUAL-SUBSCRIPT-OOB array-location dimension-number-location
restart-tag.   Dimension-number  is the location of the offending
dimension's index.  "We assume that the current frame's args  are
the  array  and  the  subscripts,  and  find  the  actual  losing
subscript that way."

INSTANCE-LACKS-INSTANCE-VARIABLE var-location  instance-location.
"Signalled   by   LOCATE-IN-INSTANCE."   "There  is  no  instance
variable ~S in ~S."

INTERNAL-MEMORY-LOCATION-OOB memory-selector-location      index-
location.  "Internal memory location is out of range."

MAR-BREAK direction.  "The MAR has gone off because of an attempt
to write ~S into offset ~O in ~S."  "The MAR has gone off because
of  an attempt to read from offset ~O in ~S."  Direction is WRITE
or READ.  This trap is for the MAR feature.

MICRO-CODE-ENTRY-OUT-OF-RANGE misc-number-location         "MISC-
instruction ~S is not an implemented instruction."

NO-CURRENTLY-PREPARED-SHEET  location.   "There was an attempt to
draw on the sheet ~S without preparing it first."



                             17-6

Software Design Notes                              Error Handling



NO-MAPPING-TABLE   "Flavor  ~S  is  not  a  component  of  SELF's
flavor, ~S, on a call to a function which assumes SELF is a ~S."

NO-MAPPING-TABLE-1.  "SYS:SELF-MAPPING-TABLE is NUL in a combined
method."

NONEXISTANT-INSTANCE-VARIABLE.    "Compiled   code   referred  to
instance variable ~S, no longer present in flavor ~S."

NUMBER-ARRAY-NOT-ALLOWED array-location restart-tag.  "The  array
~S,  which was given to ~S, is not allowed to be a number array."
This one occurs when making a locative to an array element.  None
of the current uses has a restart-tag.

NUMBER-CALLED-AS-FUNCTION number-location.  "The number, ~S,  was
called as a function."

PDL-OVERFLOW  pdl-type.   "The ~A push-down list has overflowed."
Pdl-type is either REGULAR or SPECIAL.

RASTER-WIDTH-TOO-WIDE.  The raster width of a font was too wide.

RCONS-FIXED.  "There was an attempt to allocate  storage  in  the
fixed area ~S."  The area number is in M-S.

REGION-TABLE-OVERFLOW.   "Unable  to  create a new region because
the region tables are full."

RPLACD-WRONG-REPRESENTATION-TYPE first-arg-location.  "Attempt to
RPLACD a list which is embedded  in  a  structure  and  therefore
cannot  be RPLACD'ed.  The list is ~S."  First-arg-location tells
where to find the first arg to RPLACD.

SELF-NOT-INSTANCE.   "A  method  is  referring  to  an   instance
variable, but SELF is ~S, not an instance."

SG-RETURN-UNSAFE.   "An  unsafe  stack  group attempted to STACK-
GROUP-RETURN."  "No args, since the  frob  is  in  the  previous-
stack-group of the current one."

STACK-FRAME-TOO-LARGE.   "Attempt  to  make  a stack frame larger
than 256.  words."  Called from %ASSURE-PDL-ROOM.

STEP-BREAK.  Interface to microcode support for single-stepping.

SUBSCRIPT-OOB index-location limit-location restart-tag  indices-
flag.  Index-location is where to find the index used, and should
always be present.

     Limit-location  is  where  to  find  the legal limit for the
     subscript, and should always be present.

     Restart-tag  may  be  a   list,   which   will   be   pushed


                             17-7

Error Handling                              Software Design Notes



     sequentially.  "This is used to get the effect of making the
     microcode  restart by calling a subroutine which will return
     to the point of the error."

     Indices-flag is "T if indices are on the stack, 1  if  ar-1-
     force  (etc.)   and  there  is  only one index, or absent if
     array's rank should be used to decide where the args are."

*THROW-TAG-NOT-FOUND.

TRANS-TRAP For the conditions  unbound-symbol,  unbound-instance-
variable, unbound-closure-variable, undefined-function, bad-data-
type-in-memory.

     "The variable ~S ~A unbound."

     "The function ~S ~A undefined."

     "The instance variable ~S ~A unbound in ~S."

     "The variable ~S ~A unbound (in a closure value-cell)."

     "The word #<~S ~S> was read from location ~O ~0[in ~A~]."

USER-NUBUS-ERROR    high-address-location    low-address-location
nubus-tms-type-location "User NuBus Error of type ~S, at  address
#x ~16R 16,6.  48~R   $Error Bits:  #x ~16R."

USER-NUBUS-GACBL-LIMIT.  "Number of GACBLs exceeded limit in user
NuBus operation."

USER-NUBUS-PARITY-LIMIT.  "Number of Parity Errors exceeded limit
in user NuBus operation.

VIRTUAL-MEMORY-OVERFLOW.   "You've  used up all available virtual
memory!"

WRITE-IN-READ-ONLY address-location.  "There was  an  attempt  to
write into ~S, which is a read-only address."

WRONG-SG-STATE  sg-location.   "The state of the stack group, ~S,
given to ~S, was invalid."  Sg-location  is  where  to  find  the
invalid stack group.

ZERO-ARGS-TO-SELECT-METHOD   select-method-location.    "~S   was
applied to no arguments."









                             17-8
