intel · bb-sycl · Jul 20, 2026 · Jul 11, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/.ci/compute_projects.py b/.ci/compute_projects.py
@@ -72,7 +72,10 @@
 # This mapping describes runtimes that should be enabled for a specific project,
 # but not necessarily run for testing. The only case of this currently is lldb
 # which needs some runtimes enabled for tests.
-DEPENDENT_RUNTIMES_TO_BUILD = {"lldb": {"libcxx", "libcxxabi", "libunwind"}}
+DEPENDENT_RUNTIMES_TO_BUILD = {
+    "flang": {"openmp"},
+    "lldb": {"libcxx", "libcxxabi", "libunwind", "compiler-rt"},
+}
 
 # This mapping describes runtimes that should be tested when the key project is
 # touched.

diff --git a/.ci/compute_projects_test.py b/.ci/compute_projects_test.py
@@ -214,9 +214,9 @@ def test_flang(self):
         env_variables = compute_projects.get_env_variables(
             ["flang/CMakeLists.txt"], "Linux"
         )
-        self.assertEqual(env_variables["projects_to_build"], "clang;flang;llvm")
+        self.assertEqual(env_variables["projects_to_build"], "clang;flang;lld;llvm")
         self.assertEqual(env_variables["project_check_targets"], "check-flang")
-        self.assertEqual(env_variables["runtimes_to_build"], "flang-rt")
+        self.assertEqual(env_variables["runtimes_to_build"], "flang-rt;openmp")
         self.assertEqual(env_variables["runtimes_check_targets"], "check-flang-rt")
         self.assertEqual(env_variables["runtimes_check_targets_needs_reconfig"], "")
         self.assertEqual(env_variables["enable_cir"], "OFF")

diff --git a/bolt/CMakeLists.txt b/bolt/CMakeLists.txt
@@ -1,4 +1,11 @@
 cmake_minimum_required(VERSION 3.20.0)
+if("${CMAKE_VERSION}" VERSION_LESS "3.31.0")
+  message(WARNING
+    "Your CMake version is ${CMAKE_VERSION}. Starting with LLVM 24, the "
+    "minimum version of CMake required to build LLVM will become 3.31.0, and "
+    "using an older CMake will become an error. Please upgrade your CMake to "
+    "at least 3.31.0 now to avoid issues in the future.")
+endif()
 
 set(LLVM_SUBPROJECT_TITLE "BOLT")
 

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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.