Home | History | Annotate | Download | only in sys
      1 /*
      2  * CDDL HEADER START
      3  *
      4  * The contents of this file are subject to the terms of the
      5  * Common Development and Distribution License (the "License").
      6  * You may not use this file except in compliance with the License.
      7  *
      8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
      9  * or http://www.opensolaris.org/os/licensing.
     10  * See the License for the specific language governing permissions
     11  * and limitations under the License.
     12  *
     13  * When distributing Covered Code, include this CDDL HEADER in each
     14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     15  * If applicable, add the following below this CDDL HEADER, with the
     16  * fields enclosed by brackets "[]" replaced with your own identifying
     17  * information: Portions Copyright [yyyy] [name of copyright owner]
     18  *
     19  * CDDL HEADER END
     20  */
     21 /*
     22  * Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
     23  * Use is subject to license terms.
     24  */
     25 
     26 #ifndef	_ONTRAP_H
     27 #define	_ONTRAP_H
     28 
     29 #pragma ident	"%Z%%M%	%I%	%E% SMI"
     30 
     31 #if !defined(_ASM)
     32 #include <sys/types.h>
     33 #endif
     34 
     35 #ifdef	__cplusplus
     36 extern "C" {
     37 #endif
     38 
     39 /*
     40  * on_trap() provides protection against various kinds of machine exceptions,
     41  * and must be used with extreme caution.  Like setjmp(), on_trap() returns
     42  * zero when explicitly called and non-zero when it returns as the result of
     43  * an exception.  The caller should not attempt to interpret the actual integer
     44  * return value except to test whether it is zero or non-zero.  on_trap() and
     45  * no_trap() are NOT DDI interfaces for public consumption.  For now, the
     46  * on_trap() mechanism is separate from on_fault() protection and the t_lofault
     47  * protection used by the various copy routines.
     48  *
     49  * Calls to on_trap() may be nested, but only the most recently installed bits
     50  * apply.  Protection bits may be OR-ed together if the caller wishes to
     51  * protect against more than one type of trap.  If on_trap() returns non-zero,
     52  * the bit corresponding to the trap that triggered return to on_trap() will
     53  * be stored in the ot_trap field of the caller's on_trap_data.
     54  *
     55  * After calling on_trap(), the caller may elect to modify ot_trampoline to
     56  * install a custom trampoline routine prior to executing the protected code
     57  * region.  No other fields of the on_trap_data should be modified by the
     58  * caller.  The trampoline may not be applicable on all platforms.
     59  *
     60  * The on_trap_data structures are kept in a stack (linked list) whose top
     61  * is pointed to by the current thread's t_ontrap field.  A no_trap() call
     62  * pops the top element from the stack and resets t_ontrap to ot_prev.
     63  * We assume the caller has allocated the on_trap_data on the stack or
     64  * made other arrangements, so we do not need to worry about deallocation.
     65  *
     66  * If repeated calls to on_trap() are made using the same on_trap_data address,
     67  * the topmost stack element is modified in-place (the same on_trap_data is
     68  * not pushed twice), allowing callers to use on_trap() in a loop.  The act
     69  * of catching an exception does NOT modify t_ontrap.  Even if on_trap()
     70  * returns non-zero, the caller must use no_trap() to clear trap protection.
     71  *
     72  * Calls to no_trap() are permitted when the on_trap_data stack is empty; they
     73  * have no effect.  no_trap() only modifies t_ontrap; it does not modify the
     74  * internals of the topmost on_trap_data element.  It is therefore legal for
     75  * callers to examine the contents of the on_trap_data (specifically ot_trap)
     76  * after the data is popped using no_trap().
     77  *
     78  * A given platform may not implement all the forms of on_trap() protection.
     79  * The on_trap_data will be pushed on the t_ontrap stack with ot_prot set
     80  * regardless.  We must guarantee that if the platform does not implement
     81  * a trap protection, the exceptional condition will trigger a panic.  We do
     82  * not permit a platform to allow the exceptional condition to occur silently
     83  * and then continue to execute the caller's protected code region.
     84  */
     85 
     86 #define	OT_DATA_ACCESS	0x01		/* data access exception protection */
     87 #define	OT_DATA_EC	0x02		/* error correction trap protection */
     88 
     89 #if defined(__x86)
     90 #define	OT_SEGMENT_ACCESS 0x03		/* segmentation exception */
     91 #endif
     92 
     93 #if !defined(_ASM)
     94 
     95 typedef struct on_trap_data {
     96 	ushort_t ot_prot;		/* active protection bits (see above) */
     97 	ushort_t ot_trap;		/* bit of actual trap that occurred */
     98 	uintptr_t ot_trampoline;	/* %pc for trap return (if any) */
     99 	label_t ot_jmpbuf;		/* label for longjmp back to on_trap */
    100 	struct on_trap_data *ot_prev;	/* pointer to previous on_trap_data */
    101 	void *ot_handle;		/* access handle */
    102 	void *ot_pad1;			/* reserved for future use */
    103 } on_trap_data_t;
    104 
    105 #if defined(_KERNEL)
    106 
    107 extern int on_trap(on_trap_data_t *, uint_t);
    108 #pragma	unknown_control_flow(on_trap)
    109 extern void no_trap(void);
    110 
    111 extern void on_trap_trampoline(void);	/* default trampoline */
    112 
    113 #endif	/* _KERNEL */
    114 #endif	/* !_ASM */
    115 
    116 #ifdef	__cplusplus
    117 }
    118 #endif
    119 
    120 #endif	/* _ONTRAP_H */
    121