1//===-- options.inc ---------------------------------------------*- 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_OPTION
10#error "Define GWP_ASAN_OPTION prior to including this file!"
11#endif
12
13#ifndef GWP_ASAN_DEFAULT_ENABLED
14#define GWP_ASAN_DEFAULT_ENABLED true
15#endif
16
17#ifndef GWP_ASAN_STRINGIFY
18#define GWP_ASAN_STRINGIFY(S) GWP_ASAN_STRINGIFY_(S)
19#define GWP_ASAN_STRINGIFY_(S) #S
20#endif
21
22GWP_ASAN_OPTION(bool, Enabled, GWP_ASAN_DEFAULT_ENABLED,
23                "Is GWP-ASan enabled? Defaults to " GWP_ASAN_STRINGIFY(
24                    GWP_ASAN_DEFAULT_ENABLED) ".")
25
26GWP_ASAN_OPTION(int, MaxSimultaneousAllocations, 16,
27                "Number of simultaneously-guarded allocations available in the "
28                "pool. Defaults to 16.")
29
30GWP_ASAN_OPTION(int, SampleRate, 5000,
31                "The probability (1 / SampleRate) that an allocation is "
32                "selected for GWP-ASan sampling. Default is 5000. Sample rates "
33                "up to (2^30 - 1) are supported.")
34
35// Developer note - This option is not actually processed by GWP-ASan itself. It
36// is included here so that a user can specify whether they want signal handlers
37// or not. The supporting allocator should inspect this value to see whether
38// signal handlers need to be installed, and then use
39// crash_handler::installSignalHandlers() in order to install the handlers. Note
40// that in order to support signal handlers, you will need to link against the
41// optional crash_handler component.
42GWP_ASAN_OPTION(
43    bool, InstallSignalHandlers, true,
44    "Install GWP-ASan signal handlers for SIGSEGV during dynamic loading. This "
45    "allows better error reports by providing stack traces for allocation and "
46    "deallocation when reporting a memory error. GWP-ASan's signal handler "
47    "will forward the signal to any previously-installed handler, and user "
48    "programs that install further signal handlers should make sure they do "
49    "the same. Note, if the previously installed SIGSEGV handler is SIG_IGN, "
50    "we terminate the process after dumping the error report.")
51
52GWP_ASAN_OPTION(
53    bool, Recoverable, false,
54    "Install GWP-ASan's signal handler in recoverable mode. This means that "
55    "upon GWP-ASan detecting an error, it'll print the error report, but *not* "
56    "crash. Only one crash per sampled allocation will ever be recorded, and "
57    "if a sampled allocation does actually cause a crash, it'll permanently "
58    "occupy a slot in the pool. The recoverable mode also means that "
59    "previously-installed signal handlers will only be triggered for "
60    "non-GWP-ASan errors, as all GWP-ASan errors won't be forwarded.")
61
62GWP_ASAN_OPTION(bool, InstallForkHandlers, true,
63                "Install GWP-ASan atfork handlers to acquire internal locks "
64                "before fork and release them after.")
65
66GWP_ASAN_OPTION(bool, help, false, "Print a summary of the available options.")
67
68// =============================================================================
69// ==== WARNING
70// =============================================================================
71// If you are adding flags to GWP-ASan, please note that GWP-ASan flag strings
72// may be parsed by trusted system components (on Android, GWP-ASan flag strings
73// are parsed by libc during the dynamic loader). This means that GWP-ASan
74// should never feature flags like log paths on disk, because this can lead to
75// arbitrary file write and thus privilege escalation. For an example, see the
76// setuid ASan log_path exploits: https://www.exploit-db.com/exploits/46241.
77//
78// Please place all new flags above this warning, so that the warning always
79// stays at the bottom.
80