ontrap.h revision 7c478bd95313f5f23a4c958a745db2134aa03244
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (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]
*
* CDDL HEADER END
*/
/*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _ONTRAP_H
#define _ONTRAP_H
#pragma ident "%Z%%M% %I% %E% SMI"
#if !defined(_ASM)
#include <sys/types.h>
#endif
#ifdef __cplusplus
extern "C" {
#endif
/*
* on_trap() provides protection against various kinds of machine exceptions,
* and must be used with extreme caution. Like setjmp(), on_trap() returns
* zero when explicitly called and non-zero when it returns as the result of
* an exception. The caller should not attempt to interpret the actual integer
* return value except to test whether it is zero or non-zero. on_trap() and
* no_trap() are NOT DDI interfaces for public consumption. For now, the
* on_trap() mechanism is separate from on_fault() protection and the t_lofault
* protection used by the various copy routines.
*
* Calls to on_trap() may be nested, but only the most recently installed bits
* apply. Protection bits may be OR-ed together if the caller wishes to
* protect against more than one type of trap. If on_trap() returns non-zero,
* the bit corresponding to the trap that triggered return to on_trap() will
* be stored in the ot_trap field of the caller's on_trap_data.
*
* After calling on_trap(), the caller may elect to modify ot_trampoline to
* install a custom trampoline routine prior to executing the protected code
* region. No other fields of the on_trap_data should be modified by the
* caller. The trampoline may not be applicable on all platforms.
*
* The on_trap_data structures are kept in a stack (linked list) whose top
* is pointed to by the current thread's t_ontrap field. A no_trap() call
* pops the top element from the stack and resets t_ontrap to ot_prev.
* We assume the caller has allocated the on_trap_data on the stack or
* made other arrangements, so we do not need to worry about deallocation.
*
* If repeated calls to on_trap() are made using the same on_trap_data address,
* the topmost stack element is modified in-place (the same on_trap_data is
* not pushed twice), allowing callers to use on_trap() in a loop. The act
* of catching an exception does NOT modify t_ontrap. Even if on_trap()
* returns non-zero, the caller must use no_trap() to clear trap protection.
*
* Calls to no_trap() are permitted when the on_trap_data stack is empty; they
* have no effect. no_trap() only modifies t_ontrap; it does not modify the
* internals of the topmost on_trap_data element. It is therefore legal for
* callers to examine the contents of the on_trap_data (specifically ot_trap)
* after the data is popped using no_trap().
*
* A given platform may not implement all the forms of on_trap() protection.
* The on_trap_data will be pushed on the t_ontrap stack with ot_prot set
* regardless. We must guarantee that if the platform does not implement
* a trap protection, the exceptional condition will trigger a panic. We do
* not permit a platform to allow the exceptional condition to occur silently
* and then continue to execute the caller's protected code region.
*/
#define OT_DATA_ACCESS 0x01 /* data access exception protection */
#define OT_DATA_EC 0x02 /* error correction trap protection */
#if !defined(_ASM)
typedef struct on_trap_data {
ushort_t ot_prot; /* active protection bits (see above) */
ushort_t ot_trap; /* bit of actual trap that occurred */
uintptr_t ot_trampoline; /* %pc for trap return (if any) */
label_t ot_jmpbuf; /* label for longjmp back to on_trap */
struct on_trap_data *ot_prev; /* pointer to previous on_trap_data */
void *ot_handle; /* access handle */
void *ot_pad1; /* reserved for future use */
} on_trap_data_t;
#if defined(_KERNEL)
extern int on_trap(on_trap_data_t *, uint_t);
#pragma unknown_control_flow(on_trap)
extern void no_trap(void);
extern void on_trap_trampoline(void); /* default trampoline */
#endif /* _KERNEL */
#endif /* !_ASM */
#ifdef __cplusplus
}
#endif
#endif /* _ONTRAP_H */