[llvm] [AArch64][BOLT] Document AArch64 optimization flag support (PR #198282)
Amina Chabane via llvm-commits
llvm-commits at lists.llvm.org
Mon Jun 1 08:08:41 PDT 2026
https://github.com/Amichaxx updated https://github.com/llvm/llvm-project/pull/198282
>From c08b11fda24ada14e52b440691fdcef714c8e0aa Mon Sep 17 00:00:00 2001
From: Amichaxx <amina.chabane at arm.com>
Date: Mon, 18 May 2026 12:05:04 +0000
Subject: [PATCH 1/3] [AArch64][BOLT] Document AArch64's gaps on BOLT
BOLTAArch64OptimizationStatus.rst aims to document default-off, user-enabled passes
and their status (supported/unsupported) on AArch64.
``--simplify-rodata-loads`` has a patch in review, so I have documented
its current status.
---
bolt/docs/BOLTAArch64OptimizationStatus.rst | 125 ++++++++++++++++++++
1 file changed, 125 insertions(+)
create mode 100644 bolt/docs/BOLTAArch64OptimizationStatus.rst
diff --git a/bolt/docs/BOLTAArch64OptimizationStatus.rst b/bolt/docs/BOLTAArch64OptimizationStatus.rst
new file mode 100644
index 0000000000000..3ceec729229db
--- /dev/null
+++ b/bolt/docs/BOLTAArch64OptimizationStatus.rst
@@ -0,0 +1,125 @@
+=====================================
+AArch64 Optimization and Flags Status
+=====================================
+
+Overview
+--------
+
+This page summarizes default-off BOLT optimization flags that users may
+explicitly enable when optimizing AArch64 binaries.
+
+Ideally, BOLT is to be used with binaries linked with
+relocations (``--emit-relocs`` or ``-Wl,-q``) and representative profile data.
+
+Supported Flags
+---------------
+The following flags are supported for AArch64.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 34 42
+
+ * - Flag
+ - Optimization
+ * - ``--tail-duplication=aggressive|moderate|cache``
+ - Duplicate branch tails
+ * - ``--peepholes=double-jumps|tailcall-traps|useless-branches|all``
+ - Run peephole optimizations
+ * - ``--reorder-blocks=normal|ext-tsp|cache|branch-predictor|reverse|cluster-shuffle``
+ - Reorder basic blocks
+ * - | ``--align-blocks``
+ | ``--block-alignment=<uint>``
+ - Align basic blocks
+ * - | ``--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
+ * - | ``--reorder-functions=exec-count|hfsort|cdsort|pettis-hansen|random|user``
+ | ``--function-order=<file>``
+ - Reorder functions
+
+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.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 28 44
+
+ * - 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-functions``
+ | ``--split-strategy=profile2|cdsplit|random2|randomN|all``
+ | ``--split-all-cold``
+ | ``--split-eh``
+ - Split hot and cold code
+ - ``--split-strategy=cdsplit`` requires ``--compact-code-model`` on AArch64.
+
+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
+optimization could be relevant, but is not currently implemented for this
+target.
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 28 42
+
+ * - 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.
+ * - ``--cmov-conversion``
+ - Convert branches to conditional moves
+ - Not applicable to 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.
+ * - ``--reg-reassign``
+ - Reassign registers to reduce encoding size
+ - Not applicable to AArch64.
+ * - ``--simplify-rodata-loads``
+ - Replace read-only data loads with constants
+ - Not implemented for AArch64.
+ * - | ``--stoke``
+ | ``--stoke-out``
+ - Emit STOKE optimization data
+ - Not applicable to AArch64.
+ * - ``--insert-retpolines``
+ - Insert retpolines
+ - Not applicable to AArch64.
+ * - ``--memcpy1-spec=<func1,func2:cs1:cs2,...>``
+ - Specialize one-byte ``memcpy`` calls
+ - Not implemented for AArch64.
>From a31779a8af4f8802981b5f3d91448874114e0f0e Mon Sep 17 00:00:00 2001
From: Amichaxx <amina.chabane at arm.com>
Date: Mon, 18 May 2026 15:21:23 +0000
Subject: [PATCH 2/3] Add toctree and fix weird formatting in rst
---
bolt/docs/BOLTAArch64OptimizationStatus.rst | 3 +++
bolt/docs/index.rst | 11 +++++++++++
2 files changed, 14 insertions(+)
diff --git a/bolt/docs/BOLTAArch64OptimizationStatus.rst b/bolt/docs/BOLTAArch64OptimizationStatus.rst
index 3ceec729229db..989ec84661cba 100644
--- a/bolt/docs/BOLTAArch64OptimizationStatus.rst
+++ b/bolt/docs/BOLTAArch64OptimizationStatus.rst
@@ -18,6 +18,7 @@ The following flags are supported for AArch64.
.. list-table::
:header-rows: 1
:widths: 34 42
+ :align: left
* - Flag
- Optimization
@@ -52,6 +53,7 @@ an error or perform no transformation.
.. list-table::
:header-rows: 1
:widths: 30 28 44
+ :align: left
* - Flag
- Optimization
@@ -88,6 +90,7 @@ target.
.. list-table::
:header-rows: 1
:widths: 30 28 42
+ :align: left
* - Flag
- Optimization
diff --git a/bolt/docs/index.rst b/bolt/docs/index.rst
index 13ae27d6a4c46..7fc138e0d29fa 100644
--- a/bolt/docs/index.rst
+++ b/bolt/docs/index.rst
@@ -256,6 +256,17 @@ Profile Formats
See `Profile Formats <profiles.md>`__ for comprehensive documentation of all
profile formats accepted by BOLT: perf.data, fdata, YAML, and pre-aggregated.
+Additional Documentation
+------------------------
+
+.. toctree::
+ :hidden:
+
+ BOLTAArch64OptimizationStatus
+
+:doc:`BOLTAArch64OptimizationStatus`
+ Status of default-off BOLT optimization flags on AArch64.
+
License
-------
>From 57f58c55413bd15e520aac0d6f213cc41728ef15 Mon Sep 17 00:00:00 2001
From: Amichaxx <amina.chabane at arm.com>
Date: Mon, 1 Jun 2026 15:03:32 +0000
Subject: [PATCH 3/3] Reordered sections, split up --split-strategy, fixed up
wording
---
bolt/docs/BOLTAArch64OptimizationStatus.rst | 48 +++++++++++----------
1 file changed, 25 insertions(+), 23 deletions(-)
diff --git a/bolt/docs/BOLTAArch64OptimizationStatus.rst b/bolt/docs/BOLTAArch64OptimizationStatus.rst
index 989ec84661cba..bb000f57c75a8 100644
--- a/bolt/docs/BOLTAArch64OptimizationStatus.rst
+++ b/bolt/docs/BOLTAArch64OptimizationStatus.rst
@@ -8,7 +8,7 @@ Overview
This page summarizes default-off BOLT optimization flags that users may
explicitly enable when optimizing AArch64 binaries.
-Ideally, BOLT is to be used with binaries linked with
+BOLT is to be used with binaries linked with
relocations (``--emit-relocs`` or ``-Wl,-q``) and representative profile data.
Supported Flags
@@ -22,15 +22,23 @@ The following flags are supported for AArch64.
* - Flag
- Optimization
- * - ``--tail-duplication=aggressive|moderate|cache``
- - Duplicate branch tails
- * - ``--peepholes=double-jumps|tailcall-traps|useless-branches|all``
- - Run peephole optimizations
+ * - | ``--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
* - | ``--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:
@@ -40,9 +48,6 @@ The following flags are supported for AArch64.
- Inline functions
* - ``--icf=safe|all``
- Fold identical functions
- * - | ``--reorder-functions=exec-count|hfsort|cdsort|pettis-hansen|random|user``
- | ``--function-order=<file>``
- - Reorder functions
Supported Flags With Limitations
--------------------------------
@@ -71,12 +76,9 @@ an error or perform no transformation.
| ``--reorder-data-algo=count|funcs``
- Reorder data sections
- ``move``, ``split`` and ``aggressive`` disable data reordering.
- * - | ``--split-functions``
- | ``--split-strategy=profile2|cdsplit|random2|randomN|all``
- | ``--split-all-cold``
- | ``--split-eh``
- - Split hot and cold code
- - ``--split-strategy=cdsplit`` requires ``--compact-code-model`` on AArch64.
+ * - ``--split-strategy=cdsplit``
+ - Split functions using cache-directed splitting
+ - Requires ``--compact-code-model`` on AArch64.
Unsupported Flags
-----------------
@@ -101,21 +103,24 @@ target.
* - ``--three-way-branch``
- Reorder three-way branches
- Not implemented for AArch64.
- * - ``--cmov-conversion``
- - Convert branches to conditional moves
- - Not applicable to 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.
- * - ``--simplify-rodata-loads``
- - Replace read-only data loads with constants
- - Not implemented for AArch64.
+ * - ``--cmov-conversion``
+ - Convert branches to conditional moves
+ - Not applicable to AArch64.
* - | ``--stoke``
| ``--stoke-out``
- Emit STOKE optimization data
@@ -123,6 +128,3 @@ target.
* - ``--insert-retpolines``
- Insert retpolines
- Not applicable to AArch64.
- * - ``--memcpy1-spec=<func1,func2:cs1:cs2,...>``
- - Specialize one-byte ``memcpy`` calls
- - Not implemented for AArch64.
More information about the llvm-commits
mailing list