diff --git a/compiler-rt/lib/gwp_asan/crash_handler_interface.h b/compiler-rt/lib/gwp_asan/crash_handler_interface.h new file mode 100644 --- /dev/null +++ b/compiler-rt/lib/gwp_asan/crash_handler_interface.h @@ -0,0 +1,128 @@ +//===-- crash_handler_interface.h -------------------------------*- C++ -*-===// +// +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +//===----------------------------------------------------------------------===// + +// This file contains interface functions that can be called by an in-process or +// out-of-process crash handler after the process has terminated. Functions in +// this interface are never thread safe. For an in-process crash handler, the +// handler should call GuardedPoolAllocator::disable() to stop any other threads +// from retrieving new GWP-ASan allocations, which may corrupt the metadata. +#ifndef GWP_ASAN_CRASH_HANDLER_INTERFACE_H_ +#define GWP_ASAN_CRASH_HANDLER_INTERFACE_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +// When a process crashes, there are three possible outcomes: +// 1. The crash is unrelated to GWP-ASan - in which case this function returns +// false. +// 2. The crash is internally detected within GWP-ASan itself (e.g. a +// double-free bug is caught in GuardedPoolAllocator::deallocate(), and +// GWP-ASan will terminate the process). In this case - this function +// returns true. +// 3. The crash is caused by a memory error at `AccessPtr` that's caught by the +// system, but GWP-ASan is responsible for the allocation. In this case - +// the function also returns true. +// This function takes an optional `AccessPtr` parameter. If the pointer that +// was attempted to be accessed is available, you should provide it here. In the +// case of some internally-detected errors, the crash may manifest as an abort +// or trap that doesn't have an associated pointer. In these cases, the pointer +// can be obtained by a call to __gwp_asan_get_internal_crash_address. +bool __gwp_asan_error_is_mine(gwp_asan::AllocatorState *State, + uintptr_t AccessPtr = 0u); + +// For internally-detected errors (double free, invalid free), this function +// returns the pointer that the error occurred at. If the error is unrelated to +// GWP-ASan, or if the error was caused by a non-internally detected failure, +// this function returns zero. +uintptr_t +__gwp_asan_get_internal_crash_address(gwp_asan::AllocatorState *State); + +// +---------------------------------------------------------------------------+ +// | Error Information Functions | +// +---------------------------------------------------------------------------+ +// Functions below return information about the type of error that was caught by +// GWP-ASan, or information about the allocation that caused the error. These +// functions generally take an `ErrorPtr` argument. This pointer can be either +// the address of the access that caused the fault, or the internally-detected +// crash address returned by __gwp_asan_get_internal_crash_address(). + +// Diagnose and return the type of error that occurred at `ErrorPtr`. If +// `ErrorPtr` is unrelated to GWP-ASan, or if the error type cannot be deduced, +// this function returns Error::UNKNOWN. +gwp_asan::AllocatorState::Error +__gwp_asan_diagnose_error(gwp_asan::AllocatorState *State, uintptr_t ErrorPtr); + +// This function returns whether metadata exists for the allocation that caused +// the error at `ErrorPtr`. If `ErrorPtr` is unrelated to GWP-ASan, this +// function returns false. This function also returns false if `ErrorPtr` is +// related to an allocation that doesn't have metadata, which can occur if the +// metadata about this allocation has been recycled. +bool __gwp_asan_has_metadata(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Returns the pointer to the start of the allocation that caused the error at +// `ErrorPtr`. This function may not be called if +// __gwp_asan_has_metadata(ErrorPtr) returns false. +uintptr_t __gwp_asan_get_allocation_address(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Returns the size of the allocation (in bytes) that caused the error at +// `ErrorPtr`. This function may not be called if +// __gwp_asan_has_metadata(ErrorPtr) returns false. +size_t __gwp_asan_get_allocation_size(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Returns the Thread ID that allocated the memory that caused the error at +// `ErrorPtr`. This function may not be called if +// __gwp_asan_has_metadata(ErrorPtr) returns false. +uint64_t __gwp_asan_get_allocation_thread_id(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Retrieve the allocation trace for the allocation that caused the error at +// `ErrorPtr`, and place it into the provided `Buffer` that has at least +// `BufferLen` elements. This function returns the number of frames that would +// have been written into `Buffer` if the space was available (i.e. however many +// frames were stored by GWP-ASan). A return value greater than `BufferLen` +// indicates that the trace was truncated when storing to `Buffer`. This +// function may not be called if __gwp_asan_has_metadata(ErrorPtr) returns +// false. +size_t __gwp_asan_get_allocation_trace(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr, uintptr_t *Buffer, + size_t BufferLen); + +// Returns whether the allocation that caused the error at `ErrorPtr` has been +// deallocated. This function may not be called if +// __gwp_asan_has_metadata(ErrorPtr) returns false. +bool __gwp_asan_is_deallocated(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Returns the Thread ID that deallocated the memory that caused the error at +// `ErrorPtr`. This function may not be called if +// __gwp_asan_has_metadata(ErrorPtr) or __gwp_asan_is_deallocated(ErrorPtr) +// returns false. +uint64_t __gwp_asan_get_dallocation_thread_id(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr); + +// Retrieve the deallocation trace for the allocation that caused the error at +// `ErrorPtr`, and place it into the provided `Buffer` that has at least +// `BufferLen` elements. This function returns the number of frames that would +// have been written into `Buffer` if the space was available (i.e. however many +// frames were stored by GWP-ASan). A return value greater than `BufferLen` +// indicates that the trace was truncated when storing to `Buffer`. This +// function may not be called if __gwp_asan_has_metadata(ErrorPtr) or +// __gwp_asan_is_deallocated(ErrorPtr) returns false. +size_t __gwp_asan_get_allocation_trace(gwp_asan::AllocatorState *State, + uintptr_t ErrorPtr, uintptr_t *Buffer, + size_t BufferLen); + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // GWP_ASAN_CRASH_HANDLER_INTERFACE_H_