Enable AutoFDO.

This largely involves implementing the options debug-info-for-profiling
and profile-sample-use and forwarding them on to LLVM.

AutoFDO can be used on x86-64 Linux like this:
rustc -O -Cdebug-info-for-profiling main.rs -o main
perf record -b ./main
create_llvm_prof --binary=main --out=code.prof
rustc -O -Cprofile-sample-use=code.prof main.rs -o main2

Now `main2` will have feedback directed optimization applied to it.

The create_llvm_prof tool can be obtained from this github repository:
https://github.com/google/autofdo

Fixes #64892.

2 files changed, 45 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/compiler-flags/debug_info_for_profiling.md b/src/doc/unstable-book/src/compiler-flags/debug_info_for_profiling.md
new file mode 100644
index 00000000000..44bd3baeeed
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/debug_info_for_profiling.md
@@ -0,0 +1,35 @@
+# `debug-info-for-profiling
+
+---
+
+## Introduction
+
+Automatic Feedback Directed Optimization (AFDO) is a method for using sampling
+based profiles to guide optimizations. This is contrasted with other methods of
+FDO or profile-guided optimization (PGO) which use instrumented profiling.
+
+Unlike PGO (controlled by the `rustc` flags `-Cprofile-generate` and
+`-Cprofile-use`), a binary being profiled does not perform significantly worse,
+and thus it's possible to profile binaries used in real workflows and not
+necessary to construct artificial workflows.
+
+## Use
+
+In order to use AFDO, the target platform must be Linux running on an `x86_64`
+architecture with the performance profiler `perf` available. In addition, the
+external tool `create_llvm_prof` from [this repository] must be used.
+
+Given a Rust file `main.rs`, we can produce an optimized binary as follows:
+
+```shell
+rustc -O -Zdebug-info-for-profiling main.rs -o main
+perf record -b ./main
+create_llvm_prof --binary=main --out=code.prof
+rustc -O -Zprofile-sample-use=code.prof main.rs -o main2
+```
+
+The `perf` command produces a profile `perf.data`, which is then used by the
+`create_llvm_prof` command to create `code.prof`. This final profile is then
+used by `rustc` to guide optimizations in producing the binary `main2`.
+
+[this repository]: https://github.com/google/autofdo
diff --git a/src/doc/unstable-book/src/compiler-flags/profile_sample_use.md b/src/doc/unstable-book/src/compiler-flags/profile_sample_use.md
new file mode 100644
index 00000000000..ce894ce6ac7
--- /dev/null
+++ b/src/doc/unstable-book/src/compiler-flags/profile_sample_use.md
@@ -0,0 +1,10 @@
+# `profile-sample-use
+
+---
+
+`-Zprofile-sample-use=code.prof` directs `rustc` to use the profile
+`code.prof` as a source for Automatic Feedback Directed Optimization (AFDO).
+See the documentation of [`-Zdebug-info-for-profiling`] for more information
+on using AFDO.
+
+[`-Zdebug-info-for-profiling`]: debug_info_for_profiling.html