From b0a4a7125564d18d89f0aecb2d483a2b0e9410a3 Mon Sep 17 00:00:00 2001
From: Yi Lin <qinsoon@gmail.com>
Date: Mon, 4 Sep 2023 04:36:24 +0000
Subject: [PATCH] Update doc to add a section for LTO

---
 docs/userguide/src/portingguide/SUMMARY.md    |  2 +
 .../src/portingguide/perf_tuning/lto.md       | 38 +++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/userguide/src/portingguide/perf_tuning/lto.md

diff --git a/docs/userguide/src/portingguide/SUMMARY.md b/docs/userguide/src/portingguide/SUMMARY.md
index 64b95a9d7f..07f35c8bf0 100644
--- a/docs/userguide/src/portingguide/SUMMARY.md
+++ b/docs/userguide/src/portingguide/SUMMARY.md
@@ -7,3 +7,5 @@
 - [How to Undertake a Port](./howto/prefix.md)
     - [NoGC](./howto/nogc.md)
     - [Next Steps](./howto/next_steps.md)
+- [Performance Tuning]()
+    - [Link Time Optimization](./perf_tuning/lto.md)
diff --git a/docs/userguide/src/portingguide/perf_tuning/lto.md b/docs/userguide/src/portingguide/perf_tuning/lto.md
new file mode 100644
index 0000000000..892efb56ed
--- /dev/null
+++ b/docs/userguide/src/portingguide/perf_tuning/lto.md
@@ -0,0 +1,38 @@
+# Enabling Link Time Optimization (LTO) with MMTk
+
+MMTk's API is designed with an assumption that LTO will be enabled for a performant build.
+It is essential to allow the Rust compiler to optimize across the crate boundary between the binding crate and mmtk-core.
+LTO allows inlining for both directions (from mmtk-core to the binding, and from the binding to mmtk-core),
+and allows further optimization such as specializing and constant folding for the `VMBinding` trait.
+
+We suggest enabling LTO for the release build in the binding's manifest (`Cargo.toml`) by adding a profile for the release build,
+so LTO is always enabled for a release build.
+
+```toml
+[profile.release]
+lto = true
+```
+
+If your binding project is a Rust binary (e.g. the VM is written in Rust), this should be enough. However, if your binding project
+is a library, there are some limitations with cargo that you should be aware of.
+
+
+## Binding as a library
+
+Cargo only allows LTO for certain crate types. You will need to specify the crate type properly, otherwise cargo may skip LTO without
+any warning or error.
+
+```toml
+[lib]
+...
+# be careful - LTO is only allowed for certain crate types
+crate-type = ["cdylib"]
+```
+
+At the time of writing, cargo has some limitations about LTO with different crate types:
+1. LTO is only allowed with `cdylib` and `staticlib` (other than `bin`).
+Check the code of [`can_lto`](https://github.com/rust-lang/cargo/blob/5f40a97e5c85affecfbc4fde67fc06bf188c07db/src/cargo/core/compiler/crate_type.rs#L33)
+for your Rust version to clarify.
+2. If the `crate-type` field includes any type that LTO is not allowed, LTO will be skipped for all the libraries generated (https://github.com/rust-lang/rust/issues/51009).
+For example, if you have `crate-type = ["cdylib", "rlib"]` and cargo cannot do LTO for `rlib`, LTO will be skipped for `cdylib` as well.
+So only keep the crate type that you actually need in the `crate-type` field.