| Field | \nBound contract | \n
|---|---|
| Trigger | \nA hot loop stayed scalar at -O3, assembly shows spills, -O3 runs slower than -O2, GCC and Clang produce different code for the same source, or a profile-guided or post-link optimization is being planned or produced no gain. | \n
| Authority | \nReversible local: writes only instrumented binaries, profiles, and remark files under a scratch directory named in the report; rollback is deleting that directory. No remote mutation. | \n
| Side effect | \nRuns the compiler with remark flags, and when asked, an instrumented build and a training run. Project files are not modified. | \n
| Done | \nEach symptom is attributed to a named pipeline stage with the compiler's own remark or output as evidence, and each fix is stated as a source change, a flag, or a workflow step the user can apply. | \n
clang --version or gcc --version. Grounded current stables are LLVM/Clang 23.1.0 and GCC 16.2; flags below are confirmed against Clang 23.1.0.-O3, or a PGO or BOLT plan.Place the symptom in the pipeline. After the frontend emits LLVM IR (or GIMPLE in GCC), the mid-level passes run (dead code elimination, GVN, loop-invariant code motion, inlining), then loop passes (unroll, vectorize), then codegen preparation, instruction selection, register allocation, and scheduling. Pass order matters: LICM must hoist an invariant before the vectorizer can prove the loop simple. Done when: the stage is named.
\nFor a loop that did not vectorize, ask the compiler why:
\nclang -O3 -Rpass=loop-vectorize -Rpass-missed=loop-vectorize -Rpass-analysis=loop-vectorize -c foo.c\n-Rpass-analysis prints the reason. Map the reason to the fix:
| Reason in remark | \nFix | \n
|---|---|
| Trip count unknown or loop exit not computable | \nRestructure so the exit is a simple counted loop; peel the remainder. | \n
| Memory dependence between iterations | \nReorder accesses or use separate accumulators; add restrict when the pointers do not alias. | \n
| Cannot reorder floating-point operations | \nA reduction over floats needs reassociation: #pragma clang loop vectorize(enable) on the loop or -ffast-math on the file, with the precision cost accepted. | \n
| Call inside the loop | \nInline it, or move the call out of the loop body. | \n
| Unknown alignment | \n__builtin_assume_aligned where the alignment is guaranteed by the allocator. | \n
Done when: the remark reason is quoted and one fix is chosen for it.
\nFor spills, read them as live ranges exceeding the physical registers. The allocator stores values to stack slots and reloads them; each spill is a load or store on the hot path. LLVM's default allocator at -O2 and above is the greedy allocator (llc -regalloc=greedy). Reduce pressure by shortening live ranges: split long-lived variables, compute cheap values where used instead of keeping them, and reduce unrolling in the affected loop. Done when: a source change moves the spill count, which confirms the cause.
For -O3 slower than -O2, treat it as a code-size effect: more inlining and unrolling can exceed the instruction cache of the target core. Measure both, and prefer -O2 plus PGO over -O3 alone when -O2 wins. Done when: both builds are timed on the workload and the choice is stated with the numbers.
For a PGO deployment with Clang, run the three-step workflow on the representative workload:
\nclang -fprofile-instr-generate -O2 -o app foo.c\n./app # training run writes default.profraw\nllvm-profdata merge default.profraw -o default.profdata\nclang -fprofile-instr-use=default.profdata -O2 -o app_pgo foo.c\nThe profile improves branch layout, inlining decisions, and the vectorizer's cost decisions. A profile from an unrepresentative input makes the build worse on production input. Done when: the PGO binary is timed against the baseline on production-like input.
\nFor a post-link layout pass with BOLT, the binary must keep its symbol table and be linked with relocations (-Wl,--emit-relocs; confirm with a .rela.text section in readelf -S). Collect a profile by instrumentation when perf sampling is unavailable, then optimize:
llvm-bolt app -instrument -o app.inst\n./app.inst # writes /tmp/prof.fdata\nllvm-bolt app -o app.bolt -data=/tmp/prof.fdata -reorder-blocks=ext-tsp\nBOLT is incompatible with GCC's default -freorder-blocks-and-partition; add -fno-reorder-blocks-and-partition when compiling with GCC. Done when: app.bolt runs and readelf -S app.bolt shows a .note.bolt_info section.
For a GCC versus Clang difference, compare at two levels: the IR after optimization and the final assembly. The pass orders differ, so a loop one vectorizes and the other does not is normal; use the remark flags of each compiler to see the reason on each side. Done when: the first diverging decision is named.
\n| Failure class | \nBehavior | \n
|---|---|
| No remark printed for the loop | \nThe loop was not considered; usually it was fully unrolled or deleted earlier. Check with -Rpass=loop-unroll and inspect the IR before concluding. | \n
| PGO shows no gain | \nTraining input did not match production. Re-collect with a representative input before changing flags. | \n
| BOLT rejects the binary | \nSymbols stripped or no relocations. Relink with -Wl,--emit-relocs and without strip. | \n
-ffast-math changes results | \nThe reduction reorder is the cause. Use the per-loop pragma instead, or keep the loop scalar and accept it. | \n
| Compiler version older than the grounded stable | \nRemark names and allocator defaults may differ. Report the version and confirm each flag with --help before relying on it. | \n
No partial result is claimed complete. If a step cannot finish, the report states which steps ran and which are blocked.
\nAn optimization report containing:
\n-O2 versus -O3 comparison.