[GWP-ASan] Add in-proc/out-of-proc crash handler interface.

[hctim]

Summary

This patch describes the shared crash handler interface into GWP-ASan that can
be used by both in-process and out-of-process crash handlers.

This interface yet is to be implemented. This patch is primarily to discuss the
requirements of the interface, and how to expose the metadata in an stable,
robust API. Please review and leave your comments.

Some careful design decisions have been made, and I'll try and identify some
key aspects:

1. Out-of-process crash handlers need to be able to retrieve the requisite information from the crashed process. This API introduces a new (opaque at this time) struct called gwp_asan::AllocatorState. This is designed to be a flat structure (i.e. no internal pointers) that contains all metadata required for these API calls. This is similar to the design of Chromium's GWP-ASan, and will allow us to trivially memcpy() out all required information from the crashed process in order to make these API calls.
2. This API must be stable and backwards compatible. Implementing this into Android must allow libdebuggerd and the Firebase Crashlytics SDK to talk with libc (where GWP-ASan will live) in a stable way. libdebuggerd poses less risk, as the platform version will generally be in sync with libc. Applications built with Crashlytics may be built on vastly different major version of Android.

[merge_guards_bot]

Unit tests: pass. 60863 tests passed, 0 failed and 726 were skipped.

clang-format: pass.

Build artifacts: console-log.txt, CMakeCache.txt, test-results.xml, diff.json

[hctim]

Merged in D73557.

compiler-rt/lib/gwp_asan/crash_handler_interface.h

+//===-- 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_