xref: /illumos-gate/usr/src/uts/common/sys/ontrap.h (revision 6a3e8e86)
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 #if !defined(_ASM)
30 #include <sys/types.h>
31 #endif
32 
33 #ifdef	__cplusplus
34 extern "C" {
35 #endif
36 
37 /*
38  * on_trap() provides protection against various kinds of machine exceptions,
39  * and must be used with extreme caution.  Like setjmp(), on_trap() returns
40  * zero when explicitly called and non-zero when it returns as the result of
41  * an exception.  The caller should not attempt to interpret the actual integer
42  * return value except to test whether it is zero or non-zero.  on_trap() and
43  * no_trap() are NOT DDI interfaces for public consumption.  For now, the
44  * on_trap() mechanism is separate from on_fault() protection and the t_lofault
45  * protection used by the various copy routines.
46  *
47  * Calls to on_trap() may be nested, but only the most recently installed bits
48  * apply.  Protection bits may be OR-ed together if the caller wishes to
49  * protect against more than one type of trap.  If on_trap() returns non-zero,
50  * the bit corresponding to the trap that triggered return to on_trap() will
51  * be stored in the ot_trap field of the caller's on_trap_data.
52  *
53  * After calling on_trap(), the caller may elect to modify ot_trampoline to
54  * install a custom trampoline routine prior to executing the protected code
55  * region.  No other fields of the on_trap_data should be modified by the
56  * caller.  The trampoline may not be applicable on all platforms.
57  *
58  * The on_trap_data structures are kept in a stack (linked list) whose top
59  * is pointed to by the current thread's t_ontrap field.  A no_trap() call
60  * pops the top element from the stack and resets t_ontrap to ot_prev.
61  * We assume the caller has allocated the on_trap_data on the stack or
62  * made other arrangements, so we do not need to worry about deallocation.
63  *
64  * If repeated calls to on_trap() are made using the same on_trap_data address,
65  * the topmost stack element is modified in-place (the same on_trap_data is
66  * not pushed twice), allowing callers to use on_trap() in a loop.  The act
67  * of catching an exception does NOT modify t_ontrap.  Even if on_trap()
68  * returns non-zero, the caller must use no_trap() to clear trap protection.
69  *
70  * Calls to no_trap() are permitted when the on_trap_data stack is empty; they
71  * have no effect.  no_trap() only modifies t_ontrap; it does not modify the
72  * internals of the topmost on_trap_data element.  It is therefore legal for
73  * callers to examine the contents of the on_trap_data (specifically ot_trap)
74  * after the data is popped using no_trap().
75  *
76  * A given platform may not implement all the forms of on_trap() protection.
77  * The on_trap_data will be pushed on the t_ontrap stack with ot_prot set
78  * regardless.  We must guarantee that if the platform does not implement
79  * a trap protection, the exceptional condition will trigger a panic.  We do
80  * not permit a platform to allow the exceptional condition to occur silently
81  * and then continue to execute the caller's protected code region.
82  */
83 
84 #define	OT_DATA_ACCESS	0x01		/* data access exception protection */
85 #define	OT_DATA_EC	0x02		/* error correction trap protection */
86 
87 #if defined(__x86)
88 #define	OT_SEGMENT_ACCESS 0x03		/* segmentation exception */
89 #endif
90 
91 #if !defined(_ASM)
92 
93 typedef struct on_trap_data {
94 	ushort_t ot_prot;		/* active protection bits (see above) */
95 	ushort_t ot_trap;		/* bit of actual trap that occurred */
96 	uintptr_t ot_trampoline;	/* %pc for trap return (if any) */
97 	label_t ot_jmpbuf;		/* label for longjmp back to on_trap */
98 	struct on_trap_data *ot_prev;	/* pointer to previous on_trap_data */
99 	void *ot_handle;		/* access handle */
100 	void *ot_pad1;			/* reserved for future use */
101 } on_trap_data_t;
102 
103 #if defined(_KERNEL)
104 
105 extern int on_trap(on_trap_data_t *, uint_t) __RETURNS_TWICE;
106 #pragma	unknown_control_flow(on_trap)
107 extern void no_trap(void);
108 
109 extern void on_trap_trampoline(void);	/* default trampoline */
110 
111 #endif	/* _KERNEL */
112 #endif	/* !_ASM */
113 
114 #ifdef	__cplusplus
115 }
116 #endif
117 
118 #endif	/* _ONTRAP_H */
119