[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.
llvm-svn: 319763
diff --git a/llvm/docs/XRay.rst b/llvm/docs/XRay.rst
index b4443c4..942b479 100644
--- a/llvm/docs/XRay.rst
+++ b/llvm/docs/XRay.rst
@@ -143,15 +143,25 @@
| | | | 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 @@
- ``__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/llvm/docs/XRayExample.rst b/llvm/docs/XRayExample.rst
index 953833bc..9f74442 100644
--- a/llvm/docs/XRayExample.rst
+++ b/llvm/docs/XRayExample.rst
@@ -60,7 +60,7 @@
$ ./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.