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]
__sparc_utrap_install - install a SPARC V9 user trap handler

#include <sys/utrap.h>

int __sparc_utrap_install(utrap_entry_t type,
 utrap_handler_t new_precise, utrap_handler_t new_deferred,
 utrap_handler_t *old_precise, utrap_handler_t *old_deferred);

The __sparc_utrap_install() function establishes new_precise and new_deferred user trap handlers as the new values for the specified type and returns the existing user trap handler values in *old_precise and *old_deferred in a single atomic operation. A new handler address of NULL means no user handler of that type will be installed. A new handler address of UTH_NOCHANGE means that the user handler for that type should not be changed. An old handler pointer of NULL means that the user is not interested in the old handler address.

A precise trap 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 deferred trap 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 SPARC Architecture Manual, Version 9 for further information on precise and deferred traps.

The list that follows contains hardware traps and their corresponding user trap types. User trap types marked with a plus-sign (+) 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 EINVAL. User trap types marked with an asterisk (*) are implemented as precise traps only.

Trap Name	User Trap Type (utrap_entry_t)
illegal_instruction
UT_ILLTRAP_INSTRUCTION +* or UT_ILLEGAL_INSTRUCTION
fp_disabled	UT_FP_DISABLED +*
fp_exception_ieee_754	UT_FP_EXCEPTION_IEEE_754 +
fp_exception_other	UT_FP_EXCEPTION_OTHER
tag_overflow	UT_TAG_OVERFLOW +*
division_by_zero	UT_DIVISION_BY_ZERO +
mem_address_not_aligned	UT_MEM_ADDRESS_NOT_ALIGNED +
privileged_action	UT_PRIVILEGED_ACTION +
privileged_opcode	UT_PRIVILEGED_OPCODE
async_data_error	UT_ASYNC_DATA_ERROR
trap_instruction
UT_TRAP_INSTRUCTION_16 through UT_TRAP_INSTRUCTION_31 +*
instruction_access_exception instruction_access_MMU_miss instruction_access_error
UT_INSTRUCTION_EXCEPTION or UT_INSTRUCTION_PROTECTION or UT_INSTRUCTION_ERROR
data_access_exception data_access_MMU_miss data_access_error data_access_protection
UT_DATA_EXCEPTION or UT_DATA_PROTECTION or UT_DATA_ERROR

The following explanations are provided for those user trap types that are not self-explanatory.

UT_ILLTRAP_INSTRUCTION

UT_ILLEGAL_INSTRUCTION

UT_PRIVILEGED_OPCODE

UT_DATA_EXCEPTION, UT_INSTRUCTION_EXCEPTION

UT_DATA_PROTECTION, UT_INSTRUCTION_PROTECTION

UT_DATA_ERROR, UT_INSTRUCTION_ERROR

UT_FP_DISABLED

For all traps, the handler executes in a new register window, where the in registers are the out 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 save instruction. The global registers (including the special registers %ccr, %asi, and %y) and the floating-point registers have their values from the time of the trap. The stack pointer register %sp 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 in registers or local registers, it should execute a FLUSHW instruction, and then access them off of the frame pointer. If the handler calls an ABI-conforming function, it must set the %asi register to ASI_PRIMARY_NOFAULT before the call.

On entry to a precise user trap handler %l6 contains the %pc and %l7 contains the %npc at the time of the trap. To return from a handler and reexecute the trapped instruction, the handler would execute:

jmpl %l6, %g0 ! Trapped PC supplied to user trap handler
return %l7 ! Trapped nPC supplied to user trap handler

To return from a handler and skip the trapped instruction, the handler would execute:

jmpl %l7, %g0 ! Trapped nPC supplied to user trap handler
return %l7 + 4 ! Trapped nPC + 4

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

Instructions	Additional Information
LD-type (LDSTUB)
%o2 contains the effective address (rs1 + rs2 | simm13).
ST-type (CAS, SWAP)
%o2 contains the effective address ( rs1 + rs2 |simm13).
Integer arithmetic
%o2 contains the rs1 value. %o3 contains the rs2 | simm13 value. %o4 contains the contents of the %y register.
Floating-point arithmetic
%o2 contains the address of rs1 value. %o3 contains the address of rs2 value.
Control-transfer
%o2 contains the target address (rs1 + rs2 | simm13).
Asynchronous data errors
%o2 contains the address that caused the error. %o3 contains the effective ASI, if available, else -1.

To return from a deferred trap, the trap handler issues:

ta 68 ! ST_RETURN_FROM_DEFERRED_TRAP

The following pseudo-code explains how the operating system dispatches traps:

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);

User trap handlers must preserve all registers except the locals (%l0-7) and the outs (%o0-7), that is, %i0-7, %g1-7, %d0-d62, %asi, %fsr, %fprs, %ccr, and %y, except to the extent that modifying the registers is part of the desired functionality of the handler. For example, the handler for UT_FP_DISABLED may load floating-point registers.

Upon successful completion, 0 is returned. Otherwise, a non-zero value is returned and errno is set to indicate the error.

The __sparc_utrap_install() function will fail if:

EINVAL

Example 1 A sample program using the __sparc_utrap_install() function.

The __sparc_utrap_install() function is normally used by user programs that wish to provide their own tailored exception handlers as a faster alternative to signal(3C), or to handle exceptions that are not directly supported by the signal() interface, such as fp_disabled.

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)

This example turns on bit 2, FEF, in the Floating-Point Registers State (FPRS) Register, after a floating-point instruction causes an fp_disabled 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.)

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

signal(3C), attributes(5)

SPARC Architecture Manual, Version 9

Manufacturer's processor chip user manuals

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.