Parse "-Z instrument-xray" codegen option

Recognize all bells and whistles that LLVM's XRay pass is capable of.
The always/never settings are a bit dumb without attributes but they're
still there. The default instruction count is chosen by the compiler,
not LLVM pass. We'll do it later.

1 files changed, 39 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/instrument-xray.md b/src/doc/unstable-book/src/compiler-flags/instrument-xray.md
new file mode 100644
index 00000000000..7fb33cd68b4
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/instrument-xray.md
@@ -0,0 +1,39 @@
+# `instrument-xray`
+
+The tracking issue for this feature is: [#102921](https://github.com/rust-lang/rust/issues/102921).
+
+------------------------
+
+Enable generation of NOP sleds for XRay function tracing instrumentation.
+For more information on XRay,
+read [LLVM documentation](https://llvm.org/docs/XRay.html),
+and/or the [XRay whitepaper](http://research.google.com/pubs/pub45287.html).
+
+Set the `-Z instrument-xray` compiler flag in order to enable XRay instrumentation.
+
+  - `-Z instrument-xray` – use the default settings
+  - `-Z instrument-xray=skip-exit` – configure a custom setting
+  - `-Z instrument-xray=ignore-loops,instruction-threshold=300` –
+    multiple settings separated by commas
+
+Supported options:
+
+  - `always` – force instrumentation of all functions
+  - `never` – do no instrument any functions
+  - `ignore-loops` – ignore presence of loops,
+    instrument functions based only on instruction count
+  - `instruction-threshold=10` – set a different instruction threshold for instrumentation
+  - `skip-entry` – do no instrument function entry
+  - `skip-exit` – do no instrument function exit
+
+The default settings are:
+
+  - instrument both entry & exit from functions
+  - instrument functions with at least 200 instructions,
+    or containing a non-trivial loop
+
+Note that `-Z instrument-xray` only enables generation of NOP sleds
+which on their own don't do anything useful.
+In order to actually trace the functions,
+you will need to link a separate runtime library of your choice,
+such as Clang's [XRay Runtime Library](https://www.llvm.org/docs/XRay.html#xray-runtime-library).