From 0e60df9ed1439cb9d7bcc1a09bf2fc87d03393b1 Mon Sep 17 00:00:00 2001 From: Oleksii Lozovskyi Date: Sat, 24 Sep 2022 20:02:44 +0900 Subject: 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. --- .../src/compiler-flags/instrument-xray.md | 39 ++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 src/doc/unstable-book/src/compiler-flags/instrument-xray.md (limited to 'src') 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). -- cgit 1.4.1-3-g733a5