bolt/docs/BAT.md

   1 # BOLT Address Translation (BAT)
   2 # Purpose
   3 A regular profile collection for BOLT involves collecting samples from
   4 unoptimized binary. BOLT Address Translation allows collecting profile
   5 from BOLT-optimized binary and using it for optimizing the input (pre-BOLT)
   6 binary.
   7
   8 # Overview
   9 BOLT Address Translation is an extra section (`.note.bolt_bat`) inserted by BOLT
  10 into the output binary containing translation tables and split functions linkage
  11 information. This information enables mapping the profile back from optimized
  12 binary onto the original binary.
  13
  14 # Usage
  15 `--enable-bat` flag controls the generation of BAT section. Sampled profile
  16 needs to be passed along with the optimized binary containing BAT section to
  17 `perf2bolt` which reads BAT section and produces fdata profile for the original
  18 binary. Note that YAML profile generation is not supported since BAT doesn't
  19 contain the metadata for input functions.
  20
  21 # Internals
  22 ## Section contents
  23 The section is organized as follows:
  24 - Hot functions table
  25   - Address translation tables
  26 - Cold functions table
  27
  28 ## Construction and parsing
  29 BAT section is created from `BoltAddressTranslation` class which captures
  30 address translation information provided by BOLT linker. It is then encoded as a
  31 note section in the output binary.
  32
  33 During profile conversion when BAT-enabled binary is passed to perf2bolt,
  34 `BoltAddressTranslation` class is populated from BAT section. The class is then
  35 queried by `DataAggregator` during sample processing to reconstruct addresses/
  36 offsets in the input binary.
  37
  38 ## Encoding format
  39 The encoding is specified in
  40 [BoltAddressTranslation.h](/bolt/include/bolt/Profile/BoltAddressTranslation.h)
  41 and [BoltAddressTranslation.cpp](/bolt/lib/Profile/BoltAddressTranslation.cpp).
  42
  43 ### Layout
  44 The general layout is as follows:
  45 ```
  46 Hot functions table header
  47 |------------------|
  48 |  Function entry  |
  49 | |--------------| |
  50 | | OutOff InOff | |
  51 | |--------------| |
  52 ~~~~~~~~~~~~~~~~~~~~
  53
  54 Cold functions table header
  55 |------------------|
  56 |  Function entry  |
  57 | |--------------| |
  58 | | OutOff InOff | |
  59 | |--------------| |
  60 ~~~~~~~~~~~~~~~~~~~~
  61 ```
  62
  63 ### Functions table
  64 Hot and cold functions tables share the encoding except difference marked below.
  65 Header:
  66 | Entry  | Encoding | Description |
  67 | ------ | ----- | ----------- |
  68 | `NumFuncs` | ULEB128 | Number of functions in the functions table |
  69
  70 The header is followed by Functions table with `NumFuncs` entries.
  71 Output binary addresses are delta encoded, meaning that only the difference with
  72 the last previous output address is stored. Addresses implicitly start at zero.
  73 Output addresses are continuous through function start addresses and function
  74 internal offsets, and between hot and cold fragments, to better spread deltas
  75 and save space.
  76
  77 Hot indices are delta encoded, implicitly starting at zero.
  78 | Entry  | Encoding | Description |
  79 | ------ | ------| ----------- |
  80 | `Address` | Continuous, Delta, ULEB128 | Function address in the output binary |
  81 | `HotIndex` | Delta, ULEB128 | Cold functions only: index of corresponding hot function in hot functions table |
  82 | `NumEntries` | ULEB128 | Number of address translation entries for a function |
  83
  84 Function header is followed by `NumEntries` pairs of offsets for current
  85 function.
  86
  87 ### Address translation table
  88 Delta encoding means that only the difference with the previous corresponding
  89 entry is encoded. Input offsets implicitly start at zero.
  90 | Entry  | Encoding | Description |
  91 | ------ | ------| ----------- |
  92 | `OutputOffset` | Continuous, Delta, ULEB128 | Function offset in output binary |
  93 | `InputOffset` | Delta, SLEB128 | Function offset in input binary with `BRANCHENTRY` LSB bit |
  94
  95 `BRANCHENTRY` bit denotes whether a given offset pair is a control flow source
  96 (branch or call instruction). If not set, it signifies a control flow target
  97 (basic block offset).