pgo

Name: pgo
Author: mohitmishra786

288installs19forks

How to install pgo?

mohitmishra786/low-level-dev-skills/pgo

$npx -y skills add mohitmishra786/low-level-dev-skills --skill pgo

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# PGO (Profile-Guided Optimisation)
2
3	## Purpose
4
5	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.
6
7	## Triggers
8
9	- "How do I use PGO to speed up my binary?"
10	- "What is profile-guided optimization and when should I use it?"
11	- "How do I use `-fprofile-generate` and `-fprofile-use`?"
12	- "My `-O3` build isn't fast enough — what next?"
13	- "How does BOLT differ from PGO?"
14	- "How do I collect representative profile data?"
15
16	## Workflow
17
18	### 1. When to use PGO
19
20	```text
21	Is -O3 -march=native already applied?
22	no → apply standard optimisation first
23	yes → is workload branch-heavy or has irregular call patterns?
24	yes → PGO will likely help 5-30%
25	no → PGO may not help; profile first with linux-perf
26	```
27
28	PGO helps most with:
29
30	- Large binaries with many cold/hot code paths (compilers, databases, servers)
31	- Branch-heavy code where static prediction is wrong
32	- Function call-heavy code where inlining decisions improve with profile data
33
34	### 2. GCC PGO workflow
35
36	```bash
37	# Step 1: Build with instrumentation
38	gcc -O2 -fprofile-generate -fprofile-dir=./pgo-data \
39	prog.c -o prog_instr
40
41	# Step 2: Run with representative workload(s)
42	./prog_instr < workload1.input
43	./prog_instr < workload2.input
44	# Generates .gcda files in ./pgo-data/
45
46	# Step 3: Build optimised binary using profile
47	gcc -O2 -fprofile-use -fprofile-dir=./pgo-data \
48	-fprofile-correction \
49	prog.c -o prog_pgo
50	```
51
52	`-fprofile-correction`: handles profile count inconsistencies from parallel or nondeterministic runs. Always include it.
53
54	### 3. Clang PGO workflow (IR-based, preferred)
55
56	```bash
57	# Step 1: Instrument build
58	clang -O2 -fprofile-instr-generate prog.c -o prog_instr
59
60	# Step 2: Run workload (generates default.profraw)
61	./prog_instr < workload.input
62	LLVM_PROFILE_FILE="prog-%p.profraw" ./prog_instr # per-PID files for parallel runs
63
64	# Step 3: Merge raw profiles
65	llvm-profdata merge -output=prog.profdata *.profraw
66
67	# Step 4: Optimised build
68	clang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog_pgo
69	```
70
71	Clang's IR PGO is more accurate than GCC's and supports `SamplePGO` (sampling-based, no instrumentation overhead).
72
73	### 4. Clang SamplePGO (sampling, no instrumentation)
74
75	```bash
76	# Step 1: Build with frame pointers for accurate stacks
77	clang -O2 -fno-omit-frame-pointer prog.c -o prog
78
79	# Step 2: Sample with perf
80	perf record -b -e cycles:u ./prog < workload.input
81	perf script -F ip,brstack > perf.script # or use perf2bolt
82
83	# Step 3: Convert perf data
84	llvm-profgen --binary=./prog --perf-script=perf.script \
85	--output=prog.profdata
86
87	# Step 4: Optimised build
88	clang -O2 -fprofile-sample-use=prog.profdata prog.c -o prog_spgo
89	```
90
91	SamplePGO is ideal for production profiling without instrumentation overhead.
92
93	### 5. CMake integration
94
95	```cmake
96	option(PGO_INSTRUMENT "Build with PGO instrumentation" OFF)
97	option(PGO_USE "Build with PGO profile data" OFF)
98
99	if(PGO_INSTRUMENT)
100	add_compile_options(-fprofile-instr-generate)
101	add_link_options(-fprofile-instr-generate)
102	endif()
103
104	if(PGO_USE)
105	add_compile_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
106	add_link_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
107	endif()
108	```
109
110	Build script:
111
112	```bash
113	# Phase 1: instrument
114	cmake -S . -B build-pgo-instr -DPGO_INSTRUMENT=ON -DCMAKE_BUILD_TYPE=Release
115	cmake --build build-pgo-instr -j$(nproc)
116
117	# Collect profile
118	./build-pgo-instr/prog < workload.input
119	llvm-profdata merge -output=prog.profdata *.profraw
120
121	# Phase 2: optimised
122	cmake -S . -B build-pgo -DPGO_USE=ON -DCMAKE_BUILD_TYPE=Release
123	cmake --build build-pgo -j$(nproc)
124	```
125
126	### 6. BOLT (post-link binary optimisation)
127
128	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%.
129
130	```bash
131	# Step 1: Build with relocation support
132	clang -O2 -Wl,--emit-relocs prog.c -o prog
133
134	# Step 2: Collect profile with perf
135	perf record -e cycles:u -b ./prog < workload.input
136	perf2bolt prog -p perf.data -o prog.fdata
137
138	# Or use instrumented BOLT
139	llvm-bolt prog -instrument -o prog.instr
140	./prog.instr < workload.input
141	# Generates /tmp/prof.fdata
142
143	# Step 3: Apply BOLT optimisation
144	llvm-bolt prog -data prog.fdata -o prog.bolt \
145	-reorder-blocks=ext-tsp \
146	-reorder-functions=hfsort \
147	-split-functions \
148	-split-all-cold \
149	-dyno-stats
150	```
151
152	### 7. Verifying PGO impact
153
154	```bash
155	# Compare perf of instrumented vs PGO build
156	perf stat ./prog_baseline

People who liked this also viewed

6 picks

Type

pgo

288installs19forks

View on GitHub

How to install pgo?

mohitmishra786/low-level-dev-skills/pgo

$npx -y skills add mohitmishra786/low-level-dev-skills --skill pgo

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# PGO (Profile-Guided Optimisation)
2
3	## Purpose
4
5	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.
6
7	## Triggers
8
9	- "How do I use PGO to speed up my binary?"
10	- "What is profile-guided optimization and when should I use it?"
11	- "How do I use `-fprofile-generate` and `-fprofile-use`?"
12	- "My `-O3` build isn't fast enough — what next?"
13	- "How does BOLT differ from PGO?"
14	- "How do I collect representative profile data?"
15
16	## Workflow
17
18	### 1. When to use PGO
19
20	```text
21	Is -O3 -march=native already applied?
22	no → apply standard optimisation first
23	yes → is workload branch-heavy or has irregular call patterns?
24	yes → PGO will likely help 5-30%
25	no → PGO may not help; profile first with linux-perf
26	```
27
28	PGO helps most with:
29
30	- Large binaries with many cold/hot code paths (compilers, databases, servers)
31	- Branch-heavy code where static prediction is wrong
32	- Function call-heavy code where inlining decisions improve with profile data
33
34	### 2. GCC PGO workflow
35
36	```bash
37	# Step 1: Build with instrumentation
38	gcc -O2 -fprofile-generate -fprofile-dir=./pgo-data \
39	prog.c -o prog_instr
40
41	# Step 2: Run with representative workload(s)
42	./prog_instr < workload1.input
43	./prog_instr < workload2.input
44	# Generates .gcda files in ./pgo-data/
45
46	# Step 3: Build optimised binary using profile
47	gcc -O2 -fprofile-use -fprofile-dir=./pgo-data \
48	-fprofile-correction \
49	prog.c -o prog_pgo
50	```
51
52	`-fprofile-correction`: handles profile count inconsistencies from parallel or nondeterministic runs. Always include it.
53
54	### 3. Clang PGO workflow (IR-based, preferred)
55
56	```bash
57	# Step 1: Instrument build
58	clang -O2 -fprofile-instr-generate prog.c -o prog_instr
59
60	# Step 2: Run workload (generates default.profraw)
61	./prog_instr < workload.input
62	LLVM_PROFILE_FILE="prog-%p.profraw" ./prog_instr # per-PID files for parallel runs
63
64	# Step 3: Merge raw profiles
65	llvm-profdata merge -output=prog.profdata *.profraw
66
67	# Step 4: Optimised build
68	clang -O2 -fprofile-instr-use=prog.profdata prog.c -o prog_pgo
69	```
70
71	Clang's IR PGO is more accurate than GCC's and supports `SamplePGO` (sampling-based, no instrumentation overhead).
72
73	### 4. Clang SamplePGO (sampling, no instrumentation)
74
75	```bash
76	# Step 1: Build with frame pointers for accurate stacks
77	clang -O2 -fno-omit-frame-pointer prog.c -o prog
78
79	# Step 2: Sample with perf
80	perf record -b -e cycles:u ./prog < workload.input
81	perf script -F ip,brstack > perf.script # or use perf2bolt
82
83	# Step 3: Convert perf data
84	llvm-profgen --binary=./prog --perf-script=perf.script \
85	--output=prog.profdata
86
87	# Step 4: Optimised build
88	clang -O2 -fprofile-sample-use=prog.profdata prog.c -o prog_spgo
89	```
90
91	SamplePGO is ideal for production profiling without instrumentation overhead.
92
93	### 5. CMake integration
94
95	```cmake
96	option(PGO_INSTRUMENT "Build with PGO instrumentation" OFF)
97	option(PGO_USE "Build with PGO profile data" OFF)
98
99	if(PGO_INSTRUMENT)
100	add_compile_options(-fprofile-instr-generate)
101	add_link_options(-fprofile-instr-generate)
102	endif()
103
104	if(PGO_USE)
105	add_compile_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
106	add_link_options(-fprofile-instr-use=${CMAKE_SOURCE_DIR}/prog.profdata)
107	endif()
108	```
109
110	Build script:
111
112	```bash
113	# Phase 1: instrument
114	cmake -S . -B build-pgo-instr -DPGO_INSTRUMENT=ON -DCMAKE_BUILD_TYPE=Release
115	cmake --build build-pgo-instr -j$(nproc)
116
117	# Collect profile
118	./build-pgo-instr/prog < workload.input
119	llvm-profdata merge -output=prog.profdata *.profraw
120
121	# Phase 2: optimised
122	cmake -S . -B build-pgo -DPGO_USE=ON -DCMAKE_BUILD_TYPE=Release
123	cmake --build build-pgo -j$(nproc)
124	```
125
126	### 6. BOLT (post-link binary optimisation)
127
128	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%.
129
130	```bash
131	# Step 1: Build with relocation support
132	clang -O2 -Wl,--emit-relocs prog.c -o prog
133
134	# Step 2: Collect profile with perf
135	perf record -e cycles:u -b ./prog < workload.input
136	perf2bolt prog -p perf.data -o prog.fdata
137
138	# Or use instrumented BOLT
139	llvm-bolt prog -instrument -o prog.instr
140	./prog.instr < workload.input
141	# Generates /tmp/prof.fdata
142
143	# Step 3: Apply BOLT optimisation
144	llvm-bolt prog -data prog.fdata -o prog.bolt \
145	-reorder-blocks=ext-tsp \
146	-reorder-functions=hfsort \
147	-split-functions \
148	-split-all-cold \
149	-dyno-stats
150	```
151
152	### 7. Verifying PGO impact
153
154	```bash
155	# Compare perf of instrumented vs PGO build
156	perf stat ./prog_baseline

People who liked this also viewed

6 picks

Type