28 KiB
BOLT - a post-link optimizer developed to speed up large applications
SYNOPSIS
llvm-bolt <executable> [-o outputfile] <executable>.bolt [-data=perf.fdata] [options]
OPTIONS
Generic options:
-
-hAlias for --help
-
--helpDisplay available options (--help-hidden for more)
-
--help-hiddenDisplay all available options
-
--help-listDisplay list of available options (--help-list-hidden for more)
-
--help-list-hiddenDisplay list of all available options
-
--versionDisplay the version of this program
Output options:
-
--bolt-infoWrite bolt info section in the output binary
-
-o <string>output file
-
-w <string>Save recorded profile to a file
BOLT generic options:
-
--align-text=<uint>Alignment of .text section
-
--allow-strippedAllow processing of stripped binaries
-
--alt-inst-feature-size=<uint>Size of feature field in .altinstructions
-
--alt-inst-has-padlenSpecify that .altinstructions has padlen field
-
--asm-dump[=<dump folder>]Dump function into assembly
-
-bAlias for -data
-
--bolt-id=<string>Add any string to tag this execution in the output binary via bolt info section
-
--break-funcs=<func1,func2,func3,...>List of functions to core dump on (debugging)
-
--check-encodingPerform verification of LLVM instruction encoding/decoding. Every instruction in the input is decoded and re-encoded. If the resulting bytes do not match the input, a warning message is printed.
-
--comp-dir-override=<string>Overrides DW_AT_comp_dir, and provides an alterantive base location, which is used with DW_AT_dwo_name to construct a path to *.dwo files.
-
--create-debug-names-sectionCreates .debug_names section, if the input binary doesn't have it already, for DWARF5 CU/TUs.
-
--cu-processing-batch-size=<uint>Specifies the size of batches for processing CUs. Higher number has better performance, but more memory usage. Default value is 1.
-
--data=<string>data file
-
--data2=<string>data file
-
--debug-skeleton-cuPrints out offsets for abbrev and debug_info of Skeleton CUs that get patched.
-
--deterministic-debuginfoDisables parallel execution of tasks that may produce nondeterministic debug info
-
--dot-tooltip-codeAdd basic block instructions as tool tips on nodes
-
--dump-alt-instructionsDump Linux alternative instructions info
-
--dump-cg=<string>Dump callgraph to the given file
-
--dump-dataDump parsed bolt data for debugging
-
--dump-dot-allDump function CFGs to graphviz format after each stage;enable '-print-loops' for color-coded blocks
-
--dump-linux-exceptionsDump Linux kernel exception table
-
--dump-orcDump raw ORC unwind information (sorted)
-
--dump-para-sitesDump Linux kernel paravitual patch sites
-
--dump-pci-fixupsDump Linux kernel PCI fixup table
-
--dump-smp-locksDump Linux kernel SMP locks
-
--dump-static-callsDump Linux kernel static calls
-
--dump-static-keysDump Linux kernel static keys jump table
-
--dwarf-output-path=<string>Path to where .dwo files or dwp file will be written out to.
-
--dwp=<string>Path and name to DWP file.
-
--dyno-statsPrint execution info based on profile
-
--dyno-stats-allPrint dyno stats after each stage
-
--dyno-stats-scale=<uint>Scale to be applied while reporting dyno stats
-
--enable-batWrite BOLT Address Translation tables
-
--force-data-relocationsForce relocations to data sections to always be processed
-
--force-patchForce patching of original entry points
-
--funcs=<func1,func2,func3,...>Limit optimizations to functions from the list
-
--funcs-file=<string>File with list of functions to optimize
-
--funcs-file-no-regex=<string>File with list of functions to optimize (non-regex)
-
--funcs-no-regex=<func1,func2,func3,...>Limit optimizations to functions from the list (non-regex)
-
--hot-dataHot data symbols support (relocation mode)
-
--hot-functions-at-endIf reorder-functions is used, order functions putting hottest last
-
--hot-textGenerate hot text symbols. Apply this option to a precompiled binary that manually calls into hugify, such that at runtime hugify call will put hot code into 2M pages. This requires relocation.
-
--hot-text-move-sections=<sec1,sec2,sec3,...>List of sections containing functions used for hugifying hot text. BOLT makes sure these functions are not placed on the same page as the hot text. (default='.stub,.mover').
-
--insert-retpolinesRun retpoline insertion pass
-
--keep-arangesKeep or generate .debug_aranges section if .gdb_index is written
-
--keep-tmpPreserve intermediate .o file
-
--liteSkip processing of cold functions
-
--log-file=<string>Redirect journaling to a file instead of stdout/stderr
-
--long-jump-labelsAlways use long jumps/nops for Linux kernel static keys
-
--max-data-relocations=<uint>Maximum number of data relocations to process
-
--max-funcs=<uint>Maximum number of functions to process
-
--no-huge-pagesUse regular size pages for code alignment
-
--no-threadsDisable multithreading
-
--pad-funcs=<func1:pad1,func2:pad2,func3:pad3,...>List of functions to pad with amount of bytes
-
--profile-format=<value>Format to dump profile output in aggregation mode, default is fdata
fdata: offset-based plaintext formatyaml: dense YAML representation
-
--r11-availability=<value>Determine the availability of r11 before indirect branches
never: r11 not availablealways: r11 available before calls and jumpsabi: r11 available before calls but not before jumps
-
--relocsUse relocations in the binary (default=autodetect)
-
--remove-symtabRemove .symtab section
-
--reorder-skip-symbols=<symbol1,symbol2,symbol3,...>List of symbol names that cannot be reordered
-
--reorder-symbols=<symbol1,symbol2,symbol3,...>List of symbol names that can be reordered
-
--retpoline-lfenceDetermine if lfence instruction should exist in the retpoline
-
--skip-funcs=<func1,func2,func3,...>List of functions to skip
-
--skip-funcs-file=<string>File with list of functions to skip
-
--strictTrust the input to be from a well-formed source
-
--tasks-per-thread=<uint>Number of tasks to be created per thread
-
--terminal-trapAssume that execution stops at trap instruction
-
--thread-count=<uint>Number of threads
-
--top-called-limit=<uint>Maximum number of functions to print in top called functions section
-
--trap-avx512In relocation mode trap upon entry to any function that uses AVX-512 instructions
-
--trap-old-codeInsert traps in old function bodies (relocation mode)
-
--update-debug-sectionsUpdate DWARF debug sections of the executable
-
--use-gnu-stackUse GNU_STACK program header for new segment (workaround for issues with strip/objcopy)
-
--use-old-textRe-use space in old .text if possible (relocation mode)
-
-v <uint>Set verbosity level for diagnostic output
-
--write-dwpOutput a single dwarf package file (dwp) instead of multiple non-relocatable dwarf object files (dwo).
BOLT optimization options:
-
--align-blocksAlign basic blocks
-
--align-blocks-min-size=<uint>Minimal size of the basic block that should be aligned
-
--align-blocks-threshold=<uint>Align only blocks with frequency larger than containing function execution frequency specified in percent. E.g. 1000 means aligning blocks that are 10 times more frequently executed than the containing function.
-
--align-functions=<uint>Align functions at a given value (relocation mode)
-
--align-functions-max-bytes=<uint>Maximum number of bytes to use to align functions
-
--assume-abiAssume the ABI is never violated
-
--block-alignment=<uint>Boundary to use for alignment of basic blocks
-
--bolt-seed=<uint>Seed for randomization
-
--cg-from-perf-dataUse perf data directly when constructing the call graph for stale functions
-
--cg-ignore-recursive-callsIgnore recursive calls when constructing the call graph
-
--cg-use-split-hot-sizeUse hot/cold data on basic blocks to determine hot sizes for call graph functions
-
--cold-threshold=<uint>Tenths of percents of main entry frequency to use as a threshold when evaluating whether a basic block is cold (0 means it is only considered cold if the block has zero samples). Default: 0
-
--elim-link-veneersRun veneer elimination pass
-
--eliminate-unreachableEliminate unreachable code
-
--equalize-bb-countsUse same count for BBs that should have equivalent count (used in non-LBR and shrink wrapping)
-
--execution-count-threshold=<uint>Perform profiling accuracy-sensitive optimizations only if function execution count >= the threshold (default: 0)
-
--fix-block-countsAdjust block counts based on outgoing branch counts
-
--fix-func-countsAdjust function counts based on basic blocks execution count
-
--force-inline=<func1,func2,func3,...>List of functions to always consider for inlining
-
--frame-opt=<value>Optimize stack frame accesses
none: do not perform frame optimizationhot: perform FOP on hot functionsall: perform FOP on all functions
-
--frame-opt-rm-storesApply additional analysis to remove stores (experimental)
-
--function-order=<string>File containing an ordered list of functions to use for function reordering
-
--generate-function-order=<string>File to dump the ordered list of functions to use for function reordering
-
--generate-link-sections=<string>Generate a list of function sections in a format suitable for inclusion in a linker script
-
--group-stubsShare stubs across functions
-
--hugifyAutomatically put hot code on 2MB page(s) (hugify) at runtime. No manual call to hugify is needed in the binary (which is what --hot-text relies on).
-
--icfFold functions with identical code
-
--icpAlias for --indirect-call-promotion
-
--icp-calls-remaining-percent-threshold=<uint>The percentage threshold against remaining unpromoted indirect call count for the promotion for calls
-
--icp-calls-topnAlias for --indirect-call-promotion-calls-topn
-
--icp-calls-total-percent-threshold=<uint>The percentage threshold against total count for the promotion for calls
-
--icp-eliminate-loadsEnable load elimination using memory profiling data when performing ICP
-
--icp-funcs=<func1,func2,func3,...>List of functions to enable ICP for
-
--icp-inlineOnly promote call targets eligible for inlining
-
--icp-jt-remaining-percent-threshold=<uint>The percentage threshold against remaining unpromoted indirect call count for the promotion for jump tables
-
--icp-jt-targetsAlias for --icp-jump-tables-targets
-
--icp-jt-topnAlias for --indirect-call-promotion-jump-tables-topn
-
--icp-jt-total-percent-threshold=<uint>The percentage threshold against total count for the promotion for jump tables
-
--icp-jump-tables-targetsFor jump tables, optimize indirect jmp targets instead of indices
-
--icp-mp-thresholdAlias for --indirect-call-promotion-mispredict-threshold
-
--icp-old-code-sequenceUse old code sequence for promoted calls
-
--icp-top-callsites=<uint>Optimize hottest calls until at least this percentage of all indirect calls frequency is covered. 0 = all callsites
-
--icp-topnAlias for --indirect-call-promotion-topn
-
--icp-use-mpAlias for --indirect-call-promotion-use-mispredicts
-
--indirect-call-promotion=<value>Indirect call promotion
none: do not perform indirect call promotioncalls: perform ICP on indirect callsjump-tables: perform ICP on jump tablesall: perform ICP on calls and jump tables
-
--indirect-call-promotion-calls-topn=<uint>Limit number of targets to consider when doing indirect call promotion on calls. 0 = no limit
-
--indirect-call-promotion-jump-tables-topn=<uint>Limit number of targets to consider when doing indirect call promotion on jump tables. 0 = no limit
-
--indirect-call-promotion-topn=<uint>Limit number of targets to consider when doing indirect call promotion. 0 = no limit
-
--indirect-call-promotion-use-mispredictsUse misprediction frequency for determining whether or not ICP should be applied at a callsite. The -indirect-call-promotion-mispredict-threshold value will be used by this heuristic
-
--infer-fall-throughsInfer execution count for fall-through blocks
-
--infer-stale-profileInfer counts from stale profile data.
-
--inline-allInline all functions
-
--inline-apAdjust function profile after inlining
-
--inline-limit=<uint>Maximum number of call sites to inline
-
--inline-max-iters=<uint>Maximum number of inline iterations
-
--inline-memcpyInline memcpy using 'rep movsb' instruction (X86-only)
-
--inline-small-functionsInline functions if increase in size is less than defined by -inline-small- functions-bytes
-
--inline-small-functions-bytes=<uint>Max number of bytes for the function to be considered small for inlining purposes
-
--instrumentInstrument code to generate accurate profile data
-
--iterative-guessIn non-LBR mode, guess edge counts using iterative technique
-
--jt-footprint-optimize-for-icacheWith jt-footprint-reduction, only process PIC jumptables and turn off other transformations that increase code size
-
--jt-footprint-reductionMake jump tables size smaller at the cost of using more instructions at jump sites
-
--jump-tables=<value>Jump tables support (default=basic)
none: do not optimize functions with jump tablesbasic: optimize functions with jump tablesmove: move jump tables to a separate sectionsplit: split jump tables section into hot and cold based on function execution frequencyaggressive: aggressively split jump tables section based on usage of the tables
-
--keep-nopsKeep no-op instructions. By default they are removed.
-
--lite-threshold-count=<uint>Similar to '-lite-threshold-pct' but specify threshold using absolute function call count. I.e. limit processing to functions executed at least the specified number of times.
-
--lite-threshold-pct=<uint>Threshold (in percent) for selecting functions to process in lite mode. Higher threshold means fewer functions to process. E.g threshold of 90 means only top 10 percent of functions with profile will be processed.
-
--memcpy1-spec=<func1,func2:cs1:cs2,func3:cs1,...>List of functions with call sites for which to specialize memcpy() for size 1
-
--min-branch-clustersUse a modified clustering algorithm geared towards minimizing branches
-
--no-inlineDisable all inlining (overrides other inlining options)
-
--no-scanDo not scan cold functions for external references (may result in slower binary)
-
--peepholes=<value>Enable peephole optimizations
none: disable peepholesdouble-jumps: remove double jumps when abletailcall-traps: insert tail call trapsuseless-branches: remove useless conditional branchesall: enable all peephole optimizations
-
--plt=<value>Optimize PLT calls (requires linking with -znow)
none: do not optimize PLT callshot: optimize executed (hot) PLT callsall: optimize all PLT calls
-
--preserve-blocks-alignmentTry to preserve basic block alignment
-
--profile-ignore-hashIgnore hash while reading function profile
-
--profile-use-dfsUse DFS order for YAML profile
-
--reg-reassignReassign registers so as to avoid using REX prefixes in hot code
-
--reorder-blocks=<value>Change layout of basic blocks in a function
none: do not reorder basic blocksreverse: layout blocks in reverse ordernormal: perform optimal layout based on profilebranch-predictor: perform optimal layout prioritizing branch predictionscache: perform optimal layout prioritizing I-cache behaviorcache+: perform layout optimizing I-cache behaviorext-tsp: perform layout optimizing I-cache behaviorcluster-shuffle: perform random layout of clusters
-
--reorder-data=<section1,section2,section3,...>List of sections to reorder
-
--reorder-data-algo=<value>Algorithm used to reorder data sections
count: sort hot data by read countsfuncs: sort hot data by hot function usage and count
-
--reorder-data-inplaceReorder data sections in place
-
--reorder-data-max-bytes=<uint>Maximum number of bytes to reorder
-
--reorder-data-max-symbols=<uint>Maximum number of symbols to reorder
-
--reorder-functions=<value>Reorder and cluster functions (works only with relocations)
none: do not reorder functionsexec-count: order by execution counthfsort: use hfsort algorithmhfsort+: use cache-directed sortcdsort: use cache-directed sortpettis-hansen: use Pettis-Hansen algorithmrandom: reorder functions randomlyuser: use function order specified by -function-order
-
--reorder-functions-use-hot-sizeUse a function's hot size when doing clustering
-
--report-bad-layout=<uint>Print top functions with suboptimal code layout on input
-
--report-stalePrint the list of functions with stale profile
-
--runtime-hugify-lib=<string>Specify file name of the runtime hugify library
-
--runtime-instrumentation-lib=<string>Specify file name of the runtime instrumentation library
-
--sctc-mode=<value>Mode for simplify conditional tail calls
always: always perform sctcpreserve: only perform sctc when branch direction is preservedheuristic: use branch prediction data to control sctc
-
--sequential-disassemblyPerforms disassembly sequentially
-
--shrink-wrapping-threshold=<uint>Percentage of prologue execution count to use as threshold when evaluating whether a block is cold enough to be profitable to move eligible spills there
-
--simplify-conditional-tail-callsSimplify conditional tail calls by removing unnecessary jumps
-
--simplify-rodata-loadsSimplify loads from read-only sections by replacing the memory operand with the constant found in the corresponding section
-
--split-align-threshold=<uint>When deciding to split a function, apply this alignment while doing the size comparison (see -split-threshold). Default value: 2.
-
--split-all-coldOutline as many cold basic blocks as possible
-
--split-ehSplit C++ exception handling code
-
--split-functionsSplit functions into fragments
-
--split-strategy=<value>Strategy used to partition blocks into fragments
profile2: split each function into a hot and cold fragment using profiling informationcdsplit: split each function into a hot, warm, and cold fragment using profiling informationrandom2: split each function into a hot and cold fragment at a randomly chosen split point (ignoring any available profiling information)randomN: split each function into N fragments at a randomly chosen split points (ignoring any available profiling information)all: split all basic blocks of each function into fragments such that each fragment contains exactly a single basic block
-
--split-threshold=<uint>Split function only if its main size is reduced by more than given amount of bytes. Default value: 0, i.e. split iff the size is reduced. Note that on some architectures the size can increase after splitting.
-
--stale-matching-max-func-size=<uint>The maximum size of a function to consider for inference.
-
--stale-matching-min-matched-block=<uint>Percentage threshold of matched basic blocks at which stale profile inference is executed.
-
--stale-threshold=<uint>Maximum percentage of stale functions to tolerate (default: 100)
-
--stokeTurn on the stoke analysis
-
--strip-rep-retStrip 'repz' prefix from 'repz retq' sequence (on by default)
-
--tail-duplication=<value>Duplicate unconditional branches that cross a cache line
none: do not applyaggressive: aggressive strategymoderate: moderate strategycache: cache-aware duplication strategy
-
--tsp-threshold=<uint>Maximum number of hot basic blocks in a function for which to use a precise TSP solution while re-ordering basic blocks
-
--use-aggr-reg-reassignUse register liveness analysis to try to find more opportunities for -reg- reassign optimization
-
--use-compact-alignerUse compact approach for aligning functions
-
--use-edge-countsUse edge count data when doing clustering
-
--verify-cfgVerify the CFG after every pass
-
--x86-align-branch-boundary-hot-onlyOnly apply branch boundary alignment in hot code
-
--x86-strip-redundant-address-sizeRemove redundant Address-Size override prefix
BOLT options in relocation mode:
-
--align-macro-fusion=<value>Fix instruction alignment for macro-fusion (x86 relocation mode)
none: do not insert alignment no-ops for macro-fusionhot: only insert alignment no-ops on hot execution paths (default)all: always align instructions to allow macro-fusion
BOLT instrumentation options:
llvm-bolt <executable> -instrument [-o outputfile] <instrumented-executable>
-
--conservative-instrumentationDisable instrumentation optimizations that sacrifice profile accuracy (for debugging, default: false)
-
--instrument-callsRecord profile for inter-function control flow activity (default: true)
-
--instrument-hot-onlyOnly insert instrumentation on hot functions (needs profile, default: false)
-
--instrumentation-binpath=<string>Path to instrumented binary in case if /proc/self/map_files is not accessible due to access restriction issues
-
--instrumentation-file=<string>File name where instrumented profile will be saved (default: /tmp/prof.fdata)
-
--instrumentation-file-append-pidAppend PID to saved profile file name (default: false)
-
--instrumentation-no-counters-clearDon't clear counters across dumps (use with instrumentation-sleep-time option)
-
--instrumentation-sleep-time=<uint>Interval between profile writes (default: 0 = write only at program end). This is useful for service workloads when you want to dump profile every X minutes or if you are killing the program and the profile is not being dumped at the end.
-
--instrumentation-wait-forksWait until all forks of instrumented process will finish (use with instrumentation-sleep-time option)
BOLT printing options:
-
--print-aliasesPrint aliases when printing objects
-
--print-allPrint functions after each stage
-
--print-cfgPrint functions after CFG construction
-
--print-debug-infoPrint debug info when printing functions
-
--print-disasmPrint function after disassembly
-
--print-dyno-opcode-stats=<uint>Print per instruction opcode dyno stats and the functionnames:BB offsets of the nth highest execution counts
-
--print-dyno-stats-onlyWhile printing functions output dyno-stats and skip instructions
-
--print-exceptionsPrint exception handling data
-
--print-globalsPrint global symbols after disassembly
-
--print-jump-tablesPrint jump tables
-
--print-loopsPrint loop related information
-
--print-mem-dataPrint memory data annotations when printing functions
-
--print-normalizedPrint functions after CFG is normalized
-
--print-only=<func1,func2,func3,...>List of functions to print
-
--print-orcPrint ORC unwind information for instructions
-
--print-profilePrint functions after attaching profile
-
--print-profile-statsPrint profile quality/bias analysis
-
--print-pseudo-probes=<value>Print pseudo probe info
decode: decode probes section from binaryaddress_conversion: update address2ProbesMap with output block addressencoded_probes: display the encoded probes in binary sectionall: enable all debugging printout
-
--print-relocationsPrint relocations when printing functions/objects
-
--print-reordered-dataPrint section contents after reordering
-
--print-retpoline-insertionPrint functions after retpoline insertion pass
-
--print-sdtPrint all SDT markers
-
--print-sectionsPrint all registered sections
-
--print-unknownPrint names of functions with unknown control flow
-
--time-buildPrint time spent constructing binary functions
-
--time-rewritePrint time spent in rewriting passes
-
--print-after-branch-fixupPrint function after fixing local branches
-
--print-after-jt-footprint-reductionPrint function after jt-footprint-reduction pass
-
--print-after-loweringPrint function after instruction lowering
-
--print-cache-metricsCalculate and print various metrics for instruction cache
-
--print-clustersPrint clusters
-
--print-estimate-edge-countsPrint function after edge counts are set for no-LBR profile
-
--print-finalizedPrint function after CFG is finalized
-
--print-fix-relaxationsPrint functions after fix relaxations pass
-
--print-fix-riscv-callsPrint functions after fix RISCV calls pass
-
--print-fopPrint functions after frame optimizer pass
-
--print-function-statistics=<uint>Print statistics about basic block ordering
-
--print-icfPrint functions after ICF optimization
-
--print-icpPrint functions after indirect call promotion
-
--print-inlinePrint functions after inlining optimization
-
--print-large-functionsPrint functions that could not be overwritten due to excessive size
-
--print-longjmpPrint functions after longjmp pass
-
--print-optimize-bodylessPrint functions after bodyless optimization
-
--print-output-address-rangePrint output address range for each basic block in the function whenBinaryFunction::print is called
-
--print-peepholesPrint functions after peephole optimization
-
--print-pltPrint functions after PLT optimization
-
--print-regreassignPrint functions after regreassign pass
-
--print-reorderedPrint functions after layout optimization
-
--print-reordered-functionsPrint functions after clustering
-
--print-sctcPrint functions after conditional tail call simplification
-
--print-simplify-rodata-loadsPrint functions after simplification of RO data loads
-
--print-sorted-by=<value>Print functions sorted by order of dyno stats
executed-forward-branches: executed forward branchestaken-forward-branches: taken forward branchesexecuted-backward-branches: executed backward branchestaken-backward-branches: taken backward branchesexecuted-unconditional-branches: executed unconditional branchesall-function-calls: all function callsindirect-calls: indirect callsPLT-calls: PLT callsexecuted-instructions: executed instructionsexecuted-load-instructions: executed load instructionsexecuted-store-instructions: executed store instructionstaken-jump-table-branches: taken jump table branchestaken-unknown-indirect-branches: taken unknown indirect branchestotal-branches: total branchestaken-branches: taken branchesnon-taken-conditional-branches: non-taken conditional branchestaken-conditional-branches: taken conditional branchesall-conditional-branches: all conditional brancheslinker-inserted-veneer-calls: linker-inserted veneer callsall: sorted by all names
-
--print-sorted-by-order=<value>Use ascending or descending order when printing functions ordered by dyno stats
-
--print-splitPrint functions after code splitting
-
--print-stokePrint functions after stoke analysis
-
--print-ucePrint functions after unreachable code elimination
-
--print-veneer-eliminationPrint functions after veneer elimination pass
-
--time-optsPrint time spent in each optimization
-
--print-all-optionsPrint all option values after command line parsing
-
--print-optionsPrint non-default options after command line parsing