xref: /freebsd/contrib/llvm-project/compiler-rt/lib/gwp_asan/optional/segv_handler.h (revision dd41de95a84d979615a2ef11df6850622bf6184e)
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 #ifndef GWP_ASAN_OPTIONAL_CRASH_HANDLER_H_
10 #define GWP_ASAN_OPTIONAL_CRASH_HANDLER_H_
11 
12 #include "gwp_asan/guarded_pool_allocator.h"
13 #include "gwp_asan/options.h"
14 
15 namespace gwp_asan {
16 namespace crash_handler {
17 // ================================ Requirements ===============================
18 // This function must be provided by the supporting allocator only when this
19 // provided crash handler is used to dump the generic report.
20 // sanitizer::Printf() function can be simply used here.
21 // ================================ Description ================================
22 // This function shall produce output according to a strict subset of the C
23 // standard library's printf() family. This function must support printing the
24 // following formats:
25 //   1. integers: "%([0-9]*)?(z|ll)?{d,u,x,X}"
26 //   2. pointers: "%p"
27 //   3. strings:  "%[-]([0-9]*)?(\\.\\*)?s"
28 //   4. chars:    "%c"
29 // This function must be implemented in a signal-safe manner, and thus must not
30 // malloc().
31 // =================================== Notes ===================================
32 // This function has a slightly different signature than the C standard
33 // library's printf(). Notably, it returns 'void' rather than 'int'.
34 typedef void (*Printf_t)(const char *Format, ...);
35 
36 // ================================ Requirements ===============================
37 // This function is required for the supporting allocator, but one of the three
38 // provided implementations may be used (RTGwpAsanBacktraceLibc,
39 // RTGwpAsanBacktraceSanitizerCommon, or BasicPrintBacktraceFunction).
40 // ================================ Description ================================
41 // This function shall take the backtrace provided in `TraceBuffer`, and print
42 // it in a human-readable format using `Print`. Generally, this function shall
43 // resolve raw pointers to section offsets and print them with the following
44 // sanitizer-common format:
45 //      "  #{frame_number} {pointer} in {function name} ({binary name}+{offset}"
46 // e.g. "  #5 0x420459 in _start (/tmp/uaf+0x420459)"
47 // This format allows the backtrace to be symbolized offline successfully using
48 // llvm-symbolizer.
49 // =================================== Notes ===================================
50 // This function may directly or indirectly call malloc(), as the
51 // GuardedPoolAllocator contains a reentrancy barrier to prevent infinite
52 // recursion. Any allocation made inside this function will be served by the
53 // supporting allocator, and will not have GWP-ASan protections.
54 typedef void (*PrintBacktrace_t)(uintptr_t *TraceBuffer, size_t TraceLength,
55                                  Printf_t Print);
56 
57 // Returns a function pointer to a basic PrintBacktrace implementation. This
58 // implementation simply prints the stack trace in a human readable fashion
59 // without any symbolization.
60 PrintBacktrace_t getBasicPrintBacktraceFunction();
61 
62 // Install the SIGSEGV crash handler for printing use-after-free and heap-
63 // buffer-{under|over}flow exceptions if the user asked for it. This is platform
64 // specific as even though POSIX and Windows both support registering handlers
65 // through signal(), we have to use platform-specific signal handlers to obtain
66 // the address that caused the SIGSEGV exception. GPA->init() must be called
67 // before this function.
68 void installSignalHandlers(gwp_asan::GuardedPoolAllocator *GPA, Printf_t Printf,
69                            PrintBacktrace_t PrintBacktrace,
70                            options::Backtrace_t Backtrace);
71 
72 void uninstallSignalHandlers();
73 
74 void dumpReport(uintptr_t ErrorPtr, const gwp_asan::AllocatorState *State,
75                 const gwp_asan::AllocationMetadata *Metadata,
76                 options::Backtrace_t Backtrace, Printf_t Printf,
77                 PrintBacktrace_t PrintBacktrace);
78 } // namespace crash_handler
79 } // namespace gwp_asan
80 
81 #endif // GWP_ASAN_OPTIONAL_CRASH_HANDLER_H_
82