.cs 5
.pn 
.mt 5
.mb 6
.pl 66
.ll 65
.po 10
.hm 2
.fm 2
.ft All Information Presented Here is Proprietary to Digital Research
.sp 2
.he CP/M-8000 Programmer's Guide              4.6  Exception Functions
.tc    4.6  Exception Functions
.sp 2
.sh
4.6  Exception Functions
.qs
.ix exception functions
.pp 5 
This section describes the Set Exception (61), Set Supervisor State, 
(62), and the Get/Set TPA Limits Functions that set exceptions for error
handling and other exception processing. 
.bp
.pn 88
.tc         4.6.1  Set Exception Vector Function
.sh
4.6.1  Set Exception Vector Function
.qs
.ix set exception vector function
.sp 3
.nf 
               FUNCTION 61:  SET EXCEPTION VECTOR

                Entry Parameters:
                   Register   R5:  3DH
                   Register  RR6:  EPB Address

                Returned  Values:
                   Register   R7:  Return Code

                                   success:  00H
                                     error:  FFH
.fi
.sp 2
.pp
The Set Exception Vector Function allows a program to reset
current exception vectors, set new exception vectors, and create
exception handlers for the Z8000 microprocessor. 
The exception numbers used are the same as the exception numbers 
used in CP/M-68000, for portability.
.ix exception vectors
.ix exception handlers
.ix exception parameter block (EPB)
.pp
In addition to passing the function number in register   R5, a
program must pass the address of the Exception Parameter Block
(EPB) in register  RR6. The EPB is a 10-byte data structure
containing a one-word vector number and two longword vector
values.  See Figure 4-7. The EPB specifies the exception and
the address of the new exception handler. 
Table 4-21 lists valid exceptions that correspond to Z8000 
microprocessor hardware.  The starting location of the 
EPB must be an even-numbered address.
.sp 2
.nf        
.sh
               Field                            Size
.qs
.sp              

             Vector Number                     1 word

             New Defined Vector Value          1 longword

           Old Vector Value Returned by BDOS   1 longword

.fi
.sp 2
.ce
.sh
Figure 4-7. Exception Parameter Block (EPB)
.qs
.sp 2 
.ix vector number
.ix vector values
.pp
The vector number identifies the exception. The New Vector Value specifies
the address of the new exception handler for the specified exception. The
BDOS returns in the Old Vector Value Field, the value that the exception
vector contained before this function was invoked.  The BDOS replaces the
old vector value with the new vector value in its table of exception
handlers and returns the address of the old exception handler to the old
vector value in the EPB.  After the BDOS sets the new exception vector, it
passes the value 00H in register   R7. However, if an error, such as a bad
vector, occurs while the vector is being set, this function passes the
value FFH in register   R7.  The bad vector error occurs when a vector
other than one listed in Table 4-21 is specified for this function. 
.ix bad vector error
.ix system state
.pp
When an exception occurs, before the BIOS passes control to the BDOS
exception handler, it saves the registers on the system stack
in a form suitable for use with the control-transfer (XFER) system
call provided by the BIOS (as described in the CP/M-8000 Operating
System Guide).  It then calls the BDOS exception handler as a subroutine,
in system, segmented mode.  The BDOS exception handler restores the
status to that of the program that was executing when the exception
occurred (usually normal, non-segmented mode), and places a copy
of the context block on the appropriate (system or normal) stack.
The exception handler must return control to the interrupted program
by means of an XFER system call.
.ix exception handler
.ix logical console device (CONSOLE)
.pp
If an exception handler does not exist for an exception, when
that exception occurs, the BDOS default exception handler returns
an exception message to the logical console device (CONSOLE)
before it aborts the program. The BDOS exception message format is
defined below: 
.sp 2
.ix resident system extensions (RSXs) 
.nf
           Exception nn at user address aaaaaaaa. Aborted.
.fi
.sp 
.in 10
.ti -10
where:
.sp 
.ti -10
nn        is a hexadecimal number in the range 2 through 17 or 24
through 2F that defines all exceptions excluding reset,
hardware interrupts, and system Traps 0 through 3.
.sp 
.ti -10
aaaaaaaa  is the address of the instruction following the one 
that caused the exception.
.qi
.sp 2
Except for exceptions handled by resident system extensions (RSXs), the
BDOS reinitializes all vectors to the default exception handler when the
BDOS System Reset Function (0) is invoked. Any exception vectors, which
your program sets, are reset after the BDOS warm boots the system. An RSX
is a program that is not configured in the operating system but remains
resident in memory after it is loaded. RSXs normally provide additional
system functions. The Get/Set TPA Limits Function (63) allows you to create
an area in the TPA in which one or more RSXs can reside. 
.ix RSX
.ix resident system extension
.bp
.ce
.sh
Table 4-21.  Valid Vectors and Exceptions
.qs
.sp 
.nf
                 Vector         Exception
.sp
		    0	     Non-Maskable Interrupt
.sp
		    1	     EPU Trap
.sp
                    2        Segment Violation
.sp
                    8        Privilege Violation
.sp
                   32*       System Call 0 (debugger breakpoint)
.sp
                   36**      System Call 4	
.sp
                   37**      System Call 5  
.sp
                   38**      System Call 6  
.sp
                   39**      System Call 7 
 
.sp        
.fi
.in 6
.ti -4
*   Vectors reserved for Resident System Extensions (RSX)
implemented with the Get/Set TPA Limits Function (63). 
.sp
.ti -4
**  Recommended Trap vectors for applications. 
.bp
.in 0
.tc         4.6.2  Set Supervisor State
.sh
4.6.2  Set Supervisor State
.qs
.ix set supervisor state
.sp 3
.nf
               FUNCTION 62:  SET SUPERVISOR STATE

                     Entry Parameters:  
                        Register   R5:  3EH

                     Returned  Values:
                        Register   R7:  00H
.fi
.sp 2
.ix supervisor state
.pp
The Set Supervisor Function puts the calling program in supervisor 
(system) state.  If running on a segmented processor (Z8001 or Z8003),
it also puts the program into segmented mode.
This function should not be used by novice 
programmers and experienced programmers should be careful when 
invoking this function.
.ix supervisor stack
.pp
The user stack is swapped when the program enters supervisor state.  
On return from this function, the stack pointer, register RR14, is the 
supervisor stack pointer and not the user stack pointer. Thus, you
cannot use register RR14 to reference the user stack, but must use
the user stack pointer (accessible with the LDCTL instruction).  
.pp
The supervisor stack is used by the BDOS and BIOS. The
size of this stack is unpredictable, and the percent of the stack used 
by the system is dependent on the operation being performed and 
those previously performed. Therefore, you cannot predict
how much of the stack is available for program operations.  To 
avoid stack overflow and overwriting the system, you should not  
push more than a few dozen bytes onto the stack, especially when
you call BDOS and BIOS functions. 
.pp
An alternate method of avoiding stack overflow is to switch to a private
supervisor stack. You create the stack by loading into RR14 the address of an
area in memory that you use as the supervisor stack. The address must be an
even address. If you call BDOS and BIOS functions, your private supervisor
stack should be 300 longwords more than the space required by the program.
If your program exits supervisor mode, make sure your program restores the
system stack pointer to its original value. The supervisor stack is
reinitialized when the system warm boots. 
.pp
Note that in future CP/M-8000 upward compatible systems, this
function may not exist, or will require privilege for the calling
process to access this function, or the function will fail. If it fails 
the value FFH will be passed to   R7.  However, no
privilege is currently necessary. The function is always
successful and the value 00H is passed in register   R7. 
.bp
.tc         4.6.3  Get/Set TPA Limits
.sh
4.6.3  Get/Set TPA Limits
.qs
.sp 3
.ix get/set TPA limits
.nf
                FUNCTION 63:  GET-SET TPA LIMITS

                 Entry Parameters:
                    Register   R5:  3FH
                    Register  RR6:  TPAB Address

                 Returned  Values:
                    Register   R7:  00H
                    Register TPAB:  Contains TPA
                                    Values
.sp 2
.fi
.ix Transient Program Area (TPA)
.ix Transient Program Area block (TPAB)
.ix Transient Program Area (TPA), boundaries
.pp
The Get/Set TPA Limits Function allows you to obtain or set the
boundaries of the Transient Program Area (TPA).  You must load
the address of the Transient Program Area Block (TPAB) in 
register  RR6.  The TPAB is a 5-word data structure consisting  
of one word and two longwords. You create the TPAB in 
the TPA as illustrated in Figure 4-8. 

=============== THIS IS PRESENTLY NOT IMPLEMENTED RIGHT =========
=============== IT IS NOT CLEAR WHAT IT SHOULD DO IN A  =========
=============== SEGMENTED ADDRESS SPACE.                =========
.sp 3
.in 2
.nf
Byte Offset            Field                        Size
   
 00H              Parameters                       1 word  

 02H              Low TPA address                  1 longword

 06H              High TPA address + 1             1 longword

.fi
.in 0
.sp 2
.ce
.sh 
Figure 4-8.  Transient Program Parameter Block
.qs
.sp 2
.pp
The value of the first two bits in the one-word Parameters Field 
determines whether 
this function gets or sets the TPA limits and which fields you 
supply. Figure 4-9 illustrates the
format of the parameters field.
.bp
.in 6
.nf
   
 Parameters    15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0   
 Field        
                   reserved bits (2-15) = 0      



                 bits:         1      0 

                 values =     1/0    1/0   

.fi
.in 0
.sp 2
.ce
.sh 
Figure 4-9.  Parameters Field in TPAB
.sp 2
.pp
Bit Zero  determines whether you get or set the TPA limits.  When
the value of bit zero is zero, the BDOS returns the current TPA
boundaries in the Low and High Address fields of the TPAB.  When the value of 
bit zero is one, the BDOS sets new TPA
boundaries.  The BDOS uses the values that you specify in the Low
and High TPA address fields of the TPAB to set the new TPA
boundaries.  
.pp
When you set the TPA boundaries, bit one determines whether the boundaries 
are temporary or permanent.  When the value of bit one is zero, 
the TPA boundaries that you set are temporary; when the system warm boots,
the previous TPA limits are restored.  When the value of bit one is 
one, the TPA values that you set are permanent; they are not 
changed when the system warm boots. 
.pp
Bits 2 through 15 contain zeroes.  These bits are reserved for future use.  
Table 4-22 summarizes the values of bits zero and one. 
.sp 2 
.ce 2
.sh 
Table 4-22.  
.sp 0
.sh
Values For Bits 0 and 1 in the TPAB Parameters Field
.qs
.ix TPAB parameters field
.sp
.in 5
.ll 60
.nf
Bit    Value                      Explanation
.sp
.fi
.in 23
.ti -18
0        0        Return boundaries of current TPA in TPAB Low and High 
Address Fields.
.sp
.ti -18
         1        Set new TPA boundaries with the values loaded in TPAB Low 
and High address fields.
.sp
.ti -18
1        0        Restore previous TPA values when the system warm boots.
.sp
.ti -18
         1        Permanently replace the TPA boundaries with the ones you 
specify in the Low and High TPAB Address Fields.
.bp
.in 0
.ll 65
The examples below illustrate and explain values for bits zero and 
one.
.sp
Examples:
.sp 2
.in 8
.ti -4
1)  Get TPA Limits
.sp
.nf
                         1       0               
  
                         0       0   

.fi
.sp
This function returns the boundaries of the current TPA in the 
Low and High Address Fields of the TPAB when the value of bit 
zero equals 0.
.ne 10
.sp
.ti -4
2)  Temporarily Set TPA Limits 
.sp
.nf
                         1       0               
  
                         0       1   

.fi
.sp
This function temporarily sets the TPA boundaries to the
boundaries that you supply in the Low and High Address Fields of
the TPAB when bit zero equals 1 and bit one equals 0. The TPA
boundaries are reset when the system 
warm boots.
.sp
.ti -4
3) Permanently Set TPA Limits
.sp
.nf
                         1       0               
  
                         1       1   

.fi
.sp
This function permanently sets the TPA boundaries to the values 
that you supply in the Low and High Address Fields of the TPAB 
when the value of bit zero equals 1 and bit one equals 1. The
TPA limits remain set until this function is called to reset the
boundaries or you cold boot system.
.in 0
.sp 2
.ce
End of Section 4
.nx five

