[llvm] [docs] Finish MyST migration for BOLT docs (PR #210199)
Reid Kleckner via llvm-commits
llvm-commits at lists.llvm.org
Thu Jul 16 16:55:07 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/210199
>From 4a910ea056048b33fd88f3dd0d87ba50d88e58c6 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Thu, 16 Jul 2026 22:00:07 +0000
Subject: [PATCH 1/2] [docs] Convert selected rst docs with rst2myst
---
bolt/docs/BOLTAArch64OptimizationStatus.md | 39 +++--
bolt/docs/GettingStarted.md | 190 ++++++++++-----------
bolt/docs/index.md | 63 +++----
3 files changed, 141 insertions(+), 151 deletions(-)
diff --git a/bolt/docs/BOLTAArch64OptimizationStatus.md b/bolt/docs/BOLTAArch64OptimizationStatus.md
index df2fc21fa2c7c..a340615a0f18b 100644
--- a/bolt/docs/BOLTAArch64OptimizationStatus.md
+++ b/bolt/docs/BOLTAArch64OptimizationStatus.md
@@ -1,22 +1,20 @@
-=====================================
-AArch64 Optimization and Flags Status
-=====================================
+# AArch64 Optimization and Flags Status
-Overview
---------
+## Overview
This page summarizes default-off BOLT optimization flags that users may
explicitly enable when optimizing AArch64 binaries.
BOLT is to be used with binaries linked with
-relocations (``--emit-relocs`` or ``-Wl,-q``) and representative profile data.
+relocations (`--emit-relocs` or `-Wl,-q`) and representative profile data.
+
+## Main Code-Layout Optimizations
-Main Code-Layout Optimizations
-------------------------------
The following code-layout optimizations are typically the first options to
consider when optimizing AArch64 binaries with representative profile data.
They typically provide the largest performance gains among BOLT optimizations.
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: 34 42
@@ -35,11 +33,13 @@ They typically provide the largest performance gains among BOLT optimizations.
| ``--split-eh``
- Split hot and cold code
+```
+
+## Other Supported Optimizations
-Other Supported Optimizations
------------------------------
The following optimizations are also supported for AArch64.
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: 34 42
@@ -63,13 +63,15 @@ The following optimizations are also supported for AArch64.
- Inline functions
* - ``--icf=safe|all``
- Fold identical functions
+```
+
+## Supported Flags With Limitations
-Supported Flags With Limitations
---------------------------------
The following flags are implemented for AArch64, but require specific runtime
or option conditions. Enabling them without the required conditions may report
an error or perform no transformation.
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: 30 28 44
@@ -94,16 +96,17 @@ an error or perform no transformation.
* - ``--split-strategy=cdsplit``
- Split functions using cache-directed splitting
- Requires ``--compact-code-model`` on AArch64.
+```
-Unsupported Flags
------------------
+## Unsupported Flags
-The following flags are not available for AArch64. ``Not applicable to
-AArch64`` means the optimization targets architectural features or mechanisms
-that do not apply to AArch64. ``Not implemented for AArch64`` means the
+The following flags are not available for AArch64. `Not applicable to
+AArch64` means the optimization targets architectural features or mechanisms
+that do not apply to AArch64. `Not implemented for AArch64` means the
optimization could be relevant, but is not currently implemented for this
target.
+```{eval-rst}
.. list-table::
:header-rows: 1
:widths: 30 28 42
@@ -143,3 +146,5 @@ target.
* - ``--insert-retpolines``
- Insert retpolines
- Not applicable to AArch64.
+```
+
diff --git a/bolt/docs/GettingStarted.md b/bolt/docs/GettingStarted.md
index ab410b3a6ff04..0716bec4280ff 100644
--- a/bolt/docs/GettingStarted.md
+++ b/bolt/docs/GettingStarted.md
@@ -1,13 +1,11 @@
-Getting Started with BOLT
-=========================
+# Getting Started with BOLT
-Input Binary Requirements
--------------------------
+## 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).
+(`--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,
@@ -22,9 +20,9 @@ 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
+`-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
+`-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
@@ -32,25 +30,22 @@ 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
+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
-------------
+## Installation
-Docker Image
-~~~~~~~~~~~~
+### 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>`__.
+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
-~~~~~~~~~~~~
+### 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
@@ -59,54 +54,50 @@ 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
+```
- > 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
+`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
------------------------------
+## 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 ....
+```
+> 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 ....
+```
+> sudo yum install gperftools-devel
+> LD_PRELOAD=/usr/lib64/libtcmalloc_minimal.so llvm-bolt ....
+```
-Usage
------
+## Usage
-For a complete practical guide of using BOLT see :doc:`OptimizingClang`.
+For a complete practical guide of using BOLT see {doc}`OptimizingClang`.
-Step 0
-~~~~~~
+### 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
+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
+for `.rela.text` section in the binary. BOLT will also report if it
detects relocations while processing the binary.
-Step 1: Collect Profile
-~~~~~~~~~~~~~~~~~~~~~~~
+### 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
@@ -114,43 +105,41 @@ 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
+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
-^^^^^^^^^^^^^^^^
+#### 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`:
-::
+```
+$ perf record -e cycles:u -j any,u -o perf.data -- <executable> <args> ...
+```
- $ perf record -e cycles:u -j any,u -o perf.data -- <executable> <args> ...
-
-For Services
-^^^^^^^^^^^^
+#### 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
+```
+$ 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
+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
+`BR_INST_RETIRED.*`. Empirically we found it to produce better
results.
If the collection of a profile with branches is not available, e.g.,
@@ -159,63 +148,60 @@ 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
-^^^^^^^^^^^^^^^^^^^^
+#### 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>
+```
+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
+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
+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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### 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.
+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
+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``:
+running `strip -g` is okay).
-::
+Make sure `perf` is in your `PATH`, and execute `perf2bolt`:
- $ perf2bolt -p perf.data -o perf.fdata <executable>
+```
+$ perf2bolt -p perf.data -o perf.fdata <executable>
+```
-This command will aggregate branch data from ``perf.data`` and store it
+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
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Step 3: Optimize with BOLT
-Once you have ``perf.fdata`` ready, you can use it for optimizations
+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``:
-
-::
+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
+```
+$ 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
+`-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.
+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
@@ -225,31 +211,29 @@ 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.
+update `.fdata` for release branches.
-Multiple Profiles
------------------
+## 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:
+contradict each other) you can use `merge-fdata` tool:
-::
+```
+$ merge-fdata *.fdata > combined.fdata
+```
- $ merge-fdata *.fdata > combined.fdata
-
-Use ``combined.fdata`` for **Step 3** above to generate a universally
+Use `combined.fdata` for **Step 3** above to generate a universally
optimized binary.
-Profile Formats
----------------
+## Profile Formats
-See :doc:`profiles` for comprehensive documentation of all profile formats
+See {doc}`profiles` for comprehensive documentation of all profile formats
accepted by BOLT: perf.data, fdata, YAML, and pre-aggregated.
-License
--------
+## License
+
+BOLT is licensed under the [Apache License v2.0 with LLVM
+Exceptions](https://github.com/llvm/llvm-project/blob/main/LICENSE.TXT).
-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/index.md b/bolt/docs/index.md
index bbbca8130bea0..e39892df38523 100644
--- a/bolt/docs/index.md
+++ b/bolt/docs/index.md
@@ -1,46 +1,47 @@
-BOLT
-====
+# BOLT
-.. toctree::
- :hidden:
+```{toctree}
+:hidden: true
- BOLTAArch64OptimizationStatus
+BOLTAArch64OptimizationStatus
+```
BOLT is a post-link optimizer developed to speed up large applications.
It achieves the improvements by optimizing application’s code layout
based on execution profile gathered by sampling profiler, such as Linux
-``perf`` tool. An overview of the ideas implemented in BOLT along with a
-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/>`__.
+`perf` tool. An overview of the ideas implemented in BOLT along with a
+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/).
-User Guides
-===========
+# User Guides
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
- GettingStarted
- OptimizingClang
- OptimizingLinux
- Heatmaps
+GettingStarted
+OptimizingClang
+OptimizingLinux
+Heatmaps
+```
-Reference
-=========
+# Reference
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
- CommandLineArgumentReference
- profiles
- BOLTAArch64OptimizationStatus
+CommandLineArgumentReference
+profiles
+BOLTAArch64OptimizationStatus
+```
-Design Documentation
-====================
+# Design Documentation
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+
+BAT
+BinaryAnalysis
+PointerAuthDesign
+RuntimeLibrary
+```
- BAT
- BinaryAnalysis
- PointerAuthDesign
- RuntimeLibrary
>From 6f20715f39e3aeb18c1613a5af6cd7b8143abda8 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Thu, 16 Jul 2026 22:00:58 +0000
Subject: [PATCH 2/2] [docs] Finish MyST migration for selected docs
---
bolt/docs/BOLTAArch64OptimizationStatus.md | 221 ++++++++++-----------
bolt/docs/GettingStarted.md | 19 +-
2 files changed, 117 insertions(+), 123 deletions(-)
diff --git a/bolt/docs/BOLTAArch64OptimizationStatus.md b/bolt/docs/BOLTAArch64OptimizationStatus.md
index a340615a0f18b..8567e48afb42e 100644
--- a/bolt/docs/BOLTAArch64OptimizationStatus.md
+++ b/bolt/docs/BOLTAArch64OptimizationStatus.md
@@ -14,56 +14,53 @@ The following code-layout optimizations are typically the first options to
consider when optimizing AArch64 binaries with representative profile data.
They typically provide the largest performance gains among BOLT optimizations.
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: 34 42
- :align: left
-
- * - Flag
- - Optimization
- * - | ``--reorder-functions=exec-count|hfsort|cdsort|pettis-hansen|random|user``
- | ``--function-order=<file>``
- - Reorder functions
- * - ``--reorder-blocks=normal|ext-tsp|cache|branch-predictor|reverse|cluster-shuffle``
- - Reorder basic blocks
- * - | ``--split-functions``
- | ``--split-strategy=profile2|random2|randomN|all``
- | ``--split-all-cold``
- | ``--split-eh``
- - Split hot and cold code
-
-```
+:::{list-table}
+:header-rows: 1
+:widths: 34 42
+:align: left
+
+* - Flag
+ - Optimization
+* - `--reorder-functions=exec-count|hfsort|cdsort|pettis-hansen|random|user`
+ `--function-order=<file>`
+ - Reorder functions
+* - `--reorder-blocks=normal|ext-tsp|cache|branch-predictor|reverse|cluster-shuffle`
+ - Reorder basic blocks
+* - `--split-functions`
+ `--split-strategy=profile2|random2|randomN|all`
+ `--split-all-cold`
+ `--split-eh`
+ - Split hot and cold code
+:::
## Other Supported Optimizations
The following optimizations are also supported for AArch64.
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: 34 42
- :align: left
-
- * - Flag
- - Optimization
- * - | ``--align-blocks``
- | ``--block-alignment=<uint>``
- - Align basic blocks
- * - ``--tail-duplication=aggressive|moderate|cache``
- - Duplicate branch tails
- * - ``--peepholes=double-jumps|tailcall-traps|useless-branches|all``
- - Run peephole optimizations
- * - | ``--inline-all``
- | ``--inline-small-functions``
- | Related options:
- | ``--inline-ap``
- | ``--inline-limit=<uint>``
- | ``--inline-small-functions-bytes=<uint>``
- - Inline functions
- * - ``--icf=safe|all``
- - Fold identical functions
-```
+:::{list-table}
+:header-rows: 1
+:widths: 34 42
+:align: left
+
+* - Flag
+ - Optimization
+* - `--align-blocks`
+ `--block-alignment=<uint>`
+ - Align basic blocks
+* - `--tail-duplication=aggressive|moderate|cache`
+ - Duplicate branch tails
+* - `--peepholes=double-jumps|tailcall-traps|useless-branches|all`
+ - Run peephole optimizations
+* - `--inline-all`
+ `--inline-small-functions`
+ Related options:
+ `--inline-ap`
+ `--inline-limit=<uint>`
+ `--inline-small-functions-bytes=<uint>`
+ - Inline functions
+* - `--icf=safe|all`
+ - Fold identical functions
+:::
## Supported Flags With Limitations
@@ -71,32 +68,31 @@ The following flags are implemented for AArch64, but require specific runtime
or option conditions. Enabling them without the required conditions may report
an error or perform no transformation.
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: 30 28 44
- :align: left
-
- * - Flag
- - Optimization
- - Notes
- * - ``--inline-memcpy``
- - Inline fixed-size ``memcpy`` calls
- - Only applies when the copy size is a known constant; AArch64 skips sizes over 64 bytes.
- * - ``--plt=hot|all``
- - Optimize PLT calls
- - Requires immediate binding. If BOLT cannot update the binary, relink with ``-znow``.
- * - ``--hugify``
- - Place hot code on huge pages
- - Applies to binaries with a recognized entry point; skipped when ``--instrument`` is used.
- * - | ``--reorder-data=<section1,section2,...>``
- | ``--reorder-data-algo=count|funcs``
- - Reorder data sections
- - ``move``, ``split`` and ``aggressive`` disable data reordering.
- * - ``--split-strategy=cdsplit``
- - Split functions using cache-directed splitting
- - Requires ``--compact-code-model`` on AArch64.
-```
+:::{list-table}
+:header-rows: 1
+:widths: 30 28 44
+:align: left
+
+* - Flag
+ - Optimization
+ - Notes
+* - `--inline-memcpy`
+ - Inline fixed-size `memcpy` calls
+ - Only applies when the copy size is a known constant; AArch64 skips sizes over 64 bytes.
+* - `--plt=hot|all`
+ - Optimize PLT calls
+ - Requires immediate binding. If BOLT cannot update the binary, relink with `-znow`.
+* - `--hugify`
+ - Place hot code on huge pages
+ - Applies to binaries with a recognized entry point; skipped when `--instrument` is used.
+* - `--reorder-data=<section1,section2,...>`
+ `--reorder-data-algo=count|funcs`
+ - Reorder data sections
+ - `move`, `split` and `aggressive` disable data reordering.
+* - `--split-strategy=cdsplit`
+ - Split functions using cache-directed splitting
+ - Requires `--compact-code-model` on AArch64.
+:::
## Unsupported Flags
@@ -106,45 +102,44 @@ that do not apply to AArch64. `Not implemented for AArch64` means the
optimization could be relevant, but is not currently implemented for this
target.
-```{eval-rst}
-.. list-table::
- :header-rows: 1
- :widths: 30 28 42
- :align: left
-
- * - Flag
- - Optimization
- - Notes
- * - ``--jt-footprint-reduction``
- - Reduce jump-table footprint
- - Not implemented for AArch64.
- * - ``--three-way-branch``
- - Reorder three-way branches
- - Not implemented for AArch64.
- * - ``--simplify-rodata-loads``
- - Replace read-only data loads with constants
- - Not implemented for AArch64.
- * - ``--frame-opt=hot|all``
- - Optimize stack-frame accesses
- - Not implemented for AArch64.
- * - ``--indirect-call-promotion=calls|jump-tables|all``
- - Promote indirect calls
- - Not implemented for AArch64.
- * - ``--memcpy1-spec=<func1,func2:cs1:cs2,...>``
- - Specialize one-byte ``memcpy`` calls
- - Not implemented for AArch64.
- * - ``--reg-reassign``
- - Reassign registers to reduce encoding size
- - Not applicable to AArch64.
- * - ``--cmov-conversion``
- - Convert branches to conditional moves
- - Not applicable to AArch64.
- * - | ``--stoke``
- | ``--stoke-out``
- - Emit STOKE optimization data
- - Not applicable to AArch64.
- * - ``--insert-retpolines``
- - Insert retpolines
- - Not applicable to AArch64.
-```
-
+:::{list-table}
+:header-rows: 1
+:widths: 30 28 42
+:align: left
+
+* - Flag
+ - Optimization
+ - Notes
+* - `--jt-footprint-reduction`
+ - Reduce jump-table footprint
+ - Not implemented for AArch64.
+* - `--three-way-branch`
+ - Reorder three-way branches
+ - Not implemented for AArch64.
+* - `--simplify-rodata-loads`
+ - Replace read-only data loads with constants
+ - Not implemented for AArch64.
+* - `--frame-opt=hot|all`
+ - Optimize stack-frame accesses
+ - Not implemented for AArch64.
+* - `--indirect-call-promotion=calls|jump-tables|all`
+ - Promote indirect calls
+ - Not implemented for AArch64.
+* - `--memcpy1-spec=<func1,func2:cs1:cs2,...>`
+ - Specialize one-byte `memcpy` calls
+ - Not implemented for AArch64.
+* - `--reg-reassign`
+ - Reassign registers to reduce encoding size
+ - Not applicable to AArch64.
+* - `--cmov-conversion`
+ - Convert branches to conditional moves
+ - Not applicable to AArch64.
+* - `--stoke`
+
+ `--stoke-out`
+ - Emit STOKE optimization data
+ - Not applicable to AArch64.
+* - `--insert-retpolines`
+ - Insert retpolines
+ - Not applicable to AArch64.
+:::
diff --git a/bolt/docs/GettingStarted.md b/bolt/docs/GettingStarted.md
index 0716bec4280ff..95d10880a50c1 100644
--- a/bolt/docs/GettingStarted.md
+++ b/bolt/docs/GettingStarted.md
@@ -54,7 +54,7 @@ under Linux.
Start with cloning LLVM repo:
-```
+```console
> git clone https://github.com/llvm/llvm-project.git
> mkdir build
> cd build
@@ -72,14 +72,14 @@ 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:
-```
+```console
> sudo yum install jemalloc-devel
> LD_PRELOAD=/usr/lib64/libjemalloc.so llvm-bolt ....
```
Or if you rather use tcmalloc:
-```
+```console
> sudo yum install gperftools-devel
> LD_PRELOAD=/usr/lib64/libtcmalloc_minimal.so llvm-bolt ....
```
@@ -115,7 +115,7 @@ 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`:
-```
+```console
$ perf record -e cycles:u -j any,u -o perf.data -- <executable> <args> ...
```
@@ -126,7 +126,7 @@ 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:
-```
+```console
$ perf record -e cycles:u -j any,u -a -o perf.data -- sleep 180
```
@@ -153,7 +153,7 @@ BOLT are expected to be lower.
If perf record is not available to you, you may collect profile by first
instrumenting the binary with BOLT and then running it.
-```
+```console
llvm-bolt <executable> -instrument -o <instrumented-executable>
```
@@ -176,7 +176,7 @@ running `strip -g` is okay).
Make sure `perf` is in your `PATH`, and execute `perf2bolt`:
-```
+```console
$ perf2bolt -p perf.data -o perf.fdata <executable>
```
@@ -193,7 +193,7 @@ 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`:
-```
+```console
$ 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
```
@@ -220,7 +220,7 @@ 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:
-```
+```console
$ merge-fdata *.fdata > combined.fdata
```
@@ -236,4 +236,3 @@ accepted by BOLT: perf.data, fdata, YAML, and pre-aggregated.
BOLT is licensed under the [Apache License v2.0 with LLVM
Exceptions](https://github.com/llvm/llvm-project/blob/main/LICENSE.TXT).
-
More information about the llvm-commits
mailing list