'\" te
.\"  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH __SPARC_UTRAP_INSTALL 2 "Nov 11, 1997"
.SH NAME
__sparc_utrap_install \- install a SPARC V9 user trap handler
.SH SYNOPSIS
.LP
.nf
#include <sys/utrap.h>

\fBint\fR \fB__sparc_utrap_install\fR(\fButrap_entry_t\fR \fItype\fR,
     \fButrap_handler_t\fR \fInew_precise\fR, \fButrap_handler_t\fR \fInew_deferred\fR,
     \fButrap_handler_t *\fR\fIold_precise\fR, \fButrap_handler_t *\fR\fIold_deferred\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fB__sparc_utrap_install()\fR function establishes \fInew_precise\fR and
\fInew_deferred\fR user trap handlers as the new values for the specified
\fItype\fR and returns the existing user trap handler values in
\fB*\fR\fIold_precise\fR and \fB*\fR\fIold_deferred\fR in a single atomic
operation. A new handler address of \fINULL\fR means no user handler of that
type will be installed. A new handler address of \fBUTH_NOCHANGE\fR means that
the user handler for that type should not be changed. An old handler pointer of
\fINULL\fR means that the user is not interested in the old handler address.
.sp
.LP
A \fIprecise trap\fR is caused by a specific instruction and occurs before any
program-visible state has been changed by this instruction. When a precise trap
occurs, the program counter (PC) saved in the Trap Program Counter (TPC)
register points to the instruction that induced the trap; all instructions
prior to this trapping instruction have been executed.  The next program
counter (nPC) saved in the Trap Next Program Counter (TnPC) register points to
the next instruction following the trapping instruction, which has not yet been
executed.  A \fIdeferred trap\fR is also caused by a particular instruction,
but unlike a precise trap, a deferred trap may occur after the program-visible
state has been changed.  See the \fISPARC Architecture Manual, Version 9\fR for
further information on precise and deferred traps.
.sp
.LP
The list that follows contains hardware traps and their corresponding user trap
types. User trap types marked with a plus-sign (\fB+\fR) are required and must
be provided by all ABI-conforming implementations.  The others may not be
present on every implementation; an attempt to install a user trap handler for
those conditions will return \fBEINVAL\fR. User trap types marked with an
asterisk (\fB*\fR) are implemented as precise traps only.
.sp

.sp
.TS
box;
c | c
l | l .
\fBTrap Name\fR	\fBUser Trap Type (utrap_entry_t)\fR
_
\fBillegal_instruction\fR	T{
\fBUT_ILLTRAP_INSTRUCTION\fR +*\fB or UT_ILLEGAL_INSTRUCTION\fR
T}
_
\fBfp_disabled\fR	\fBUT_FP_DISABLED\fR +*
_
\fBfp_exception_ieee_754\fR	\fBUT_FP_EXCEPTION_IEEE_754\fR +
_
\fBfp_exception_other\fR	\fBUT_FP_EXCEPTION_OTHER\fR
_
\fBtag_overflow\fR	\fBUT_TAG_OVERFLOW\fR +*
_
\fBdivision_by_zero\fR	\fBUT_DIVISION_BY_ZERO\fR +
_
\fBmem_address_not_aligned\fR	\fBUT_MEM_ADDRESS_NOT_ALIGNED\fR +
_
\fBprivileged_action\fR	\fBUT_PRIVILEGED_ACTION\fR +
_
\fBprivileged_opcode\fR	\fBUT_PRIVILEGED_OPCODE\fR
_
\fBasync_data_error\fR	\fBUT_ASYNC_DATA_ERROR\fR
_
\fBtrap_instruction\fR	T{
\fBUT_TRAP_INSTRUCTION_16 \fRthrough \fBUT_TRAP_INSTRUCTION_31\fR +*
T}
_
T{
\fBinstruction_access_exception\fR \fBinstruction_access_MMU_miss\fR \fBinstruction_access_error\fR
T}	T{
\fBUT_INSTRUCTION_EXCEPTION \fRor \fBUT_INSTRUCTION_PROTECTION \fRor \fBUT_INSTRUCTION_ERROR \fR
T}
_
T{
\fBdata_access_exception\fR \fBdata_access_MMU_miss\fR \fBdata_access_error\fR \fBdata_access_protection\fR
T}	T{
\fBUT_DATA_EXCEPTION \fRor \fBUT_DATA_PROTECTION \fRor \fBUT_DATA_ERROR\fR
T}
.TE

.sp
.LP
The following explanations are provided for those user trap types that are not
self-explanatory.
.sp
.ne 2
.na
\fB\fBUT_ILLTRAP_INSTRUCTION\fR\fR
.ad
.sp .6
.RS 4n
This trap is raised by user execution of the \fBILLTRAP\fR \fBINSTRUCTION.\fR
It is always precise.
.RE

.sp
.ne 2
.na
\fB\fBUT_ILLEGAL_INSTRUCTION\fR\fR
.ad
.sp .6
.RS 4n
This trap will be raised by the execution of otherwise undefined opcodes. It is
implementation-dependent as to what opcodes raise this trap; the ABI only
specifies the interface. The trap may be precise or deferred.
.RE

.sp
.ne 2
.na
\fB\fBUT_PRIVILEGED_OPCODE\fR\fR
.ad
.sp .6
.RS 4n
All opcodes declared to be privileged in SPARC V9 will raise this trap. It is
implementation-dependent whether other opcodes will raise it as well; the ABI
only specifies the interface.
.RE

.sp
.ne 2
.na
\fB\fBUT_DATA_EXCEPTION,\fR \fBUT_INSTRUCTION_EXCEPTION\fR\fR
.ad
.sp .6
.RS 4n
No valid user mapping can be made to this address, for a data or instruction
access, respectively.
.RE

.sp
.ne 2
.na
\fB\fBUT_DATA_PROTECTION,\fR \fBUT_INSTRUCTION_PROTECTION\fR\fR
.ad
.sp .6
.RS 4n
A valid mapping exists, and user privilege to it exists, but the type of access
(read, write, or execute) is denied, for a data or instruction access,
respectively.
.RE

.sp
.ne 2
.na
\fB\fBUT_DATA_ERROR,\fR \fBUT_INSTRUCTION_ERROR\fR\fR
.ad
.sp .6
.RS 4n
A valid mapping exists, and both user privilege and the type of access are
allowed, but an unrecoverable error occurred in attempting the access, for a
data or instruction access, respectively. \fB%l1\fR will contain either
\fBBUS_ADDRERR\fR or \fBBUS_OBJERR.\fR
.RE

.sp
.ne 2
.na
\fB\fBUT_FP_DISABLED\fR\fR
.ad
.sp .6
.RS 4n
This trap is raised when an application issues a floating point instruction
(including load or store) and the SPARC V9 Floating Point Registers State
(FPRS) FEF bit is 0. If a user handler is installed for this trap, it will be
given control. Otherwise the system will set FEF to one and retry the
instruction.
.RE

.sp
.LP
For all traps, the handler executes in a new register window, where the
\fIin\fR registers are the \fIout\fR registers of the previous frame and have
the value they contained at the time of the trap, similar to a normal
subroutine call after the \fBsave\fR instruction. The \fIglobal\fR registers
(including the special registers \fB%ccr\fR, \fB%asi\fR, and \fB%y\fR) and the
\fIfloating-point\fR registers have their values from the time of the trap. The
stack pointer register \fB%sp\fR plus the BIAS will point to a properly-aligned
128-byte register save area; if the handler needs scratch space, it should
decrement the stack pointer to obtain it. If the handler needs access to the
previous frame's \fIin\fR registers or \fIlocal\fR registers, it should execute
a \fBFLUSHW\fR instruction, and then access them off of the frame pointer. If
the handler calls an ABI-conforming function, it must set the \fB%asi\fR
register to \fBASI_PRIMARY_NOFAULT\fR before the call.
.sp
.LP
On entry to a precise user trap handler  \fB%l6\fR contains the \fB%pc\fR and
\fB%l7\fR contains the \fB%npc\fR at the time of the trap.  To return from a
handler and reexecute the trapped instruction, the handler would execute:
.sp
.in +2
.nf
jmpl %l6, %g0 ! Trapped PC supplied to user trap handler
return %l7    ! Trapped nPC supplied to user trap handler
.fi
.in -2
.sp

.sp
.LP
To return from a handler and skip the trapped instruction, the handler would
execute:
.sp
.in +2
.nf
jmpl %l7, %g0 ! Trapped nPC supplied to user trap handler
return %l7 + 4 ! Trapped nPC + 4
.fi
.in -2
.sp

.sp
.LP
On entry to a deferred trap handler \fB%o0\fR contains the address of the
instruction that caused the trap and \fB%o1\fR contains the actual instruction
(right-justified, zero-extended), if the information is available. Otherwise
\fB%o0\fR contains the value \(mi1 and \fB%o1\fR is undefined.  Additional
information may be made available for certain cases of deferred traps, as
indicated in the following table.
.sp

.sp
.TS
box;
l | l
l | l .
\fBInstructions\fR	\fBAdditional Information\fR
_
LD-type (LDSTUB)	T{
\fB%o2\fR contains the effective address (\fIrs1\fR + \fIrs2\fR | \fIsimm13\fR).
T}
_
ST-type (CAS, SWAP)	T{
\fB%o2\fR contains the effective address (\fI rs1\fR + \fIrs2\fR |\fIsimm13\fR).
T}
_
Integer arithmetic	T{
\fB%o2\fR contains the \fIrs1\fR value. \fB%o3\fR contains the \fIrs2\fR | \fIsimm13\fR value. \fB%o4\fR contains the contents of the \fB%y\fR register.
T}
_
Floating-point arithmetic	T{
\fB%o2\fR contains the address of \fIrs1\fR value. \fB%o3\fR contains the address of \fIrs2\fR value.
T}
_
Control-transfer	T{
\fB%o2\fR contains the target address (\fIrs1\fR + \fIrs2\fR | \fIsimm13\fR).
T}
_
Asynchronous data errors	T{
\fB%o2\fR contains the address that caused the error. \fB%o3\fR contains the effective ASI, if available, else \(mi1.
T}
.TE

.sp
.LP
To return from a deferred trap, the trap handler issues:
.sp
.LP
ta    68    ! ST_RETURN_FROM_DEFERRED_TRAP
.sp
.LP
The following pseudo-code explains how the operating system dispatches traps:
.sp
.in +2
.nf
if (precise trap) {
      if (precise_handler) {
           invoke(precise_handler);
           /* not reached */
      } else {
           convert_to_signal(precise_trap);
      }
 } else if (deferred_trap) {
      invoke(deferred_handler);
           /* not reached */
      } else {
           convert_to_signal(deferred_trap);
      }
 }
 if (signal)
           send(signal);
.fi
.in -2

.sp
.LP
User trap handlers must preserve all registers except the \fIlocals\fR
(\fB%l0-7\fR) and the \fIouts\fR (\fB%o0-7\fR), that is, \fB%i0-7\fR,
\fB%g1-7\fR, \fB%d0-d62\fR, \fB%asi\fR, \fB%fsr\fR, \fB%fprs\fR, \fB%ccr\fR,
and \fB%y,\fR except to the extent that modifying the registers is part of the
desired functionality of the handler. For example, the handler for
\fBUT_FP_DISABLED\fR may load floating-point registers.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fB0\fR is returned. Otherwise, a non-zero value is
returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fB__sparc_utrap_install()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fItype\fR argument is not a supported user trap type; the new user trap
handler address is not word aligned; the old user trap handler address cannot
be returned; or the user program is not a 64-bit executable.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRA sample program using the \fB__sparc_utrap_install()\fR
function.
.sp
.LP
The \fB__sparc_utrap_install()\fR function is normally used by user programs
that wish to provide their own tailored exception handlers as a faster
alternative to \fBsignal\fR(3C), or to handle exceptions that are not directly
supported by the \fBsignal()\fR interface, such as \fBfp_disabled\fR.

.sp
.in +2
.nf
extern void *fpdis_trap_handler();
utrap_handler_t new_precise = (utrap_handler_t)fpdis_trap_handler;
double d;
int err;
err = __sparc_utrap_install(UT_FP_DISABLED, new_precise,
    UTH_NOCHANGE, NULL, NULL);
if (err == EINVAL) {
        /* unexpected error, do something */
        exit (1);
}
d = 1.0e-300;
ENTRY(fpdis_trap_handler)
wr      %g0, FPRS_FEF, %fprs
jmpl    %l6, %g0
return  %l7
SET_SIZE(fpdis_trap_handler)
.fi
.in -2

.sp
.LP
This example turns on bit 2, FEF, in the Floating-Point Registers State (FPRS)
Register, after a floating-point instruction causes an \fBfp_disabled\fR trap.
(Note that this example simulates part of the default system behavior; programs
do not need such a handler. The example is for illustrative purposes only.)

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBsignal\fR(3C), \fBattributes\fR(5)
.sp
.LP
\fISPARC Architecture Manual, Version 9\fR
.sp
.LP
Manufacturer's processor chip user manuals
.SH NOTES
.sp
.LP
The Exceptions and Interrupt Descriptions section of the SPARC V9 manual
documents which hardware traps are mandatory or optional, and whether they can
be implemented as precise or deferred traps, or both.  The manufacturer's
processor chip user manuals describe the details of the traps supported for the
specific processor implementation.