pgo

PGO（配置文件引导优化）

用途

引导 Agent 完成完整的 PGO 工作流：插桩构建 → 代表性工作负载 → 收集配置文件 → 优化构建，涵盖 GCC 和 Clang，以及用于链接后优化的 BOLT。

触发条件

• “如何使用 PGO 加速我的二进制文件？”
• “什么是配置文件引导优化？什么时候应该使用？”
• “如何使用 -fprofile-generate 和 -fprofile-use？”
• “我的 -O3 构建速度还不够快——接下来该怎么做？”
• “BOLT 与 PGO 有什么区别？”
• “如何收集有代表性的配置文件数据？”

工作流

1. 何时使用 PGO

Is -O3 -march=native already applied?
  no  → apply standard optimisation first
  yes → is workload branch-heavy or has irregular call patterns?
          yes → PGO will likely help 5-30%
          no  → PGO may not help; profile first with linux-perf

PGO 对以下情况最有帮助：

• 具有许多冷/热代码路径的大型二进制文件（编译器、数据库、服务）
• 静态预测不准确的分支密集型代码
• 函数调用密集型代码，配置文件数据有助于改进内联决策

2. GCC PGO 工作流

# Step 1: Build with instrumentation
gcc -O2 -fprofile-generate -fprofile-dir=./pgo-data \
    prog.c -o prog_instr

# Step 2: Run with representative workload(s)
./prog_instr < workload1.input
./prog_instr < workload2.input
# Generates .gcda files in ./pgo-data/

# Step 3: Build optimised binary using profile
gcc -O2 -fprofile-use -fprofile-dir=./pgo-data \
    -fprofile-correction \
    prog.c -o prog_pgo

-fprofile-correction：处理并行运行或非确定性运行导致的配置文件计数不一致。务必包含此选项。

3. Clang PGO 工作流（基于 IR，优先使用）

# Step 1: Instrument build
clang -O2 -fprofile-instr-generate prog.c -o prog_instr

# Step 2: Run workload (generates default.profraw)
./prog_instr < workload.input
LLVM_PROFILE_FILE="prog-%p.profraw" ./prog_instr  # per-PID files for parallel runs

# Step 3: Merge raw profiles
llvm-profdata merge -output=prog.profdata *.profraw

# Step 4: Optimised build
clang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog_pgo

Clang 的 IR PGO 比 GCC 更准确，并支持 SamplePGO（基于采样，无插桩开销）。

4. Clang SamplePGO（采样，无插桩）

# Step 1: Build with frame pointers for accurate stacks
clang -O2 -fno-omit-frame-pointer prog.c -o prog

# Step 2: Sample with perf
perf record -b -e cycles:u ./prog < workload.input
perf script -F ip,brstack > perf.script  # or use perf2bolt

# Step 3: Convert perf data
llvm-profgen --binary=./prog --perf-script=perf.script \
             --output=prog.profdata

# Step 4: Optimised build
clang -O2 -fprofile-sample-use=prog.profdata prog.c -o prog_spgo

SamplePGO 非常适合在生产环境中进行分析，且无插桩开销。

5. CMake 集成

option(PGO_INSTRUMENT "Build with PGO instrumentation" OFF)
option(PGO_USE "Build with PGO profile data" OFF)

if(PGO_INSTRUMENT)
    add_compile_options(-fprofile-instr-generate)
    add_link_options(-fprofile-instr-generate)
endif()

if(PGO_USE)
    add_compile_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
    add_link_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
endif()

构建脚本：

# Phase 1: instrument
cmake -S . -B build-pgo-instr -DPGO_INSTRUMENT=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-pgo-instr -j$(nproc)

# Collect profile
./build-pgo-instr/prog < workload.input
llvm-profdata merge -output=prog.profdata *.profraw

# Phase 2: optimised
cmake -S . -B build-pgo -DPGO_USE=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-pgo -j$(nproc)

6. BOLT（链接后二进制优化）

BOLT 根据配置文件数据重新排列最终二进制文件中的函数和基本块，从而改善指令缓存局部性。在 PGO 之后使用，可额外提升 5-15%。

# Step 1: Build with relocation support
clang -O2 -Wl,--emit-relocs prog.c -o prog

# Step 2: Collect profile with perf
perf record -e cycles:u -b ./prog < workload.input
perf2bolt prog -p perf.data -o prog.fdata

# Or use instrumented BOLT
llvm-bolt prog -instrument -o prog.instr
./prog.instr < workload.input
# Generates /tmp/prof.fdata

# Step 3: Apply BOLT optimisation
llvm-bolt prog -data prog.fdata -o prog.bolt \
    -reorder-blocks=ext-tsp \
    -reorder-functions=hfsort \
    -split-functions \
    -split-all-cold \
    -dyno-stats

7. 验证 PGO 的效果

# Compare perf of instrumented vs PGO build
perf stat ./prog_baseline < workload.input
perf stat ./prog_pgo < workload.input

# Check which functions are hot in each
perf record ./prog_pgo < workload.input
perf report --stdio | head -30

如需了解完整工作流详情以及 Clang 与 GCC 配置文件格式的注意事项，请参阅 references/pgo-workflow.md。

相关技能

• 使用 skills/compilers/gcc 了解 GCC 标志背景信息
• 使用 skills/compilers/clang 设置 Clang PGO 和 SamplePGO
• 使用 skills/profilers/linux-perf 收集 SamplePGO perf 数据
• 使用 skills/profilers/flamegraphs 在应用 PGO 前识别热点路径