include/sys/ontrap.h

   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 */