[llvm-branch-commits] [libcxx] [libc] [clang-tools-extra] [llvm] [lldb] [clang] [mlir] [BOLT] Add BOLT Address Translation documentation (PR #76898)

[Rafael Auler via llvm-branch-commits]

================
@@ -0,0 +1,97 @@
+# BOLT Address Translation (BAT)
+# Purpose
+A regular profile collection for BOLT involves collecting samples from
+unoptimized binary. BOLT Address Translation allows collecting profile
+from BOLT-optimized binary and using it for optimizing the input (pre-BOLT)
+binary.
+
+# Overview
+BOLT Address Translation is an extra section (`.note.bolt_bat`) inserted by BOLT
+into the output binary containing translation tables and split functions linkage
+information. This information enables mapping the profile back from optimized
+binary onto the original binary.
+
+# Usage
+`--enable-bat` flag controls the generation of BAT section. Sampled profile
+needs to be passed along with the optimized binary containing BAT section to
+`perf2bolt` which reads BAT section and produces fdata profile for the original
+binary. Note that YAML profile generation is not supported since BAT doesn't
+contain the metadata for input functions.
+
+# Internals
+## Section contents
+The section is organized as follows:
+- Functions table
+  - Address translation tables
+- Fragment linkage table
+
+## Construction and parsing
+BAT section is created from `BoltAddressTranslation` class which captures
+address translation information provided by BOLT linker. It is then encoded as a
+note section in the output binary.
+
+During profile conversion when BAT-enabled binary is passed to perf2bolt,
+`BoltAddressTranslation` class is populated from BAT section. The class is then
+queried by `DataAggregator` during sample processing to reconstruct addresses/
+offsets in the input binary.
+
+## Encoding format
+The encoding is specified in
+[BoltAddressTranslation.h](/bolt/include/bolt/Profile/BoltAddressTranslation.h)
+and [BoltAddressTranslation.cpp](/bolt/lib/Profile/BoltAddressTranslation.cpp).
+
+### Layout
+The general layout is as follows:
+```
+Functions table header
+|------------------|
+|  Function entry  |
+| |--------------| |
+| | OutOff InOff | |
+| |--------------| |
+~~~~~~~~~~~~~~~~~~~~
+
+Fragment linkage header
+|------------------|
+| ColdAddr HotAddr |
+~~~~~~~~~~~~~~~~~~~~
+```
+
+### Functions table
+Header:
+| Entry  | Width | Description |
+| ------ | ----- | ----------- |
+| `NumFuncs` | 4b | Number of functions in the functions table |
----------------
rafaelauler wrote:

Minor suggestion:
4b -> 4B

I usually see Bytes capitalized, but that's up to you

https://github.com/llvm/llvm-project/pull/76898