compiler-rt/lib/gwp_asan/optional/backtrace.h

   1 //===-- backtrace.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 #ifndef GWP_ASAN_OPTIONAL_BACKTRACE_H_
  10 #define GWP_ASAN_OPTIONAL_BACKTRACE_H_
  11
  12 #include "gwp_asan/optional/printf.h"
  13 #include "gwp_asan/options.h"
  14
  15 namespace gwp_asan {
  16 namespace backtrace {
  17 // ================================ Description ================================
  18 // This function shall take the backtrace provided in `TraceBuffer`, and print
  19 // it in a human-readable format using `Print`. Generally, this function shall
  20 // resolve raw pointers to section offsets and print them with the following
  21 // sanitizer-common format:
  22 //      "  #{frame_number} {pointer} in {function name} ({binary name}+{offset}"
  23 // e.g. "  #5 0x420459 in _start (/tmp/uaf+0x420459)"
  24 // This format allows the backtrace to be symbolized offline successfully using
  25 // llvm-symbolizer.
  26 // =================================== Notes ===================================
  27 // This function may directly or indirectly call malloc(), as the
  28 // GuardedPoolAllocator contains a reentrancy barrier to prevent infinite
  29 // recursion. Any allocation made inside this function will be served by the
  30 // supporting allocator, and will not have GWP-ASan protections.
  31 typedef void (*PrintBacktrace_t)(uintptr_t *TraceBuffer, size_t TraceLength,
  32                                  Printf_t Print);
  33
  34 // Returns a function pointer to a backtrace function that's suitable for
  35 // unwinding through a signal handler. This is important primarily for frame-
  36 // pointer based unwinders, DWARF or other unwinders can simply provide the
  37 // normal backtrace function as the implementation here. On POSIX, SignalContext
  38 // should be the `ucontext_t` from the signal handler.
  39 typedef size_t (*SegvBacktrace_t)(uintptr_t *TraceBuffer, size_t Size,
  40                                   void *SignalContext);
  41
  42 // Returns platform-specific provided implementations of Backtrace_t for use
  43 // inside the GWP-ASan core allocator.
  44 options::Backtrace_t getBacktraceFunction();
  45
  46 // Returns platform-specific provided implementations of PrintBacktrace_t and
  47 // SegvBacktrace_t for use in the optional SEGV handler.
  48 PrintBacktrace_t getPrintBacktraceFunction();
  49 SegvBacktrace_t getSegvBacktraceFunction();
  50 } // namespace backtrace
  51 } // namespace gwp_asan
  52
  53 #endif // GWP_ASAN_OPTIONAL_BACKTRACE_H_