[XRay][docs] Document xray_mode and log registration API.

This marks certain flags in XRay as deprecated (in particular,
`xray_naive_log=` and `xray_fdr_log=`), and recommends the use of the
`xray_mode=` flag.

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

diff --git a/docs/XRay.rst b/docs/XRay.rst
index b4443c4d8060a799337d4ab91ea7dc7244d95282..942b479af749c940eec465208c05ca40f8a7df1c 100644 (file)
--- a/docs/XRay.rst
+++ b/docs/XRay.rst
@@ -143,15 +143,25 @@ variable, where we list down the options and their defaults below.
 |                   |                 |               | instrumentation points |
 |                   |                 |               | before main.           |
 +-------------------+-----------------+---------------+------------------------+
-| xray_naive_log    | ``bool``        | ``false``     | Whether to install     |
-|                   |                 |               | the naive log          |
-|                   |                 |               | implementation.        |
+| xray_mode         | ``const char*`` | ``""``        | Default mode to        |
+|                   |                 |               | install and initialize |
+|                   |                 |               | before ``main``.       |
 +-------------------+-----------------+---------------+------------------------+
 | xray_logfile_base | ``const char*`` | ``xray-log.`` | Filename base for the  |
 |                   |                 |               | XRay logfile.          |
 +-------------------+-----------------+---------------+------------------------+
-| xray_fdr_log      | ``bool``        | ``false``     | Whether to install the |
-|                   |                 |               | Flight Data Recorder   |
+| xray_naive_log    | ``bool``        | ``false``     | **DEPRECATED:** Use    |
+|                   |                 |               | xray_mode=xray-basic   |
+|                   |                 |               | instead. Whether to    |
+|                   |                 |               | install the basic log  |
+|                   |                 |               | the naive log          |
+|                   |                 |               | implementation.        |
++-------------------+-----------------+---------------+------------------------+
+| xray_fdr_log      | ``bool``        | ``false``     | **DEPRECATED:** Use    |
+|                   |                 |               | xray_mode=xray-fdr     |
+|                   |                 |               | instead. Whether to    |
+|                   |                 |               | install the Flight     |
+|                   |                 |               | Data Recorder          |
 |                   |                 |               | (FDR) mode.            |
 +-------------------+-----------------+---------------+------------------------+
 
@@ -241,6 +251,14 @@ following API:
 - ``__xray_set_log_impl(...)``: This function takes a struct of type
   ``XRayLogImpl``, which is defined in ``xray/xray_log_interface.h``, part of
   the XRay compiler-rt installation.
+- ``__xray_log_register_mode(...)``: Register a logging implementation against
+  a string Mode. The implementation is an instance of ``XRayLogImpl`` defined
+  in ``xray/xray_log_interface.h``.
+- ``__xray_log_select_mode(...)``: Select the mode to install, associated with
+  a string Mode. Only implementations registered with
+  ``__xray_log_register_mode(...)`` can be chosen with this function. When
+  successful, has the same effects as calling ``__xray_set_log_impl(...)`` with
+  the registered logging implementation.
 - ``__xray_log_init(...)``: This function allows for initializing and
   re-initializing an installed logging implementation. See
   ``xray/xray_log_interface.h`` for details, part of the XRay compiler-rt

diff --git a/docs/XRayExample.rst b/docs/XRayExample.rst
index 953833bc1ef65a1feec2e8dc21f0ec7c29d2430e..9f74442bcebe962b21e5b77ec2a243af80b727c7 100644 (file)
--- a/docs/XRayExample.rst
+++ b/docs/XRayExample.rst
@@ -60,7 +60,7 @@ to enable XRay at application start. To do this, XRay checks the
   $ ./bin/llc input.ll
 
   # We need to set the XRAY_OPTIONS to enable some features.
-  $ XRAY_OPTIONS="patch_premain=true xray_naive_log=true" ./bin/llc input.ll
+  $ XRAY_OPTIONS="patch_premain=true xray_mode=xray-basic" ./bin/llc input.ll
   ==69819==XRay: Log file in 'xray-log.llc.m35qPB'
 
 At this point we now have an XRay trace we can start analysing.