libdarwin/h/mach_exception.h

   1 /*
   2  * Copyright (c) 2018 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25  * @header
  26  * Darwin-specific interfaces for manipulating Mach exception handling
  27  * properties of a task.
  28  */
  29 #ifndef __DARWIN_EXCEPTION_H
  30 #define __DARWIN_EXCEPTION_H
  31
  32 #include <os/base.h>
  33 #include <os/api.h>
  34
  35 #include <sys/cdefs.h>
  36 #include <spawn.h>
  37
  38 #include <mach/mach.h>
  39 #include <mach/port.h>
  40 #include <mach/mach_port.h>
  41 #include <mach/kern_return.h>
  42
  43 #if DARWIN_TAPI
  44 #include "tapi.h"
  45 #endif
  46
  47 __BEGIN_DECLS;
  48
  49 /*!
  50  * @typedef os_crash_flags_t
  51  * A flagset describing crash handling behaviors.
  52  *
  53  * @param OS_CRASH_FLAG_INIT
  54  * Handle no exceptions.
  55  *
  56  * @param OS_CRASH_FLAG_CRASH
  57  * Handle exceptions due to crashing conditions (e.g. segmentation violations,
  58  * signals raise(3)ed manually, etc.). These exceptions will suspend the subject
  59  * task until the exception handler has returned.
  60  *
  61  * @param OS_CRASH_FLAG_GUARD
  62  * Handle exceptions due to the subject task violating guarded kernel handles
  63  * (e.g. guarded mach port rights and file descriptors).
  64  *
  65  * @param OS_CRASH_FLAG_RESOURCE
  66  * Handle exceptions due to the subject task exceeding resource usage limits
  67  * (e.g. CPU spins, memory growth, etc.).
  68  *
  69  * @param OS_CRASH_FLAG_CORPSE
  70  * Handle exceptions which create corpses. The subject task of these exceptions
  71  * is a corpse of the original task, which is torn down asynchronously. Corpses
  72  * are a limited representation of the original task that is suitable for most
  73  * introspection needs.
  74  *
  75  * This flag is mutually exclusive with {@link OS_CRASH_FLAG_CRASH}, and if both
  76  * are present, this flag will be preferred.
  77  *
  78  * @discussion
  79  * There are other Mach exception types than the ones enumerated by these flags,
  80  * but they are almost exclusively handled internally by the kernel, and
  81  * therefore are of little interest to userspace. Those that are not handled by
  82  * the kernel are only relevant to debuggers.
  83  */
  84 OS_ENUM(os_crash_flags, uint32_t,
  85         OS_CRASH_FLAG_INIT = 0,
  86         OS_CRASH_FLAG_CRASH = (1 << 0),
  87         OS_CRASH_FLAG_GUARD = (1 << 1),
  88         OS_CRASH_FLAG_RESOURCE = (1 << 2),
  89         OS_CRASH_FLAG_CORPSE = (1 << 3),
  90 );
  91
  92 /*!
  93  * @enum os_crash_type_t
  94  * A type describing exception types relevant to userspace crash reporters.
  95  * These values serve as indexes into a {@link os_crash_port_array_t}.
  96  *
  97  * @const OS_CRASH_NONE
  98  * No exception type.
  99  *
 100  * @const OS_CRASH_CRASH
 101  * A crashing exception with the behavior described in {@link OS_CRASH_FLAG_CRASH}.
 102  *
 103  * @const OS_CRASH_GUARD
 104  * A guard exception with the behavior described in {@link OS_CRASH_FLAG_GUARD}.
 105  *
 106  * @const OS_CRASH_RESOURCE
 107  * A resource exception with the behavior described in {@link OS_CRASH_FLAG_RESOURCE}.
 108  *
 109  * @const OS_CRASH_CORPSE
 110  * A corpse exception with the behavior described in {@link OS_CRASH_FLAG_CORPSE}.
 111  */
 112 OS_ENUM(os_crash_type, uint32_t,
 113         OS_CRASH_NONE,
 114         OS_CRASH_CRASH,
 115         OS_CRASH_GUARD,
 116         OS_CRASH_RESOURCE,
 117         OS_CRASH_CORPSE,
 118         _OS_CRASH_LAST,
 119 );
 120
 121 /*!
 122  * struct os_crash_port_t
 123  * A type describing an exception port and the exception it handles.
 124  *
 125  * @property oep_type
 126  * The type of exception handled by the port.
 127  *
 128  * @property oep_port
 129  * A handle representing a send right to the exception port.
 130  */
 131 DARWIN_API_AVAILABLE_20170407
 132 typedef struct _os_crash_port {
 133         os_crash_type_t oep_type;
 134         mach_port_t oep_port;
 135 } os_crash_port_t;
 136
 137 /*!
 138  * @define DARWIN_EXCEPTION_PORT_ARRAY_COUNT
 139  * The maximum number of exception ports that an exception port array can
 140  * accommodate.
 141  */
 142 #define OS_CRASH_PORT_ARRAY_COUNT (16lu)
 143
 144 /*!
 145  * @typedef os_crash_port_array_t
 146  * An array of exception ports. This array can accommodate all exception types
 147  * described in the {@link os_crash_type_t} type and is sized to
 148  * accommodate future exception types.
 149  */
 150 DARWIN_API_AVAILABLE_20170407
 151 typedef os_crash_port_t os_crash_port_array_t[OS_CRASH_PORT_ARRAY_COUNT];
 152
 153 /*!
 154  * @function os_crash_set_reporter_port
 155  * Routine to set the exception handler port for the exceptions given.
 156  *
 157  * @param where
 158  * The task port or host port for which to set the exception handler. This
 159  * routine will internally choose the proper method of setting the exception
 160  * port based on whether this parameter represents the host or not.
 161  *
 162  * @param flags
 163  * Flags describing which exceptions are to be handled by the port.
 164  *
 165  * @param p
 166  * A send right to the desired exception handler port.
 167  *
 168  * @result
 169  * A kernel return code.
 170  *
 171  * @discussion
 172  * This routine automatically chooses the most expressive thread state to
 173  * deliver in the exception message based on the current architecture.
 174  */
 175 DARWIN_API_AVAILABLE_20170407
 176 OS_EXPORT OS_WARN_RESULT
 177 kern_return_t
 178 os_crash_set_reporter_port(mach_port_t where,
 179                 os_crash_flags_t flags, mach_port_t p);
 180
 181 /*!
 182  * @function os_crash_get_reporter_port_array
 183  * Routine to get the ports which handle exceptions for all enumerated exception
 184  * types in {@link os_crash_flags_t}.
 185  *
 186  * @param where
 187  * The task port or host port for which to retrieve exception handler ports.
 188  * This routine will internally choose the proper method of obtaining the
 189  * exception ports based on whether this parameter represents the host or not.
 190  *
 191  * @param array
 192  * An array describing the exception ports for the target host or task. This
 193  * array must be disposed of with {@link os_crash_port_array_deallocate}
 194  * when it is no longer needed.
 195  *
 196  * @result
 197  * A kernel return code.
 198  */
 199 DARWIN_API_AVAILABLE_20170407
 200 OS_EXPORT OS_WARN_RESULT OS_NONNULL2
 201 kern_return_t
 202 os_crash_get_reporter_port_array(mach_port_t where,
 203                 os_crash_port_array_t array);
 204
 205 /*!
 206  * @function os_crash_port_array_deallocate
 207  * Routine to deallocate an array of exception port descriptors.
 208  *
 209  * @param array
 210  * The array which is to be disposed of.
 211  *
 212  * @discussion
 213  * This routine disposes of the resources represented by the kernel handles in
 214  * the array. It does not manipulate the array's memory. The expectation is that
 215  * the caller allocates {@link os_crash_port_array_t} from the stack.
 216  */
 217 DARWIN_API_AVAILABLE_20170407
 218 OS_EXPORT OS_NONNULL1
 219 void
 220 os_crash_port_array_deallocate(os_crash_port_array_t array);
 221
 222 /*!
 223  * @function os_crash_spawnattr_set_reporter_port
 224  * Routine to set the exception handler port for the exceptions given in a
 225  * posix_spawn(2) attributes structure.
 226  *
 227  * @param psattr
 228  * The spawn attributes for which the exception port should be set.
 229  *
 230  * @param flags
 231  * Flags describing which exceptions are to be handled by the port.
 232  *
 233  * @param p
 234  * A send right to the desired exception handler port.
 235  *
 236  * @result
 237  * A kernel return code. This routine will only fail if the port name given was
 238  * invalid.
 239  */
 240 DARWIN_API_AVAILABLE_20170407
 241 OS_EXPORT OS_WARN_RESULT OS_NONNULL1
 242 kern_return_t
 243 os_crash_spawnattr_set_reporter_port(posix_spawnattr_t *psattr,
 244                 os_crash_flags_t flags, mach_port_t p);
 245
 246 __END_DECLS;
 247
 248 #endif // __DARWIN_EXCEPTION_H