1 // Copyright 2014 The Crashpad Authors. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_ 16 #define CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_ 17 18 #include <mach/mach.h> 19 20 namespace crashpad { 21 22 //! \brief `MACH_PORT_NULL` with the correct type for a Mach port, 23 //! `mach_port_t`. 24 //! 25 //! For situations where implicit conversions between signed and unsigned types 26 //! are not performed, use kMachPortNull instead of an explicit `implicit_cast` 27 //! of `MACH_PORT_NULL` to `mach_port_t`. This is useful for logging and testing 28 //! assertions. 29 constexpr mach_port_t kMachPortNull = MACH_PORT_NULL; 30 31 //! \brief `MACH_EXCEPTION_CODES` with the correct type for a Mach exception 32 //! behavior, `exception_behavior_t`. 33 //! 34 //! Signedness problems can occur when ORing `MACH_EXCEPTION_CODES` as a signed 35 //! integer, because a signed integer overflow results. This constant can be 36 //! used instead of `MACH_EXCEPTION_CODES` in such cases. 37 constexpr exception_behavior_t kMachExceptionCodes = MACH_EXCEPTION_CODES; 38 39 // Because exception_mask_t is an int and has one bit for each defined 40 // exception_type_t, it’s reasonable to assume that there cannot be any 41 // officially-defined exception_type_t values higher than 31. 42 // kMachExceptionSimulated uses a value well outside this range because it does 43 // not require a corresponding mask value. Simulated exceptions are delivered to 44 // the exception handler registered for EXC_CRASH exceptions using 45 // EXC_MASK_CRASH. 46 47 //! \brief An exception type to use for simulated exceptions. 48 constexpr exception_type_t kMachExceptionSimulated = 'CPsx'; 49 50 //! \brief A const version of `thread_state_t`. 51 //! 52 //! This is useful as the \a old_state parameter to exception handler functions. 53 //! Normally, these parameters are of type `thread_state_t`, but this allows 54 //! modification of the state, which is conceptually `const`. 55 using ConstThreadState = const natural_t*; 56 57 //! \brief Like `mach_thread_self()`, but without the obligation to release the 58 //! send right. 59 //! 60 //! `mach_thread_self()` returns a send right to the current thread port, 61 //! incrementing its reference count. This burdens the caller with maintaining 62 //! this send right, and calling `mach_port_deallocate()` when it is no longer 63 //! needed. This is burdensome, and is at odds with the normal operation of 64 //! `mach_task_self()`, which does not increment the task port’s reference count 65 //! whose result must not be deallocated. 66 //! 67 //! Callers can use this function in preference to `mach_thread_self()`. This 68 //! function returns an extant reference to the current thread’s port without 69 //! incrementing its reference count. 70 //! 71 //! \return The value of `mach_thread_self()` without incrementing its reference 72 //! count. The returned port must not be deallocated by 73 //! `mach_port_deallocate()`. The returned value is valid as long as the 74 //! thread continues to exist as a `pthread_t`. 75 thread_t MachThreadSelf(); 76 77 //! \brief Creates a new Mach port in the current task. 78 //! 79 //! This function wraps the `mach_port_allocate()` providing a simpler 80 //! interface. 81 //! 82 //! \param[in] right The type of right to create. 83 //! 84 //! \return The new Mach port. On failure, `MACH_PORT_NULL` with a message 85 //! logged. 86 mach_port_t NewMachPort(mach_port_right_t right); 87 88 //! \brief The value for `EXC_MASK_ALL` appropriate for the operating system at 89 //! run time. 90 //! 91 //! The SDK’s definition of `EXC_MASK_ALL` has changed over time, with later 92 //! versions containing more bits set than earlier versions. However, older 93 //! kernels will reject exception masks that contain bits set that they don’t 94 //! recognize. Calling this function will return a value for `EXC_MASK_ALL` 95 //! appropriate for the system at run time. 96 //! 97 //! \note `EXC_MASK_ALL` does not include the value of `EXC_MASK_CRASH` or 98 //! `EXC_MASK_CORPSE_NOTIFY`. Consumers that want `EXC_MASK_ALL` along with 99 //! `EXC_MASK_CRASH` may use ExcMaskAll() `| EXC_MASK_CRASH`. Consumers may 100 //! use ExcMaskValid() for `EXC_MASK_ALL` along with `EXC_MASK_CRASH`, 101 //! `EXC_MASK_CORPSE_NOTIFY`, and any values that come into existence in the 102 //! future. 103 exception_mask_t ExcMaskAll(); 104 105 //! \brief An exception mask containing every possible exception understood by 106 //! the operating system at run time. 107 //! 108 //! `EXC_MASK_ALL`, and thus ExcMaskAll(), never includes the value of 109 //! `EXC_MASK_CRASH` or `EXC_MASK_CORPSE_NOTIFY`. For situations where an 110 //! exception mask corresponding to every possible exception understood by the 111 //! running kernel is desired, use this function instead. 112 //! 113 //! Should new exception types be introduced in the future, this function will 114 //! be updated to include their bits in the returned mask value when run time 115 //! support is present. 116 exception_mask_t ExcMaskValid(); 117 118 } // namespace crashpad 119 120 #endif // CRASHPAD_UTIL_MACH_MACH_EXTENSIONS_H_ 121