[XRay][compiler-rt+docs] Introduce __xray_log_init_mode(...).

Summary:
This addresses http://llvm.org/PR36790.

The change Deprecates a number of functions and types in
`include/xray/xray_log_interface.h` to recommend using string-based
configuration of XRay through the __xray_log_init_mode(...) function. In
particular, this deprecates the following:

- `__xray_set_log_impl(...)` -- users should instead use the
`__xray_log_register_mode(...)` and `__xray_log_select_mode(...)` APIs.

- `__xray_log_init(...)` -- users should instead use the
`__xray_log_init_mode(...)` function, which also requires using the
`__xray_log_register_mode(...)` and `__xray_log_select_mode(...)`
functionality.

- `__xray::FDRLoggingOptions` -- in following patches, we'll be
migrating the FDR logging implementations (and tests) to use the
string-based configuration. In later stages we'll remove the
`__xray::FDRLoggingOptions` type, and ask users to migrate to using the
string-based configuration mechanism instead.

- `__xray::BasicLoggingOptions` -- same as `__xray::FDRLoggingOptions`,
we'll be removing this type later and instead rely exclusively on the
string-based configuration API.

We also update the documentation to reflect the new advice and remove
some of the deprecated notes.

Reviewers: eizan, kpw, echristo, pelikan

Reviewed By: kpw

Subscribers: llvm-commits

Differential Revision: https://reviews.llvm.org/D46173

git-svn-id: https://llvm.org/svn/llvm-project/compiler-rt/trunk@331503 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 21 insertions, 8 deletions

diff --git a/test/xray/TestCases/Posix/logging-modes.cc b/test/xray/TestCases/Posix/logging-modes.cc
index b846cf675..26dac3554 100644
--- a/test/xray/TestCases/Posix/logging-modes.cc
+++ b/test/xray/TestCases/Posix/logging-modes.cc
@@ -1,6 +1,7 @@
 // Check that we can install an implementation associated with a mode.
 //
-// RUN: %clangxx_xray -std=c++11 %s -o %t
+// RUN: rm xray-log.logging-modes* || true
+// RUN: %clangxx_xray -std=c++11 %s -o %t -fxray-modes=none
 // RUN: %run %t | FileCheck %s
 //
 // UNSUPPORTED: target-is-mips64,target-is-mips64el
@@ -31,8 +32,18 @@
   assert(false && "Invalid buffer provided.");
 }
 
+static constexpr char Options[] = "additional_flags";
+
 [[clang::xray_never_instrument]] XRayLogInitStatus
-printing_init(size_t, size_t, void *, size_t) {
+printing_init(size_t BufferSize, size_t MaxBuffers, void *Config,
+              size_t ArgsSize) {
+  // We require that the printing init is called through the
+  // __xray_log_init_mode(...) implementation, and that the promised contract is
+  // enforced.
+  assert(BufferSize == 0);
+  assert(MaxBuffers == 0);
+  assert(Config != nullptr);
+  assert(ArgsSize == 0 || ArgsSize == sizeof(Options));
   __xray_log_set_buffer_iterator(next_buffer);
   return XRayLogInitStatus::XRAY_LOG_INITIALIZED;
 }
@@ -52,23 +63,25 @@ static auto buffer_counter = 0;
 
 void process_buffer(const char *, XRayBuffer) { ++buffer_counter; }
 
-static bool unused = [] {
+int main(int argc, char **argv) {
   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_log_get_current_mode() != nullptr);
   std::string current_mode = __xray_log_get_current_mode();
   assert(current_mode == "custom");
   assert(__xray_patch() == XRayPatchingStatus::SUCCESS);
-  assert(__xray_log_init(0, 0, nullptr, 0) ==
+  assert(__xray_log_init_mode("custom", "flags_config_here=true") ==
          XRayLogInitStatus::XRAY_LOG_INITIALIZED);
+
+  // Also test that we can use the "binary" version of the
+  // __xray_log_niit_mode(...) API.
+  assert(__xray_log_init_mode_bin("custom", Options, sizeof(Options)) ==
+         XRayLogInitStatus::XRAY_LOG_INITIALIZED);
+
   // CHECK: printing {{.*}}
   callme(); // CHECK: called me!
   // CHECK: printing {{.*}}