[XRay][compiler-rt] Implement logging implementation registration

[dberris]

Summary

This change allows for registration of multiple logging implementations
through a central mechanism in XRay, mapping an implementation to a
"mode". Modes are strings that are used as keys to determine which
implementation to install through a single API. This mechanism allows
users to choose which implementation to install either from the
environment variable 'XRAY_OPTIONS' with the xray_mode= flag, or
programmatically using the __xray_select_mode(...) function.

Here, we introduce two API functions for the XRay logging:

__xray_log_register_mode(Mode, Impl): Associates an XRayLogImpl to a
string Mode. We can only have one implementation associated with a given
Mode.

__xray_log_select_mode(Mode): Finds the associated Impl for Mode and
installs it as if by calling __xray_set_log_impl(...).

Along with these changes, we also deprecate the xray_naive_log and
xray_fdr_log flags and encourage users to instead use the xray_mode
flag.

compiler-rt/trunk/include/xray/xray_log_interface.h

 /// This enum allows an implementation to signal log flushing operations via
 /// `__xray_log_flushLog()`, and the state of flushing the log.
 enum XRayLogFlushStatus {
   XRAY_LOG_NOT_FLUSHING = 0,
   XRAY_LOG_FLUSHING = 1,
   XRAY_LOG_FLUSHED = 2,
 };
 
+/// This enum indicates the installation state of a logging implementation, when
+/// associating a mode to a particular logging implementation through
+/// `__xray_log_register_impl(...)` or through `__xray_log_select_mode(...`.
+enum XRayLogRegisterStatus {
+  XRAY_REGISTRATION_OK = 0,
+  XRAY_DUPLICATE_MODE = 1,
+  XRAY_MODE_NOT_FOUND = 2,
+  XRAY_INCOMPLETE_IMPL = 3,
+};
+
 /// A valid XRay logging implementation MUST provide all of the function
 /// pointers in XRayLogImpl when being installed through `__xray_set_log_impl`.
 /// To be precise, ALL the functions pointers MUST NOT be nullptr.
 struct XRayLogImpl {
   /// The log initialization routine provided by the implementation, always
   /// provided with the following parameters:
   ///
   ///   - buffer size

 ///   - When the implementation is UNINITIALIZED.
 ///   - When the implementation is FINALIZED.
 ///   - When there is no current implementation installed.
 ///
 /// It is logging implementation defined what happens when this function is
 /// called while in any other states.
 void __xray_set_log_impl(XRayLogImpl Impl);
 
+/// This function registers a logging implementation against a "mode"
+/// identifier. This allows multiple modes to be registered, and chosen at
+/// runtime using the same mode identifier through
+/// `__xray_log_select_mode(...)`.
+///
+/// We treat the Mode identifier as a null-terminated byte string, as the
+/// identifier used when retrieving the log impl.
+///
+/// Returns:
+///   - XRAY_REGISTRATION_OK on success.
+///   - XRAY_DUPLICATE_MODE when an implementation is already associated with
+///     the provided Mode; does not update the already-registered
+///     implementation.
+XRayLogRegisterStatus __xray_log_register_mode(const char *Mode,
+                                               XRayLogImpl Impl);
+
+/// This function selects the implementation associated with Mode that has been
+/// registered through __xray_log_register_mode(...) and installs that
+/// implementation (as if through calling __xray_set_log_impl(...)). The same
+/// caveats apply to __xray_log_select_mode(...) as with
+/// __xray_log_set_log_impl(...).
+///
+/// Returns:
+///   - XRAY_REGISTRATION_OK on success.
+///   - XRAY_MODE_NOT_FOUND if there is no implementation associated with Mode;
+///     does not update the currently installed implementation.
+XRayLogRegisterStatus __xray_log_select_mode(const char *Mode);
+
 /// This function removes the currently installed implementation. It will also
 /// uninstall any handlers that have been previously installed. It does NOT
 /// unpatch the instrumentation sleds.
 ///
 /// NOTE: This function does NOT attempt to finalize the currently installed
 /// implementation. Use with caution.
 ///
 /// It is guaranteed safe to call this function in the following states:

compiler-rt/trunk/lib/xray/xray_fdr_logging.cc

__sanitizer::atomic_store(&LoggingStatus,
                             XRayLogInitStatus::XRAY_LOG_INITIALIZED,
                             __sanitizer::memory_order_release);
 
   if (__sanitizer::Verbosity())
     Report("XRay FDR init successful.\n");
   return XRayLogInitStatus::XRAY_LOG_INITIALIZED;
 }
 
-} // namespace __xray
-
-static auto UNUSED Unused = [] {
+bool fdrLogDynamicInitializer() XRAY_NEVER_INSTRUMENT {
   using namespace __xray;
-  if (flags()->xray_fdr_log) {
-    XRayLogImpl Impl{
-        fdrLoggingInit, fdrLoggingFinalize, fdrLoggingHandleArg0,
-        fdrLoggingFlush,
-    };
+      fdrLoggingInit,
+      fdrLoggingFinalize,
+      fdrLoggingHandleArg0,
+  auto RegistrationResult = __xray_log_register_mode("xray-fdr", Impl);
+  if (RegistrationResult != XRayLogRegisterStatus::XRAY_REGISTRATION_OK &&
+      __sanitizer::Verbosity())
+    Report("Cannot register XRay FDR mode to 'xray-fdr'; error = %d\n",
+           RegistrationResult);
+  if (flags()->xray_fdr_log ||
+      !__sanitizer::internal_strcmp(flags()->xray_mode, "xray-fdr"))
     __xray_set_log_impl(Impl);
-  }
   return true;
-}();
+}
+
+} // namespace __xray
+
+static auto UNUSED Unused = __xray::fdrLogDynamicInitializer();

compiler-rt/trunk/lib/xray/xray_flags.inc

 #ifndef XRAY_FLAG
 #error "Define XRAY_FLAG prior to including this file!"
 #endif
 
 XRAY_FLAG(bool, patch_premain, false,
           "Whether to patch instrumentation points before main.")
 XRAY_FLAG(const char *, xray_logfile_base, "xray-log.",
           "Filename base for the xray logfile.")
+XRAY_FLAG(const char *, xray_mode, "", "Mode to install by default.")
+
 
 // Basic (Naive) Mode logging options.
 XRAY_FLAG(bool, xray_naive_log, false,
-          "Whether to install the naive log implementation.")
+          "DEPRECATED: Use xray_mode=xray-basic instead.")
 XRAY_FLAG(int, xray_naive_log_func_duration_threshold_us, 5,
           "Naive logging will try to skip functions that execute for fewer "
           "microseconds than this threshold.")
 XRAY_FLAG(int, xray_naive_log_max_stack_depth, 64,
           "Naive logging will keep track of at most this deep a call stack, "
           "any more and the recordings will be droppped.")
 XRAY_FLAG(int, xray_naive_log_thread_buffer_size, 1024,
           "The number of entries to keep on a per-thread buffer.")
 
 // FDR (Flight Data Recorder) Mode logging options.
 XRAY_FLAG(bool, xray_fdr_log, false,
-          "Whether to install the flight data recorder logging implementation.")
+          "DEPRECATED: Use xray_mode=xray-fdr instead.")
 XRAY_FLAG(int, xray_fdr_log_func_duration_threshold_us, 5,
           "FDR logging will try to skip functions that execute for fewer "
           "microseconds than this threshold.")
 XRAY_FLAG(int, xray_fdr_log_grace_period_us, 0,
           "DEPRECATED: use xray_fdr_log_grace_period_ms instead.")
 XRAY_FLAG(int, xray_fdr_log_grace_period_ms, 100,
           "FDR logging will wait this much time in microseconds before "
           "actually flushing the log; this gives a chance for threads to "
           "notice that the log has been finalized and clean up.")

compiler-rt/trunk/lib/xray/xray_inmemory_log.cc

XRayLogFlushStatus basicLoggingFlush() XRAY_NEVER_INSTRUMENT {
   return XRayLogFlushStatus::XRAY_LOG_FLUSHED;
 }
 
 // This is a handler that, effectively, does nothing.
 void basicLoggingHandleArg0Empty(int32_t, XRayEntryType) XRAY_NEVER_INSTRUMENT {
 }
 
 bool basicLogDynamicInitializer() XRAY_NEVER_INSTRUMENT {
-  if (flags()->xray_naive_log) {
-    XRayLogImpl Impl{
-        basicLoggingInit,
-        basicLoggingFinalize,
-        basicLoggingHandleArg0Empty,
-        basicLoggingFlush,
-    };
+  auto RegistrationResult = __xray_log_register_mode("xray-basic", Impl);
+  if (RegistrationResult != XRayLogRegisterStatus::XRAY_REGISTRATION_OK &&
+      __sanitizer::Verbosity())
+    Report("Cannot register XRay Basic Mode to 'xray-basic'; error = %d\n",
+           RegistrationResult);
+  if (flags()->xray_naive_log ||
+      !__sanitizer::internal_strcmp(flags()->xray_mode, "xray-basic")) {
     __xray_set_log_impl(Impl);
     BasicLoggingOptions Options;
     Options.DurationFilterMicros =
         flags()->xray_naive_log_func_duration_threshold_us;
     Options.MaxStackDepth = flags()->xray_naive_log_max_stack_depth;
     Options.ThreadBufferSize = flags()->xray_naive_log_thread_buffer_size;
     __xray_log_init(flags()->xray_naive_log_thread_buffer_size, 0, &Options,
                     sizeof(BasicLoggingOptions));
   }
   return true;
 }
 
 } // namespace __xray
 
 static auto UNUSED Unused = __xray::basicLogDynamicInitializer();

compiler-rt/trunk/lib/xray/xray_log_interface.cc

 //===-- xray_log_interface.cc ---------------------------------------------===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 //
 // This file is a part of XRay, a function call tracing system.
 //
 //===----------------------------------------------------------------------===//
 #include "xray/xray_log_interface.h"
 
+#include "sanitizer_common/sanitizer_allocator_internal.h"
 #include "sanitizer_common/sanitizer_atomic.h"
 #include "sanitizer_common/sanitizer_mutex.h"
 #include "xray/xray_interface.h"
 #include "xray_defs.h"
 
 __sanitizer::SpinMutex XRayImplMutex;
+XRayLogImpl CurrentXRayImpl{nullptr, nullptr, nullptr, nullptr};
 XRayLogImpl *GlobalXRayImpl = nullptr;
 
+// We use a linked list of Mode to XRayLogImpl mappings. This is a linked list
+// when it should be a map because we're avoiding having to depend on C++
+// standard library data structures at this level of the implementation.
+struct ModeImpl {
+  ModeImpl *Next;
+  const char *Mode;
+  XRayLogImpl Impl;
+};
+
+ModeImpl SentinelModeImpl{
+    nullptr, nullptr, {nullptr, nullptr, nullptr, nullptr}};
+ModeImpl *ModeImpls = &SentinelModeImpl;
+
+XRayLogRegisterStatus
+__xray_log_register_mode(const char *Mode,
+                         XRayLogImpl Impl) XRAY_NEVER_INSTRUMENT {
+  if (Impl.flush_log == nullptr || Impl.handle_arg0 == nullptr ||
+      Impl.log_finalize == nullptr || Impl.log_init == nullptr)
+    return XRayLogRegisterStatus::XRAY_INCOMPLETE_IMPL;
+
+  __sanitizer::SpinMutexLock Guard(&XRayImplMutex);
+  // First, look for whether the mode already has a registered implementation.
+  for (ModeImpl *it = ModeImpls; it != &SentinelModeImpl; it = it->Next) {
+    if (!__sanitizer::internal_strcmp(Mode, it->Mode))
+      return XRayLogRegisterStatus::XRAY_DUPLICATE_MODE;
+  }
+  auto *NewModeImpl =
+      static_cast<ModeImpl *>(__sanitizer::InternalAlloc(sizeof(ModeImpl)));
+  NewModeImpl->Next = ModeImpls;
+  NewModeImpl->Mode = __sanitizer::internal_strdup(Mode);
+  NewModeImpl->Impl = Impl;
+  ModeImpls = NewModeImpl;
+  return XRayLogRegisterStatus::XRAY_REGISTRATION_OK;
+}
+
+XRayLogRegisterStatus
+__xray_log_select_mode(const char *Mode) XRAY_NEVER_INSTRUMENT {
+  __sanitizer::SpinMutexLock Guard(&XRayImplMutex);
+  for (ModeImpl *it = ModeImpls; it != &SentinelModeImpl; it = it->Next) {
+    if (!__sanitizer::internal_strcmp(Mode, it->Mode)) {
+      CurrentXRayImpl = it->Impl;
+      GlobalXRayImpl = &CurrentXRayImpl;
+      __xray_set_handler(it->Impl.handle_arg0);
+      return XRayLogRegisterStatus::XRAY_REGISTRATION_OK;
+    }
+  }
+  return XRayLogRegisterStatus::XRAY_MODE_NOT_FOUND;
+}
+
 void __xray_set_log_impl(XRayLogImpl Impl) XRAY_NEVER_INSTRUMENT {
   if (Impl.log_init == nullptr || Impl.log_finalize == nullptr ||
       Impl.handle_arg0 == nullptr || Impl.flush_log == nullptr) {
     __sanitizer::SpinMutexLock Guard(&XRayImplMutex);
-    delete GlobalXRayImpl;
     GlobalXRayImpl = nullptr;
     __xray_remove_handler();
     __xray_remove_handler_arg1();
     return;
   }
 
   __sanitizer::SpinMutexLock Guard(&XRayImplMutex);
-  GlobalXRayImpl = new XRayLogImpl();
-  *GlobalXRayImpl = Impl;
+  CurrentXRayImpl = Impl;
+  GlobalXRayImpl = &CurrentXRayImpl;
   __xray_set_handler(Impl.handle_arg0);
 }
 
 void __xray_remove_log_impl() XRAY_NEVER_INSTRUMENT {
   __sanitizer::SpinMutexLock Guard(&XRayImplMutex);
-  delete GlobalXRayImpl;
   GlobalXRayImpl = nullptr;
   __xray_remove_handler();
   __xray_remove_handler_arg1();
 }
 
 XRayLogInitStatus __xray_log_init(size_t BufferSize, size_t MaxBuffers,
                                   void *Args,
                                   size_t ArgsSize) XRAY_NEVER_INSTRUMENT {

compiler-rt/trunk/test/xray/TestCases/Linux/logging-modes.cc

+// Check that we can install an implementation associated with a mode.
+//
+// RUN: %clangxx_xray -std=c++11 %s -o %t
+// RUN: %run %t | FileCheck %s
+//
+// UNSUPPORTED: target-is-mips64,target-is-mips64el
+
+#include "xray/xray_interface.h"
+#include "xray/xray_log_interface.h"
+#include <cassert>
+#include <cstdio>
+
+[[clang::xray_never_instrument]] void printing_handler(int32_t fid,
+                                                       XRayEntryType) {
+  thread_local volatile bool printing = false;
+  if (printing)
+    return;
+  printing = true;
+  std::printf("printing %d\n", fid);
+  printing = false;
+}
+
+[[clang::xray_never_instrument]] XRayLogInitStatus
+printing_init(size_t, size_t, void *, size_t) {
+  return XRayLogInitStatus::XRAY_LOG_INITIALIZED;
+}
+
+[[clang::xray_never_instrument]] XRayLogInitStatus printing_finalize() {
+  return XRayLogInitStatus::XRAY_LOG_FINALIZED;
+}
+
+[[clang::xray_never_instrument]] XRayLogFlushStatus printing_flush_log() {
+  return XRayLogFlushStatus::XRAY_LOG_FLUSHED;
+}
+
+[[clang::xray_always_instrument]] void callme() { std::printf("called me!\n"); }
+
+static bool unused = [] {
+  assert(__xray_log_register_mode("custom",
+                                  {printing_init, printing_finalize,
+                                   printing_handler, printing_flush_log}) ==
+         XRayLogRegisterStatus::XRAY_REGISTRATION_OK);
+  return true;
+}();
+
+int main(int argc, char **argv) {
+  assert(__xray_log_select_mode("custom") ==
+         XRayLogRegisterStatus::XRAY_REGISTRATION_OK);
+  assert(__xray_patch() == XRayPatchingStatus::SUCCESS);
+  assert(__xray_log_init(0, 0, nullptr, 0) ==
+         XRayLogInitStatus::XRAY_LOG_INITIALIZED);
+  // CHECK: printing {{.*}}
+  callme(); // CHECK: called me!
+  // CHECK: printing {{.*}}
+  assert(__xray_log_finalize() == XRayLogInitStatus::XRAY_LOG_FINALIZED);
+  assert(__xray_log_flushLog() == XRayLogFlushStatus::XRAY_LOG_FLUSHED);
+  assert(__xray_log_select_mode("not-found") ==
+         XRayLogRegisterStatus::XRAY_MODE_NOT_FOUND);
+}