1 //===-- crash_handler.h -----------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 // This file contains interface functions that can be called by an in-process or 10 // out-of-process crash handler after the process has terminated. Functions in 11 // this interface are never thread safe. For an in-process crash handler, the 12 // handler should call GuardedPoolAllocator::disable() to stop any other threads 13 // from retrieving new GWP-ASan allocations, which may corrupt the metadata. 14 #ifndef GWP_ASAN_INTERFACE_H_ 15 #define GWP_ASAN_INTERFACE_H_ 16 17 #include "gwp_asan/common.h" 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 // When a process crashes, there are three possible outcomes: 24 // 1. The crash is unrelated to GWP-ASan - in which case this function returns 25 // false. 26 // 2. The crash is internally detected within GWP-ASan itself (e.g. a 27 // double-free bug is caught in GuardedPoolAllocator::deallocate(), and 28 // GWP-ASan will terminate the process). In this case - this function 29 // returns true. 30 // 3. The crash is caused by a memory error at `AccessPtr` that's caught by the 31 // system, but GWP-ASan is responsible for the allocation. In this case - 32 // the function also returns true. 33 // This function takes an optional `AccessPtr` parameter. If the pointer that 34 // was attempted to be accessed is available, you should provide it here. In the 35 // case of some internally-detected errors, the crash may manifest as an abort 36 // or trap may or may not have an associated pointer. In these cases, the 37 // pointer can be obtained by a call to __gwp_asan_get_internal_crash_address. 38 bool __gwp_asan_error_is_mine(const gwp_asan::AllocatorState *State, 39 uintptr_t ErrorPtr = 0u); 40 41 // Diagnose and return the type of error that occurred at `ErrorPtr`. If 42 // `ErrorPtr` is unrelated to GWP-ASan, or if the error type cannot be deduced, 43 // this function returns Error::UNKNOWN. 44 gwp_asan::Error 45 __gwp_asan_diagnose_error(const gwp_asan::AllocatorState *State, 46 const gwp_asan::AllocationMetadata *Metadata, 47 uintptr_t ErrorPtr); 48 49 // For internally-detected errors (double free, invalid free), this function 50 // returns the pointer that the error occurred at. If the error is unrelated to 51 // GWP-ASan, or if the error was caused by a non-internally detected failure, 52 // this function returns zero. 53 uintptr_t 54 __gwp_asan_get_internal_crash_address(const gwp_asan::AllocatorState *State); 55 56 // Returns a pointer to the metadata for the allocation that's responsible for 57 // the crash. This metadata should not be dereferenced directly due to API 58 // compatibility issues, but should be instead passed to functions below for 59 // information retrieval. Returns nullptr if there is no metadata available for 60 // this crash. 61 const gwp_asan::AllocationMetadata * 62 __gwp_asan_get_metadata(const gwp_asan::AllocatorState *State, 63 const gwp_asan::AllocationMetadata *Metadata, 64 uintptr_t ErrorPtr); 65 66 // +---------------------------------------------------------------------------+ 67 // | Error Information Functions | 68 // +---------------------------------------------------------------------------+ 69 // Functions below return information about the type of error that was caught by 70 // GWP-ASan, or information about the allocation that caused the error. These 71 // functions generally take an `AllocationMeta` argument, which should be 72 // retrieved via. __gwp_asan_get_metadata. 73 74 // Returns the start of the allocation whose metadata is in `AllocationMeta`. 75 uintptr_t __gwp_asan_get_allocation_address( 76 const gwp_asan::AllocationMetadata *AllocationMeta); 77 78 // Returns the size of the allocation whose metadata is in `AllocationMeta` 79 size_t __gwp_asan_get_allocation_size( 80 const gwp_asan::AllocationMetadata *AllocationMeta); 81 82 // Returns the Thread ID that allocated the memory that caused the error at 83 // `ErrorPtr`. This function may not be called if __gwp_asan_has_metadata() 84 // returns false. 85 uint64_t __gwp_asan_get_allocation_thread_id( 86 const gwp_asan::AllocationMetadata *AllocationMeta); 87 88 // Retrieve the allocation trace for the allocation whose metadata is in 89 // `AllocationMeta`, and place it into the provided `Buffer` that has at least 90 // `BufferLen` elements. This function returns the number of frames that would 91 // have been written into `Buffer` if the space was available (i.e. however many 92 // frames were stored by GWP-ASan). A return value greater than `BufferLen` 93 // indicates that the trace was truncated when storing to `Buffer`. 94 size_t __gwp_asan_get_allocation_trace( 95 const gwp_asan::AllocationMetadata *AllocationMeta, uintptr_t *Buffer, 96 size_t BufferLen); 97 98 // Returns whether the allocation whose metadata is in `AllocationMeta` has been 99 // deallocated. This function may not be called if __gwp_asan_has_metadata() 100 // returns false. 101 bool __gwp_asan_is_deallocated( 102 const gwp_asan::AllocationMetadata *AllocationMeta); 103 104 // Returns the Thread ID that deallocated the memory whose metadata is in 105 // `AllocationMeta`. This function may not be called if 106 // __gwp_asan_is_deallocated() returns false. 107 uint64_t __gwp_asan_get_deallocation_thread_id( 108 const gwp_asan::AllocationMetadata *AllocationMeta); 109 110 // Retrieve the deallocation trace for the allocation whose metadata is in 111 // `AllocationMeta`, and place it into the provided `Buffer` that has at least 112 // `BufferLen` elements. This function returns the number of frames that would 113 // have been written into `Buffer` if the space was available (i.e. however many 114 // frames were stored by GWP-ASan). A return value greater than `BufferLen` 115 // indicates that the trace was truncated when storing to `Buffer`. This 116 // function may not be called if __gwp_asan_is_deallocated() returns false. 117 size_t __gwp_asan_get_deallocation_trace( 118 const gwp_asan::AllocationMetadata *AllocationMeta, uintptr_t *Buffer, 119 size_t BufferLen); 120 121 #ifdef __cplusplus 122 } // extern "C" 123 #endif 124 125 #endif // GWP_ASAN_INTERFACE_H_ 126