[llvm-branch-commits] [llvm] [BOLT] Support negative hex in pre-aggregated profile (PR #192391)

[Amir Ayupov via llvm-branch-commits]

https://github.com/aaupov updated https://github.com/llvm/llvm-project/pull/192391

>From b9fa9bdae0c2932c3846c06483fa690c4d1a18fc Mon Sep 17 00:00:00 2001
From: Amir Ayupov <aaupov at fb.com>
Date: Thu, 23 Apr 2026 19:45:06 -0700
Subject: [PATCH 1/2] updated documentation

Created using spr 1.3.4
---
 bolt/docs/profiles.md | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/bolt/docs/profiles.md b/bolt/docs/profiles.md
index d03e99746cb51..7385043a63056 100644
--- a/bolt/docs/profiles.md
+++ b/bolt/docs/profiles.md
@@ -79,13 +79,39 @@ Where:
 - `r` — Aggregated fall-through originating at an external return (no checks
   performed for fall-through start).
 
+Internally, all branch/fall-through formats are represented as traces, with the
+following field mapping:
+- `B <start> <end>` -> `T <start> <end> BR_ONLY`
+- `F <start> <end>` -> `T FT_ONLY <start> <end>`
+- `f <start> <end>` -> `T FT_EXTERNAL_ORIGIN <start> <end>`
+- `r <start> <end>` -> `R FT_EXTERNAL_RETURN <start> <end>`
+
+The constants have the following values and can be specified directly:
+- `BR_ONLY`/`FT_ONLY`: UINT64_MAX: ffffffffffffffff or -1
+- `FT_EXTERNAL_ORIGIN`: UINT64_MAX-1: fffffffffffffffe or -2
+- `FT_EXTERNAL_RETURN`: UINT64_MAX-2: fffffffffffffffd or -3
+
+e.g. `T <branch> <target> -1` is a branch trace with unknown fall-through, useful
+for representing top-of-brstack entries having no valid fall-through. Note that
+such traces can be extended with an average fall-through length by passing
+`--impute-trace-fall-through`.
+
+`R`/`r` mark a fall-through originating at a return so it can be extended back
+to cover the call site, improving profile continuity. The hint is only needed
+for external returns (e.g. from a PLT call), where the return instruction can't
+be disassembled to tell a return from an ordinary jump.
+
+
 ### Location format
 
-Locations have the format `[<buildid>:]<offset>`:
-- `<offset>` — Hex offset from the object base load address.
+Locations have the format `[<buildid>:]<addr>`:
+- `<addr>` — Hex vaddr (non-PIE) or offset from the object base load address (PIE).
 - `<buildid>:<offset>` — Offset within the object identified by `<buildid>`.
 - `X:<addr>` — External address (outside the profiled binary).
 
+Base load address is the address of the first `PT_LOAD` segment in the binary, which
+may not be the same as the segment containing code address.
+
 ### Examples
 
 Basic samples profile:

>From 560c68194c5ac3cc9c70944fc03e40c895d98656 Mon Sep 17 00:00:00 2001
From: Amir Ayupov <aaupov at fb.com>
Date: Thu, 23 Apr 2026 20:26:42 -0700
Subject: [PATCH 2/2] updated docs

Created using spr 1.3.4
---
 bolt/docs/profiles.md | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/bolt/docs/profiles.md b/bolt/docs/profiles.md
index 7385043a63056..f208620be85ce 100644
--- a/bolt/docs/profiles.md
+++ b/bolt/docs/profiles.md
@@ -74,11 +74,10 @@ Where:
 - `R` — Aggregated trace originating at a return.
 - `B` — Aggregated branch from `<start>` to `<end>`.
 - `F` — Aggregated fall-through from `<start>` to `<end>`.
-- `f` — Aggregated fall-through with external origin (disambiguates returns
-  hitting a basic block head from regular internal jumps).
-- `r` — Aggregated fall-through originating at an external return (no checks
-  performed for fall-through start).
+- `f` — Aggregated fall-through with external origin.
+- `r` — Aggregated fall-through with external return as origin.
 
+### Trace mapping
 Internally, all branch/fall-through formats are represented as traces, with the
 following field mapping:
 - `B <start> <end>` -> `T <start> <end> BR_ONLY`
@@ -91,16 +90,24 @@ The constants have the following values and can be specified directly:
 - `FT_EXTERNAL_ORIGIN`: UINT64_MAX-1: fffffffffffffffe or -2
 - `FT_EXTERNAL_RETURN`: UINT64_MAX-2: fffffffffffffffd or -3
 
-e.g. `T <branch> <target> -1` is a branch trace with unknown fall-through, useful
-for representing top-of-brstack entries having no valid fall-through. Note that
-such traces can be extended with an average fall-through length by passing
-`--impute-trace-fall-through`.
+### Call continuation fall-throughs
+Where applicable, call continuation fall-throughs are extended back to cover
+the call site, improving profile continuity:
+- `f`: check that the fall-through start is a block start, not an entry point
+  or a landing pad.
+- `R`/`r`: unconditional.
+- `T`: local origin: extend only if it's a return. External origin: use `f`.
+
+Return hint is only needed for external returns (e.g. from a PLT call), where
+the address can't be disassembled to distinguish a return from a jump.
 
-`R`/`r` mark a fall-through originating at a return so it can be extended back
-to cover the call site, improving profile continuity. The hint is only needed
-for external returns (e.g. from a PLT call), where the return instruction can't
-be disassembled to tell a return from an ordinary jump.
+### Best practices
+Use T/R format. To capture branch type using Linux perf events, set
+the `PERF_SAMPLE_BRANCH_TYPE_SAVE` flag in `perf_event_attr::branch_sample_type`.
 
+To represent top of brstack entry with no fall-through, use `BR_ONLY` as `ft_end`.
+Such traces can be extended with an average fall-through length by passing
+`--impute-trace-fall-through`.
 
 ### Location format
 
@@ -127,6 +134,11 @@ Trace profile combining branches and fall-throughs:
 T 4b196f 4b19e0 4b19ef 2
 ```
 
+Trace with unknown fall-through:
+```
+T 4b196f 4b19e0 -1 2
+```
+
 Legacy branch profile with separate branches and fall-throughs:
 ```
 F 41be50 41be50 3