126 lines
6.2 KiB
C++
126 lines
6.2 KiB
C++
//===-- crash_handler.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_INTERFACE_H_
|
|
#define GWP_ASAN_INTERFACE_H_
|
|
|
|
#include "gwp_asan/common.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 may or may not 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(const gwp_asan::AllocatorState *State,
|
|
uintptr_t ErrorPtr = 0u);
|
|
|
|
// 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::Error
|
|
__gwp_asan_diagnose_error(const gwp_asan::AllocatorState *State,
|
|
const gwp_asan::AllocationMetadata *Metadata,
|
|
uintptr_t ErrorPtr);
|
|
|
|
// 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(const gwp_asan::AllocatorState *State);
|
|
|
|
// Returns a pointer to the metadata for the allocation that's responsible for
|
|
// the crash. This metadata should not be dereferenced directly due to API
|
|
// compatibility issues, but should be instead passed to functions below for
|
|
// information retrieval. Returns nullptr if there is no metadata available for
|
|
// this crash.
|
|
const gwp_asan::AllocationMetadata *
|
|
__gwp_asan_get_metadata(const gwp_asan::AllocatorState *State,
|
|
const gwp_asan::AllocationMetadata *Metadata,
|
|
uintptr_t ErrorPtr);
|
|
|
|
// +---------------------------------------------------------------------------+
|
|
// | 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 `AllocationMeta` argument, which should be
|
|
// retrieved via. __gwp_asan_get_metadata.
|
|
|
|
// Returns the start of the allocation whose metadata is in `AllocationMeta`.
|
|
uintptr_t __gwp_asan_get_allocation_address(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta);
|
|
|
|
// Returns the size of the allocation whose metadata is in `AllocationMeta`
|
|
size_t __gwp_asan_get_allocation_size(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta);
|
|
|
|
// 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()
|
|
// returns false.
|
|
uint64_t __gwp_asan_get_allocation_thread_id(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta);
|
|
|
|
// Retrieve the allocation trace for the allocation whose metadata is in
|
|
// `AllocationMeta`, 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`.
|
|
size_t __gwp_asan_get_allocation_trace(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta, uintptr_t *Buffer,
|
|
size_t BufferLen);
|
|
|
|
// Returns whether the allocation whose metadata is in `AllocationMeta` has been
|
|
// deallocated. This function may not be called if __gwp_asan_has_metadata()
|
|
// returns false.
|
|
bool __gwp_asan_is_deallocated(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta);
|
|
|
|
// Returns the Thread ID that deallocated the memory whose metadata is in
|
|
// `AllocationMeta`. This function may not be called if
|
|
// __gwp_asan_is_deallocated() returns false.
|
|
uint64_t __gwp_asan_get_deallocation_thread_id(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta);
|
|
|
|
// Retrieve the deallocation trace for the allocation whose metadata is in
|
|
// `AllocationMeta`, 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_is_deallocated() returns false.
|
|
size_t __gwp_asan_get_deallocation_trace(
|
|
const gwp_asan::AllocationMetadata *AllocationMeta, uintptr_t *Buffer,
|
|
size_t BufferLen);
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif // GWP_ASAN_INTERFACE_H_
|