Pgo

mohitmishra786/low-level-dev-skills/skills/compilers/pgo

作者 mohitmishra786bdc58472fa9f無授權條款253 個星標收錄於 2026年10月9日更新於 2026年10月9日儲存庫3 個月前更新

Profile-guided optimisation skill for C/C++ with GCC and Clang. Use when squeezing maximum runtime performance after standard optimisation plateaus, implementing two-stage PGO builds, collecting profile data, or applying BOLT for post-link optimisation. Activates on queries about PGO, profile-guided optimization, fprofile-generate, fprofile-use, instrumented builds, or BOLT.

僅含說明Software Development

AI 產生的概覽

引導代理使用 GCC 與 Clang 對 C/C++ 進行設定檔導向最佳化（PGO）與 BOLT 建置。

功能: 說明完整的 PGO 工作流程：插樁建置、執行具代表性的工作負載、收集並合併設定檔資料，以及產生最佳化後的建置。涵蓋 GCC（-fprofile-generate/-fprofile-use）、Clang IR PGO 與 SamplePGO、CMake 整合，以及 BOLT 連結後最佳化。也說明如何用 perf 驗證效能影響。
適用情境: 適用於 -O3 等標準最佳化已達瓶頸、需要追求最大執行效能時，或需要實作兩階段 PGO 建置、收集設定檔資料、套用 BOLT 時。也適用於關於 fprofile-generate、fprofile-use、插樁建置或 BOLT 的問題。
執行需求: 需要 GCC 或 Clang 工具鏈、LLVM 工具（如 llvm-profdata、llvm-profgen、llvm-bolt）、用於取樣與驗證的 perf，以及用於整合範例的 CMake。僅為說明性內容，不附帶指令碼。

PGO (Profile-Guided Optimisation)

Purpose

Guide agents through the full PGO workflow: instrument build → representative workload → collect profile → optimised build, covering both GCC and Clang, plus BOLT for post-link optimisation.

Triggers

"How do I use PGO to speed up my binary?"
"What is profile-guided optimization and when should I use it?"
"How do I use -fprofile-generate and -fprofile-use?"
"My -O3 build isn't fast enough — what next?"
"How does BOLT differ from PGO?"
"How do I collect representative profile data?"

Workflow

1. When to use PGO

text

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

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 helps most with:

Large binaries with many cold/hot code paths (compilers, databases, servers)
Branch-heavy code where static prediction is wrong
Function call-heavy code where inlining decisions improve with profile data

2. GCC PGO workflow

bash

# Step 1: Build with instrumentationgcc -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 profilegcc -O2 -fprofile-use -fprofile-dir=./pgo-data \    -fprofile-correction \    prog.c -o prog_pgo

# Step 1: Build with instrumentationgcc -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 profilegcc -O2 -fprofile-use -fprofile-dir=./pgo-data \    -fprofile-correction \    prog.c -o prog_pgo

-fprofile-correction: handles profile count inconsistencies from parallel or nondeterministic runs. Always include it.

3. Clang PGO workflow (IR-based, preferred)

bash

# Step 1: Instrument buildclang -O2 -fprofile-instr-generate prog.c -o prog_instr
# Step 2: Run workload (generates default.profraw)./prog_instr < workload.inputLLVM_PROFILE_FILE="prog-%p.profraw" ./prog_instr  # per-PID files for parallel runs
# Step 3: Merge raw profilesllvm-profdata merge -output=prog.profdata *.profraw
# Step 4: Optimised buildclang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog_pgo

# Step 1: Instrument buildclang -O2 -fprofile-instr-generate prog.c -o prog_instr
# Step 2: Run workload (generates default.profraw)./prog_instr < workload.inputLLVM_PROFILE_FILE="prog-%p.profraw" ./prog_instr  # per-PID files for parallel runs
# Step 3: Merge raw profilesllvm-profdata merge -output=prog.profdata *.profraw
# Step 4: Optimised buildclang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog_pgo

Clang's IR PGO is more accurate than GCC's and supports SamplePGO (sampling-based, no instrumentation overhead).

4. Clang SamplePGO (sampling, no instrumentation)

bash

# Step 1: Build with frame pointers for accurate stacksclang -O2 -fno-omit-frame-pointer prog.c -o prog
# Step 2: Sample with perfperf record -b -e cycles:u ./prog < workload.inputperf script -F ip,brstack > perf.script  # or use perf2bolt
# Step 3: Convert perf datallvm-profgen --binary=./prog --perf-script=perf.script \             --output=prog.profdata
# Step 4: Optimised buildclang -O2 -fprofile-sample-use=prog.profdata prog.c -o prog_spgo

# Step 1: Build with frame pointers for accurate stacksclang -O2 -fno-omit-frame-pointer prog.c -o prog
# Step 2: Sample with perfperf record -b -e cycles:u ./prog < workload.inputperf script -F ip,brstack > perf.script  # or use perf2bolt
# Step 3: Convert perf datallvm-profgen --binary=./prog --perf-script=perf.script \             --output=prog.profdata
# Step 4: Optimised buildclang -O2 -fprofile-sample-use=prog.profdata prog.c -o prog_spgo

SamplePGO is ideal for production profiling without instrumentation overhead.

5. CMake integration

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()

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()

Build script:

bash

# Phase 1: instrumentcmake -S . -B build-pgo-instr -DPGO_INSTRUMENT=ON -DCMAKE_BUILD_TYPE=Releasecmake --build build-pgo-instr -j$(nproc)
# Collect profile./build-pgo-instr/prog < workload.inputllvm-profdata merge -output=prog.profdata *.profraw
# Phase 2: optimisedcmake -S . -B build-pgo -DPGO_USE=ON -DCMAKE_BUILD_TYPE=Releasecmake --build build-pgo -j$(nproc)

# Phase 1: instrumentcmake -S . -B build-pgo-instr -DPGO_INSTRUMENT=ON -DCMAKE_BUILD_TYPE=Releasecmake --build build-pgo-instr -j$(nproc)
# Collect profile./build-pgo-instr/prog < workload.inputllvm-profdata merge -output=prog.profdata *.profraw
# Phase 2: optimisedcmake -S . -B build-pgo -DPGO_USE=ON -DCMAKE_BUILD_TYPE=Releasecmake --build build-pgo -j$(nproc)

6. BOLT (post-link binary optimisation)

BOLT reorders functions and basic blocks in the final binary based on profile data, improving instruction cache locality. Works after PGO for additional 5-15%.

bash

# Step 1: Build with relocation supportclang -O2 -Wl,--emit-relocs prog.c -o prog
# Step 2: Collect profile with perfperf record -e cycles:u -b ./prog < workload.inputperf2bolt prog -p perf.data -o prog.fdata
# Or use instrumented BOLTllvm-bolt prog -instrument -o prog.instr./prog.instr < workload.input# Generates /tmp/prof.fdata
# Step 3: Apply BOLT optimisationllvm-bolt prog -data prog.fdata -o prog.bolt \    -reorder-blocks=ext-tsp \    -reorder-functions=hfsort \    -split-functions \    -split-all-cold \    -dyno-stats

# Step 1: Build with relocation supportclang -O2 -Wl,--emit-relocs prog.c -o prog
# Step 2: Collect profile with perfperf record -e cycles:u -b ./prog < workload.inputperf2bolt prog -p perf.data -o prog.fdata
# Or use instrumented BOLTllvm-bolt prog -instrument -o prog.instr./prog.instr < workload.input# Generates /tmp/prof.fdata
# Step 3: Apply BOLT optimisationllvm-bolt prog -data prog.fdata -o prog.bolt \    -reorder-blocks=ext-tsp \    -reorder-functions=hfsort \    -split-functions \    -split-all-cold \    -dyno-stats

7. Verifying PGO impact

bash

# Compare perf of instrumented vs PGO buildperf stat ./prog_baseline < workload.inputperf stat ./prog_pgo < workload.input
# Check which functions are hot in eachperf record ./prog_pgo < workload.inputperf report --stdio | head -30

# Compare perf of instrumented vs PGO buildperf stat ./prog_baseline < workload.inputperf stat ./prog_pgo < workload.input
# Check which functions are hot in eachperf record ./prog_pgo < workload.inputperf report --stdio | head -30

For full workflow details and Clang vs GCC profile format notes, see references/pgo-workflow.md [blocked].

Related skills

Use skills/compilers/gcc for GCC flag context
Use skills/compilers/clang for Clang PGO and SamplePGO setup
Use skills/profilers/linux-perf for collecting SamplePGO perf data
Use skills/profilers/flamegraphs to identify hot paths before applying PGO

來源與署名

來源：mohitmishra786/low-level-dev-skills位於skills/compilers/pgo提交bdc5847

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Pgo

PGO (Profile-Guided Optimisation)

Purpose

Triggers

Workflow

1. When to use PGO

2. GCC PGO workflow

3. Clang PGO workflow (IR-based, preferred)

4. Clang SamplePGO (sampling, no instrumentation)

5. CMake integration

6. BOLT (post-link binary optimisation)

7. Verifying PGO impact

Related skills

來源與署名

更多來自 mohitmishra786/low-level-dev-skills 的技能

Zig Debugging

Simd Intrinsics

Zig Cross

Rustc Basics

Zig Cinterop

Zig Build System

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices