[llvm] [BOLT][Documentation] Prepare documentation for hosting (PR #201378)
Amina Chabane via llvm-commits
llvm-commits at lists.llvm.org
Wed Jun 3 08:00:59 PDT 2026
https://github.com/Amichaxx created https://github.com/llvm/llvm-project/pull/201378
This PR aims to organise BOLT's docs in preparation for hosting.
- Added a landing page into index.rst, much like [clang.llvm.org](https://clang.llvm.org/docs/index.html).
<img width="1731" height="1311" alt="image" src="https://github.com/user-attachments/assets/4fa376bf-cdf1-4ad1-8be5-1de57597ac10" />
- Moved Getting Started content from index.rst into its own GettingStarted.rst.
- Enables Markdown content to be rendered. A current [discussion](https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/90840) is being had about MD/RST on discourse, but for now I have decided to support the mix of formats currently in BOLT.
- Included AArch64 optimization status page.
- Fixes some links/anchors.
**Build with Sphinx**
`sphinx-build -b html bolt/docs bolt-docs-html`
Requries Sphinx and myst_parser.
>From ab581fe3ae4c6bc7d65cd11ed15606ffc9b6c271 Mon Sep 17 00:00:00 2001
From: Amichaxx <amina.chabane at arm.com>
Date: Mon, 1 Jun 2026 14:26:37 +0000
Subject: [PATCH] wip
---
bolt/docs/BAT.md | 4 +-
bolt/docs/BinaryAnalysis.md | 3 +-
bolt/docs/GettingStarted.rst | 255 +++++++++++++++++++++++++++++++
bolt/docs/OptimizingClang.md | 2 +-
bolt/docs/PointerAuthDesign.md | 6 +-
bolt/docs/conf.py | 11 +-
bolt/docs/index.rst | 268 +++------------------------------
7 files changed, 296 insertions(+), 253 deletions(-)
create mode 100644 bolt/docs/GettingStarted.rst
diff --git a/bolt/docs/BAT.md b/bolt/docs/BAT.md
index fa43e81553d5c..72bea710d64e2 100644
--- a/bolt/docs/BAT.md
+++ b/bolt/docs/BAT.md
@@ -36,8 +36,8 @@ 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).
+[BoltAddressTranslation.h](https://github.com/llvm/llvm-project/blob/main/bolt/include/bolt/Profile/BoltAddressTranslation.h)
+and [BoltAddressTranslation.cpp](https://github.com/llvm/llvm-project/blob/main/bolt/lib/Profile/BoltAddressTranslation.cpp).
### Layout
The general layout is as follows:
diff --git a/bolt/docs/BinaryAnalysis.md b/bolt/docs/BinaryAnalysis.md
index 30be23fbf8b57..1d8d9e64ea794 100644
--- a/bolt/docs/BinaryAnalysis.md
+++ b/bolt/docs/BinaryAnalysis.md
@@ -193,7 +193,7 @@ with the specific set depending on command line options:
non-protected return instruction
* [`ptrauth-tail-calls`](#return-address-protection-before-tail-call-ptrauth-tail-calls) -
performing a tail call with an untrusted value in the link register
-* [`ptrauth-forward-cf`](#indirect-branch-call-target-protection-ptrauth-forward-cf) -
+* [`ptrauth-forward-cf`](#ptrauth-forward-cf) -
non-protected destination of branch or call instruction
* [`ptrauth-sign-oracles`](#signing-oracles-ptrauth-sign-oracles) -
signing of untrusted value (signing oracle)
@@ -370,6 +370,7 @@ check after a regular authentication instruction, which may be either too
expensive (if a fully-generic XPAC-based sequence is being used) on one hand,
or not required at all (if `FEAT_FPAC` is known to be implemented) on the other hand.
+(ptrauth-forward-cf)=
### Indirect branch / call target protection (`ptrauth-forward-cf`)
**Instructions:** Indirect call and branch instructions without built-in
diff --git a/bolt/docs/GettingStarted.rst b/bolt/docs/GettingStarted.rst
new file mode 100644
index 0000000000000..ab410b3a6ff04
--- /dev/null
+++ b/bolt/docs/GettingStarted.rst
@@ -0,0 +1,255 @@
+Getting Started with BOLT
+=========================
+
+Input Binary Requirements
+-------------------------
+
+BOLT operates on X86-64 and AArch64 ELF binaries. At the minimum, the
+binaries should have an unstripped symbol table, and, to get maximum
+performance gains, they should be linked with relocations
+(``--emit-relocs`` or ``-q`` linker flag).
+
+BOLT disassembles functions and reconstructs the control flow graph
+(CFG) before it runs optimizations. Since this is a nontrivial task,
+especially when indirect branches are present, we rely on certain
+heuristics to accomplish it. These heuristics have been tested on a code
+generated with Clang and GCC compilers. The main requirement for C/C++
+code is not to rely on code layout properties, such as function pointer
+deltas. Assembly code can be processed too. Requirements for it include
+a clear separation of code and data, with data objects being placed into
+data sections/segments. If indirect jumps are used for intra-function
+control transfer (e.g., jump tables), the code patterns should be
+matching those generated by Clang/GCC.
+
+NOTE: BOLT is currently incompatible with the
+``-freorder-blocks-and-partition`` compiler option. Since GCC8 enables
+this option by default, you have to explicitly disable it by adding
+``-fno-reorder-blocks-and-partition`` flag if you are compiling with
+GCC8 or above.
+
+NOTE2: DWARF v5 is the new debugging format generated by the latest LLVM
+and GCC compilers. It offers several benefits over the previous DWARF
+v4. Currently, the support for v5 is a work in progress for BOLT. While
+you will be able to optimize binaries produced by the latest compilers,
+until the support is complete, you will not be able to update the debug
+info with ``-update-debug-sections``. To temporarily work around the
+issue, we recommend compiling binaries with ``-gdwarf-4`` option that
+forces DWARF v4 output.
+
+PIE and .so support has been added recently. Please report bugs if you
+encounter any issues.
+
+Installation
+------------
+
+Docker Image
+~~~~~~~~~~~~
+
+You can build and use the docker image containing BOLT using our `docker
+file <https://github.com/llvm/llvm-project/blob/main/bolt/utils/docker/Dockerfile>`__.
+Alternatively, you can build BOLT manually using the steps below.
+
+Manual Build
+~~~~~~~~~~~~
+
+BOLT heavily uses LLVM libraries, and by design, it is built as one of
+LLVM tools. The build process is not much different from a regular LLVM
+build. The following instructions are assuming that you are running
+under Linux.
+
+Start with cloning LLVM repo:
+
+::
+
+ > git clone https://github.com/llvm/llvm-project.git
+ > mkdir build
+ > cd build
+ > cmake -G Ninja ../llvm-project/llvm -DLLVM_TARGETS_TO_BUILD="X86;AArch64" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_ENABLE_PROJECTS="bolt"
+ > ninja bolt
+
+``llvm-bolt`` will be available under ``bin/``. Add this directory to
+your path to ensure the rest of the commands in this tutorial work.
+
+Optimizing BOLT’s Performance
+-----------------------------
+
+BOLT runs many internal passes in parallel. If you foresee heavy usage
+of BOLT, you can improve the processing time by linking against one of
+memory allocation libraries with good support for concurrency. E.g. to
+use jemalloc:
+
+::
+
+ > sudo yum install jemalloc-devel
+ > LD_PRELOAD=/usr/lib64/libjemalloc.so llvm-bolt ....
+
+Or if you rather use tcmalloc:
+
+::
+
+ > sudo yum install gperftools-devel
+ > LD_PRELOAD=/usr/lib64/libtcmalloc_minimal.so llvm-bolt ....
+
+Usage
+-----
+
+For a complete practical guide of using BOLT see :doc:`OptimizingClang`.
+
+Step 0
+~~~~~~
+
+In order to allow BOLT to re-arrange functions (in addition to
+re-arranging code within functions) in your program, it needs a little
+help from the linker. Add ``--emit-relocs`` to the final link step of
+your application. You can verify the presence of relocations by checking
+for ``.rela.text`` section in the binary. BOLT will also report if it
+detects relocations while processing the binary.
+
+Step 1: Collect Profile
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This step is different for different kinds of executables. If you can
+invoke your program to run on a representative input from a command
+line, then check **For Applications** section below. If your program
+typically runs as a server/service, then skip to **For Services**
+section.
+
+The version of ``perf`` command used for the following steps has to
+support ``-F brstack`` option. We recommend using ``perf`` version 4.5
+or later.
+
+For Applications
+^^^^^^^^^^^^^^^^
+
+This assumes you can run your program from a command line with a typical
+input. In this case, simply prepend the command line invocation with
+``perf``:
+
+::
+
+ $ perf record -e cycles:u -j any,u -o perf.data -- <executable> <args> ...
+
+For Services
+^^^^^^^^^^^^
+
+Once you get the service deployed and warmed-up, it is time to collect
+perf data with LBR (branch information). The exact perf command to use
+will depend on the service. E.g., to collect the data for all processes
+running on the server for the next 3 minutes use:
+
+::
+
+ $ perf record -e cycles:u -j any,u -a -o perf.data -- sleep 180
+
+Depending on the application, you may need more samples to be included
+with your profile. It’s hard to tell upfront what would be a sweet spot
+for your application. We recommend the profile to cover 1B instructions
+as reported by BOLT ``-dyno-stats`` option. If you need to increase the
+number of samples in the profile, you can either run the ``sleep``
+command for longer and use ``-F<N>`` option with ``perf`` to increase
+sampling frequency.
+
+Note that for profile collection we recommend using cycle events and not
+``BR_INST_RETIRED.*``. Empirically we found it to produce better
+results.
+
+If the collection of a profile with branches is not available, e.g.,
+when you run on a VM or on hardware that does not support it, then you
+can use only sample events, such as cycles. In this case, the quality of
+the profile information would not be as good, and performance gains with
+BOLT are expected to be lower.
+
+With instrumentation
+^^^^^^^^^^^^^^^^^^^^
+
+If perf record is not available to you, you may collect profile by first
+instrumenting the binary with BOLT and then running it.
+
+::
+
+ llvm-bolt <executable> -instrument -o <instrumented-executable>
+
+After you run instrumented-executable with the desired workload, its
+BOLT profile should be ready for you in ``/tmp/prof.fdata`` and you can
+skip **Step 2**.
+
+Run BOLT with the ``-help`` option and check the category “BOLT
+instrumentation options” for a quick reference on instrumentation knobs.
+
+Step 2: Convert Profile to BOLT Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+NOTE: you can skip this step and feed ``perf.data`` directly to BOLT
+using experimental ``-p perf.data`` option.
+
+For this step, you will need ``perf.data`` file collected from the
+previous step and a copy of the binary that was running. The binary has
+to be either unstripped, or should have a symbol table intact (i.e.,
+running ``strip -g`` is okay).
+
+Make sure ``perf`` is in your ``PATH``, and execute ``perf2bolt``:
+
+::
+
+ $ perf2bolt -p perf.data -o perf.fdata <executable>
+
+This command will aggregate branch data from ``perf.data`` and store it
+in a format that is both more compact and more resilient to binary
+modifications.
+
+If the profile was collected without brstacks, you will need to add `-ba` flag to
+the command line above.
+
+Step 3: Optimize with BOLT
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have ``perf.fdata`` ready, you can use it for optimizations
+with BOLT. Assuming your environment is setup to include the right path,
+execute ``llvm-bolt``:
+
+::
+
+ $ llvm-bolt <executable> -o <executable>.bolt -data=perf.fdata -reorder-blocks=ext-tsp -reorder-functions=hfsort -split-functions -split-all-cold -split-eh -dyno-stats
+
+If you do need an updated debug info, then add
+``-update-debug-sections`` option to the command above. The processing
+time will be slightly longer.
+
+For a full list of options see ``-help``/``-help-hidden`` output.
+
+The input binary for this step does not have to 100% match the binary
+used for profile collection in **Step 1**. This could happen when you
+are doing active development, and the source code constantly changes,
+yet you want to benefit from profile-guided optimizations. However,
+since the binary is not precisely the same, the profile information
+could become invalid or stale, and BOLT will report the number of
+functions with a stale profile. The higher the number, the less
+performance improvement should be expected. Thus, it is crucial to
+update ``.fdata`` for release branches.
+
+Multiple Profiles
+-----------------
+
+Suppose your application can run in different modes, and you can
+generate multiple profiles for each one of them. To generate a single
+binary that can benefit all modes (assuming the profiles don’t
+contradict each other) you can use ``merge-fdata`` tool:
+
+::
+
+ $ merge-fdata *.fdata > combined.fdata
+
+Use ``combined.fdata`` for **Step 3** above to generate a universally
+optimized binary.
+
+Profile Formats
+---------------
+
+See :doc:`profiles` for comprehensive documentation of all profile formats
+accepted by BOLT: perf.data, fdata, YAML, and pre-aggregated.
+
+License
+-------
+
+BOLT is licensed under the `Apache License v2.0 with LLVM
+Exceptions <https://github.com/llvm/llvm-project/blob/main/LICENSE.TXT>`__.
diff --git a/bolt/docs/OptimizingClang.md b/bolt/docs/OptimizingClang.md
index 9992b4c735c22..2b06f32fb431c 100644
--- a/bolt/docs/OptimizingClang.md
+++ b/bolt/docs/OptimizingClang.md
@@ -69,7 +69,7 @@ $ llvm-bolt $CPATH/clang-7 -o $CPATH/clang-7.bolt -b clang-7.yaml \
-split-all-cold -dyno-stats -icf=1 -use-gnu-stack
```
The output will look similar to the one below:
-```t
+```text
...
BOLT-INFO: enabling relocation mode
BOLT-INFO: 11415 functions out of 104526 simple functions (10.9%) have non-empty execution profile.
diff --git a/bolt/docs/PointerAuthDesign.md b/bolt/docs/PointerAuthDesign.md
index d10179504b7f9..22a4a691a43f6 100644
--- a/bolt/docs/PointerAuthDesign.md
+++ b/bolt/docs/PointerAuthDesign.md
@@ -18,7 +18,7 @@ Note: there are two resolutions for CFI:
### Pointer Authentication
-For more information, see the [pac-ret section of the BOLT-binary-analysis document](BinaryAnalysis.md#pac-ret-analysis).
+For more information, see the [pac-ret section of the BOLT-binary-analysis document](BinaryAnalysis.md#return-address-protection-ptrauth-pac-ret).
### DW_CFA_AARCH64_negate_ra_state
@@ -177,7 +177,7 @@ what we have before the pass, and after it.
| autiasp | negate-ra-state | signed |
| ret | | unsigned |
-##### Error handling in PointerAuthCFIAnalyzer pass:
+#### Error handling in PointerAuthCFIAnalyzer pass:
Whenever the PointerAuthCFIAnalyzer pass finds inconsistencies in the current
BinaryFunction, it marks the function as ignored using `BF.setIgnored()`. BOLT
@@ -200,7 +200,7 @@ pass:
2. whenever the state changes, it adds a PseudoInstruction that holds an
OpNegateRAState CFI.
-##### Covering newly generated instructions:
+#### Covering newly generated instructions:
Some BOLT passes can add new Instructions. In PointerAuthCFIFixup, we have
to know what RA state these have.
diff --git a/bolt/docs/conf.py b/bolt/docs/conf.py
index ededa1ccbb0be..b547c9eb62837 100644
--- a/bolt/docs/conf.py
+++ b/bolt/docs/conf.py
@@ -27,11 +27,20 @@
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ["sphinx.ext.intersphinx", "sphinx.ext.todo"]
+try:
+ import myst_parser
+
+ extensions.append("myst_parser")
+except ImportError:
+ raise
+
+myst_heading_anchors = 6
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
# The encoding of source files.
# source_encoding = 'utf-8-sig'
diff --git a/bolt/docs/index.rst b/bolt/docs/index.rst
index 13ae27d6a4c46..80d74e3b806bc 100644
--- a/bolt/docs/index.rst
+++ b/bolt/docs/index.rst
@@ -8,256 +8,34 @@ based on execution profile gathered by sampling profiler, such as Linux
discussion of its potential and current results is available in `CGO’19
paper <https://research.fb.com/publications/bolt-a-practical-binary-optimizer-for-data-centers-and-beyond/>`__.
-Input Binary Requirements
--------------------------
+User Guides
+===========
-BOLT operates on X86-64 and AArch64 ELF binaries. At the minimum, the
-binaries should have an unstripped symbol table, and, to get maximum
-performance gains, they should be linked with relocations
-(``--emit-relocs`` or ``-q`` linker flag).
+.. toctree::
+ :maxdepth: 1
-BOLT disassembles functions and reconstructs the control flow graph
-(CFG) before it runs optimizations. Since this is a nontrivial task,
-especially when indirect branches are present, we rely on certain
-heuristics to accomplish it. These heuristics have been tested on a code
-generated with Clang and GCC compilers. The main requirement for C/C++
-code is not to rely on code layout properties, such as function pointer
-deltas. Assembly code can be processed too. Requirements for it include
-a clear separation of code and data, with data objects being placed into
-data sections/segments. If indirect jumps are used for intra-function
-control transfer (e.g., jump tables), the code patterns should be
-matching those generated by Clang/GCC.
+ GettingStarted
+ OptimizingClang
+ OptimizingLinux
+ Heatmaps
-NOTE: BOLT is currently incompatible with the
-``-freorder-blocks-and-partition`` compiler option. Since GCC8 enables
-this option by default, you have to explicitly disable it by adding
-``-fno-reorder-blocks-and-partition`` flag if you are compiling with
-GCC8 or above.
+Reference
+=========
-NOTE2: DWARF v5 is the new debugging format generated by the latest LLVM
-and GCC compilers. It offers several benefits over the previous DWARF
-v4. Currently, the support for v5 is a work in progress for BOLT. While
-you will be able to optimize binaries produced by the latest compilers,
-until the support is complete, you will not be able to update the debug
-info with ``-update-debug-sections``. To temporarily work around the
-issue, we recommend compiling binaries with ``-gdwarf-4`` option that
-forces DWARF v4 output.
+.. toctree::
+ :maxdepth: 1
-PIE and .so support has been added recently. Please report bugs if you
-encounter any issues.
+ CommandLineArgumentReference
+ profiles
+ BOLTAArch64OptimizationStatus
-Installation
-------------
+Design Documentation
+====================
-Docker Image
-~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 1
-You can build and use the docker image containing BOLT using our `docker
-file <utils/docker/Dockerfile>`__. Alternatively, you can build BOLT
-manually using the steps below.
-
-Manual Build
-~~~~~~~~~~~~
-
-BOLT heavily uses LLVM libraries, and by design, it is built as one of
-LLVM tools. The build process is not much different from a regular LLVM
-build. The following instructions are assuming that you are running
-under Linux.
-
-Start with cloning LLVM repo:
-
-::
-
- > git clone https://github.com/llvm/llvm-project.git
- > mkdir build
- > cd build
- > cmake -G Ninja ../llvm-project/llvm -DLLVM_TARGETS_TO_BUILD="X86;AArch64" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_ENABLE_PROJECTS="bolt"
- > ninja bolt
-
-``llvm-bolt`` will be available under ``bin/``. Add this directory to
-your path to ensure the rest of the commands in this tutorial work.
-
-Optimizing BOLT’s Performance
------------------------------
-
-BOLT runs many internal passes in parallel. If you foresee heavy usage
-of BOLT, you can improve the processing time by linking against one of
-memory allocation libraries with good support for concurrency. E.g. to
-use jemalloc:
-
-::
-
- > sudo yum install jemalloc-devel
- > LD_PRELOAD=/usr/lib64/libjemalloc.so llvm-bolt ....
-
-Or if you rather use tcmalloc:
-
-::
-
- > sudo yum install gperftools-devel
- > LD_PRELOAD=/usr/lib64/libtcmalloc_minimal.so llvm-bolt ....
-
-Usage
------
-
-For a complete practical guide of using BOLT see `Optimizing Clang with
-BOLT <docs/OptimizingClang.md>`__.
-
-Step 0
-~~~~~~
-
-In order to allow BOLT to re-arrange functions (in addition to
-re-arranging code within functions) in your program, it needs a little
-help from the linker. Add ``--emit-relocs`` to the final link step of
-your application. You can verify the presence of relocations by checking
-for ``.rela.text`` section in the binary. BOLT will also report if it
-detects relocations while processing the binary.
-
-Step 1: Collect Profile
-~~~~~~~~~~~~~~~~~~~~~~~
-
-This step is different for different kinds of executables. If you can
-invoke your program to run on a representative input from a command
-line, then check **For Applications** section below. If your program
-typically runs as a server/service, then skip to **For Services**
-section.
-
-The version of ``perf`` command used for the following steps has to
-support ``-F brstack`` option. We recommend using ``perf`` version 4.5
-or later.
-
-For Applications
-^^^^^^^^^^^^^^^^
-
-This assumes you can run your program from a command line with a typical
-input. In this case, simply prepend the command line invocation with
-``perf``:
-
-::
-
- $ perf record -e cycles:u -j any,u -o perf.data -- <executable> <args> ...
-
-For Services
-^^^^^^^^^^^^
-
-Once you get the service deployed and warmed-up, it is time to collect
-perf data with LBR (branch information). The exact perf command to use
-will depend on the service. E.g., to collect the data for all processes
-running on the server for the next 3 minutes use:
-
-::
-
- $ perf record -e cycles:u -j any,u -a -o perf.data -- sleep 180
-
-Depending on the application, you may need more samples to be included
-with your profile. It’s hard to tell upfront what would be a sweet spot
-for your application. We recommend the profile to cover 1B instructions
-as reported by BOLT ``-dyno-stats`` option. If you need to increase the
-number of samples in the profile, you can either run the ``sleep``
-command for longer and use ``-F<N>`` option with ``perf`` to increase
-sampling frequency.
-
-Note that for profile collection we recommend using cycle events and not
-``BR_INST_RETIRED.*``. Empirically we found it to produce better
-results.
-
-If the collection of a profile with branches is not available, e.g.,
-when you run on a VM or on hardware that does not support it, then you
-can use only sample events, such as cycles. In this case, the quality of
-the profile information would not be as good, and performance gains with
-BOLT are expected to be lower.
-
-With instrumentation
-^^^^^^^^^^^^^^^^^^^^
-
-If perf record is not available to you, you may collect profile by first
-instrumenting the binary with BOLT and then running it.
-
-::
-
- llvm-bolt <executable> -instrument -o <instrumented-executable>
-
-After you run instrumented-executable with the desired workload, its
-BOLT profile should be ready for you in ``/tmp/prof.fdata`` and you can
-skip **Step 2**.
-
-Run BOLT with the ``-help`` option and check the category “BOLT
-instrumentation options” for a quick reference on instrumentation knobs.
-
-Step 2: Convert Profile to BOLT Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-NOTE: you can skip this step and feed ``perf.data`` directly to BOLT
-using experimental ``-p perf.data`` option.
-
-For this step, you will need ``perf.data`` file collected from the
-previous step and a copy of the binary that was running. The binary has
-to be either unstripped, or should have a symbol table intact (i.e.,
-running ``strip -g`` is okay).
-
-Make sure ``perf`` is in your ``PATH``, and execute ``perf2bolt``:
-
-::
-
- $ perf2bolt -p perf.data -o perf.fdata <executable>
-
-This command will aggregate branch data from ``perf.data`` and store it
-in a format that is both more compact and more resilient to binary
-modifications.
-
-If the profile was collected without brstacks, you will need to add `-ba` flag to
-the command line above.
-
-Step 3: Optimize with BOLT
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once you have ``perf.fdata`` ready, you can use it for optimizations
-with BOLT. Assuming your environment is setup to include the right path,
-execute ``llvm-bolt``:
-
-::
-
- $ llvm-bolt <executable> -o <executable>.bolt -data=perf.fdata -reorder-blocks=ext-tsp -reorder-functions=hfsort -split-functions -split-all-cold -split-eh -dyno-stats
-
-If you do need an updated debug info, then add
-``-update-debug-sections`` option to the command above. The processing
-time will be slightly longer.
-
-For a full list of options see ``-help``/``-help-hidden`` output.
-
-The input binary for this step does not have to 100% match the binary
-used for profile collection in **Step 1**. This could happen when you
-are doing active development, and the source code constantly changes,
-yet you want to benefit from profile-guided optimizations. However,
-since the binary is not precisely the same, the profile information
-could become invalid or stale, and BOLT will report the number of
-functions with a stale profile. The higher the number, the less
-performance improvement should be expected. Thus, it is crucial to
-update ``.fdata`` for release branches.
-
-Multiple Profiles
------------------
-
-Suppose your application can run in different modes, and you can
-generate multiple profiles for each one of them. To generate a single
-binary that can benefit all modes (assuming the profiles don’t
-contradict each other) you can use ``merge-fdata`` tool:
-
-::
-
- $ merge-fdata *.fdata > combined.fdata
-
-Use ``combined.fdata`` for **Step 3** above to generate a universally
-optimized binary.
-
-Profile Formats
----------------
-
-See `Profile Formats <profiles.md>`__ for comprehensive documentation of all
-profile formats accepted by BOLT: perf.data, fdata, YAML, and pre-aggregated.
-
-License
--------
-
-BOLT is licensed under the `Apache License v2.0 with LLVM
-Exceptions <./LICENSE.TXT>`__.
+ BAT
+ BinaryAnalysis
+ PointerAuthDesign
+ RuntimeLibrary
More information about the llvm-commits
mailing list