Skip to content

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

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.

FileKindSize
SKILL.mdskill md6.1 KB
references/pgo-workflow.mdmarkdown3.1 KB

references/pgo-workflow.md

View on GitHub
# PGO Workflow Reference

## GCC Profile Data Formats

| Format | Flag | Notes |
|--------|------|-------|
| GCOV (classic) | `-fprofile-generate` / `-fprofile-use` | `.gcda` + `.gcno` files |
| AutoFDO | `-fauto-profile=file` | Converted from perf data via `create_gcov` |

## Clang Profile Data Formats

| Format | Flag | Notes |
|--------|------|-------|
| IR-based (instrumented) | `-fprofile-instr-generate` / `-fprofile-instr-use` | `.profraw` → merge → `.profdata` |
| Sampling (SamplePGO) | `-fprofile-sample-use` | From perf/DTrace, no overhead |
| Context-sensitive PGO | `-fcs-profile-generate` | Two-stage IR-PGO for deeper context |

## llvm-profdata Commands

```bash
# Merge multiple raw profiles
llvm-profdata merge -output=merged.profdata *.profraw

# Merge with weights (run workload A more than B)
llvm-profdata merge -output=merged.profdata \
    -weighted-input=3,workloadA.profraw \
    -weighted-input=1,workloadB.profraw

# Show profile stats
llvm-profdata show --all-functions merged.profdata | head -50

# Overlap between two profiles (check representativeness)
llvm-profdata overlap profile1.profdata profile2.profdata
```

## Context-Sensitive PGO (CS-PGO) Workflow

CS-PGO provides more precise inlining by tracking call-site context:

```bash
# Stage 1: Regular PGO
clang -O2 -fprofile-instr-generate prog.c -o prog.instr1
./prog.instr1 < workload.input
llvm-profdata merge -output=stage1.profdata *.profraw

# Stage 2: CS-PGO instrumentation using stage1 profile
clang -O2 -fprofile-use=stage1.profdata \
      -fcs-profile-generate prog.c -o prog.instr2
./prog.instr2 < workload.input
llvm-profdata merge -output=cs.profdata *.profraw

# Final build
clang -O2 -fprofile-use=cs.profdata prog.c -o prog.cspgo
```

## Workload Representativeness

A PGO build is only as good as the workload used to collect profiles.

Checklist:

- [ ] Workload covers all major code paths (hot loops, branches)
- [ ] Workload duration: at least 30 seconds of representative execution
- [ ] Multi-workload merge: weight production-like scenarios higher
- [ ] Avoid one-off startup paths unless startup matters

Red flags:

- Training on a tiny synthetic benchmark and deploying for general use
- Only training on error paths
- Profile collected from a debug build (use `-O2` for instrumentation)

## BOLT Configuration Reference

```bash
llvm-bolt prog -data prof.fdata -o prog.bolt \
    -reorder-blocks=ext-tsp     # Best block reordering algorithm
    -reorder-functions=hfsort   # Hutch-sort for function layout
    -split-functions             # Split hot/cold function portions
    -split-all-cold              # Move all cold code to .cold section
    -eliminate-unreachable       # Remove dead code
    -frame-opt=hot               # Optimize frame pointer usage in hot funcs
    -use-gnu-stack               # For GNU stack compatibility
    -dyno-stats                  # Print optimisation statistics
```

## Benchmarking Template

```bash
#!/bin/bash
set -e
WORKLOAD="./bench_input"
RUNS=5

hyperfine --runs $RUNS "./prog_baseline $WORKLOAD" \
          "./prog_pgo $WORKLOAD" \
          "./prog_bolt $WORKLOAD" \
          --export-markdown results.md
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall