[XRay] Add __xray_default_options to specify build-time defined options

[mshockwave]

Similar to __asan_default_options, users can specify default options upon building the instrumented binaries by providing their own definition of __xray_default_options which returns the option strings.

This is useful in cases where setting the XRAY_OPTIONS environment variable might be difficult. Plus, it's a convenient way to populate XRay options when you always want the instrumentation to be enabled.

[llvmbot]

@llvm/pr-subscribers-xray

Author: Min-Yih Hsu (mshockwave)

Changes

Similar to __asan_default_options, users can specify default options upon building the instrumented binaries by providing their own definition of __xray_default_options which returns the option strings.

This is useful in cases where setting the XRAY_OPTIONS environment variable might be difficult. Plus, it's a convenient way to populate XRay options when you always want the instrumentation to be enabled.

---

Full diff: https://github.com/llvm/llvm-project/pull/117921.diff

5 Files Affected:

• (modified) compiler-rt/lib/xray/weak_symbols.txt (+1)
• (modified) compiler-rt/lib/xray/xray_flags.cpp (+8)
• (modified) compiler-rt/lib/xray/xray_flags.h (+7)
• (added) compiler-rt/test/xray/TestCases/Posix/default-options.cpp (+16)
• (modified) llvm/docs/XRay.rst (+27-1)

diff --git a/compiler-rt/lib/xray/weak_symbols.txt b/compiler-rt/lib/xray/weak_symbols.txt
index 963fff2d697eef..379749796af257 100644
--- a/compiler-rt/lib/xray/weak_symbols.txt
+++ b/compiler-rt/lib/xray/weak_symbols.txt
@@ -2,3 +2,4 @@ ___start_xray_fn_idx
 ___start_xray_instr_map
 ___stop_xray_fn_idx
 ___stop_xray_instr_map
+___xray_default_options
diff --git a/compiler-rt/lib/xray/xray_flags.cpp b/compiler-rt/lib/xray/xray_flags.cpp
index e4c6906dc44345..9d3ee3ea855288 100644
--- a/compiler-rt/lib/xray/xray_flags.cpp
+++ b/compiler-rt/lib/xray/xray_flags.cpp
@@ -67,6 +67,10 @@ void initializeFlags() XRAY_NEVER_INSTRUMENT {
   const char *XRayCompileFlags = useCompilerDefinedFlags();
   XRayParser.ParseString(XRayCompileFlags);
 
+  // Use options provided at build time of the instrumented program.
+  const char *XRayDefaultOptions = __xray_default_options();
+  XRayParser.ParseString(XRayDefaultOptions);
+
   // Override from environment variables.
   XRayParser.ParseStringFromEnv("XRAY_OPTIONS");
 
@@ -82,3 +86,7 @@ void initializeFlags() XRAY_NEVER_INSTRUMENT {
 }
 
 } // namespace __xray
+
+SANITIZER_INTERFACE_WEAK_DEF(const char *, __xray_default_options, void) {
+  return "";
+}
diff --git a/compiler-rt/lib/xray/xray_flags.h b/compiler-rt/lib/xray/xray_flags.h
index cce6fe9d62f9f6..e29d62e0a3b919 100644
--- a/compiler-rt/lib/xray/xray_flags.h
+++ b/compiler-rt/lib/xray/xray_flags.h
@@ -17,6 +17,13 @@
 #include "sanitizer_common/sanitizer_flag_parser.h"
 #include "sanitizer_common/sanitizer_internal_defs.h"
 
+extern "C" {
+// Users can specify their default options upon building the instrumented
+// binaries by provide a definition of this function.
+SANITIZER_INTERFACE_ATTRIBUTE
+const char *__xray_default_options();
+}
+
 namespace __xray {
 
 struct Flags {
diff --git a/compiler-rt/test/xray/TestCases/Posix/default-options.cpp b/compiler-rt/test/xray/TestCases/Posix/default-options.cpp
new file mode 100644
index 00000000000000..e00ff3ba0a5cbe
--- /dev/null
+++ b/compiler-rt/test/xray/TestCases/Posix/default-options.cpp
@@ -0,0 +1,16 @@
+// RUN: rm -fr %t && mkdir %t && cd %t
+// RUN: %clang_xray %s -o a.out
+// RUN: %run %t/a.out 2>&1 | FileCheck %s
+
+// REQUIRES: built-in-llvm-tree
+
+extern "C" __attribute__((xray_never_instrument)) const char *
+__xray_default_options() {
+  return "patch_premain=true:verbosity=1:xray_mode=xray-basic";
+}
+
+__attribute__((xray_always_instrument)) void always() {}
+
+int main() { always(); }
+
+// CHECK: =={{[0-9].*}}==XRay: Log file in '{{.*}}'
diff --git a/llvm/docs/XRay.rst b/llvm/docs/XRay.rst
index acfb83c5374eda..ceb5b88ab9108f 100644
--- a/llvm/docs/XRay.rst
+++ b/llvm/docs/XRay.rst
@@ -157,7 +157,8 @@ Also by default the filename of the XRay trace is ``xray-log.XXXXXX`` where the
 ``XXXXXX`` part is randomly generated.
 
 These options can be controlled through the ``XRAY_OPTIONS`` environment
-variable, where we list down the options and their defaults below.
+variable during program run-time, where we list down the options and their
+defaults below.
 
 +-------------------+-----------------+---------------+------------------------+
 | Option            | Type            | Default       | Description            |
@@ -178,6 +179,31 @@ variable, where we list down the options and their defaults below.
 +-------------------+-----------------+---------------+------------------------+
 
 
+In addition to environment variable, you can also provide your own definition of
+``const char *__xray_default_options(void)`` function, which returns the option
+strings. This method effectively provides default options during program build
+time. For example, you can create an additional source file (e.g. ``xray-opt.c``
+) with the following ``__xray_default_options`` definition:
+
+.. code-block:: c
+
+  __attribute__((xray_never_instrument))
+  const char *__xray_default_options() {
+    return "patch_premain=true,xray_mode=xray-basic";
+  }
+
+And link it with the program you want to instrument:
+
+::
+
+  clang -fxray-instrument prog.c xray-opt.c ...
+
+The instrumented binary will use 'patch_premain=true,xray_mode=xray-basic' by
+default even without setting ``XRAY_OPTIONS``.
+
+Note that you still can override options designated by ``__xray_default_options``
+using ``XRAY_OPTIONS`` during run-time.
+
 If you choose to not use the default logging implementation that comes with the
 XRay runtime and/or control when/how the XRay instrumentation runs, you may use
 the XRay APIs directly for doing so. To do this, you'll need to include the

[cjappl]

LGTM - much cleaner than the first go, thanks for revising