usr/src/uts/common/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 #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 */