Merge pull request #2934 from jasonrandrews/review2

Tech review for PGO on Windows Learning Path

Author: jasonrandrews

content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/_index.md

@@ -1,34 +1,37 @@
 ---
-title: Optimize C++ performance with Profile-Guided Optimization and Google Benchmark
+title: Optimize C++ applications on Windows on Arm using Profile-Guided Optimization
 
 draft: true
 cascade:
     draft: true
 
-minutes_to_complete: 15
+minutes_to_complete: 30
 
-who_is_this_for: Developers looking to optimize C++ performance on an Arm-based Windows device, based on runtime behavior.
+who_is_this_for: This is an introductory topic for software developers who want to optimize C++ application performance on Windows on Arm using profile-guided optimization.
 
 learning_objectives: 
     - Microbenchmark a function using Google Benchmark.
     - Apply profile-guided optimization to build performance-tuned binaries for Windows on Arm.
+    - Measure and compare performance improvements from PGO-optimized builds.
 
 prerequisites:
     - Basic C++ understanding.
-    - Access to an Arm-based Windows machine.
+    - A Windows on Arm machine with [Visual Studio](/install-guides/vs-woa/) and the C++ desktop development tools installed.
 
 author: Tom Dunkle
 
 ### Tags
 skilllevels: Introductory
-subjects: ML
-armips:
-    - Neoverse
+subjects: Performance and Architecture
 tools_software_languages:
+    - C
+    - MSVC
     - Google Benchmark
-    - Runbook
+    - PGO
 operatingsystems:
     - Windows
+armips:
+    - Cortex-A
 
 further_reading:
     - resource:
@@ -39,6 +42,14 @@ further_reading:
         title: Google Benchmark Library 
         link: https://github.com/google/benchmark
         type: documentation
+    - resource:
+        title: Windows on Arm developer documentation
+        link: https://learn.microsoft.com/en-us/windows/arm/overview
+        type: documentation
+    - resource:
+        title: Arm Performance optimization resources
+        link: https://learn.arm.com/learning-paths/laptops-and-desktops/
+        type: website
 
 
 

content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-1.md

@@ -6,21 +6,36 @@ weight: 2
 layout: learningpathall
 ---
 
-### What is Profile-Guided Optimization (PGO) and how does it work?
+## What is Profile-Guided Optimization?
 
-Profile-Guided Optimization (PGO) is a compiler optimization technique that enhances program performance by utilizing real-world execution data. PGO typically involves a two-step process: 
+Profile-Guided Optimization (PGO) is a compiler optimization technique that enhances your program's performance by using real-world execution data. PGO works in two steps: 
 
-- First, compile the program to produce an instrumented binary that collects profiling data during execution; 
-- Second, recompile the program with an optimization profile, allowing the compiler to leverage the collected data to make informed optimization decisions. This approach identifies frequently executed paths — known as “hot” paths — and optimizes them more aggressively, while potentially reducing emphasis on less critical code paths.
+First, you compile your program to produce an instrumented binary that collects profiling data during execution. Second, you recompile the program with this optimization profile, allowing the compiler to make informed optimization decisions based on the collected data.
 
-### When should I use Profile-Guided Optimization?
+This approach identifies frequently executed paths (known as "hot" paths) and optimizes them more aggressively, while reducing emphasis on less critical code paths.
 
-PGO is particularly beneficial in the later stages of development when real-world workloads are available. It is especially useful for applications where performance is critical and runtime behavior is complex or data-dependent. For instance, consider optimizing “hot” functions that execute frequently. Doing so ensures that the most impactful parts of your code are optimized based on actual usage patterns.
+## How does PGO improve performance?
 
-### What are the limitations of Profile-Guided Optimization and when should I avoid it?
+PGO enables several compiler optimizations that aren't possible with static analysis alone.
 
-While PGO offers substantial performance benefits, it has limitations. The profiling data must accurately represent typical usage scenarios; otherwise, the optimizations may not deliver the desired performance improvements and could even degrade performance.
+The compiler arranges frequently executed code together in memory through code layout optimization, which improves instruction cache utilization and reduces branch mispredictions. Instead of using heuristics for inlining decisions, the compiler inlines functions based on actual call frequency and execution patterns from your profiling data.
 
-Additionally, the process requires extra build steps, potentially increasing compile times for large codebases. Therefore, use PGO only on performance-critical sections that are heavily influenced by actual runtime behavior. PGO might not be ideal for early-stage development or applications with highly variable or unpredictable usage patterns.
+For C++ virtual functions, PGO can identify the most common call targets and optimize or devirtualize those paths. The compiler can also eliminate dead code by optimizing differently or removing code paths that never execute in your profiling runs.
 
-For further information, see the [MSVC documentation](https://learn.microsoft.com/en-us/cpp/build/profile-guided-optimizations?view=msvc-170) on enabling and using PGO.
+For example, if your application has an error handling path that rarely executes, PGO ensures the compiler doesn't optimize for that path at the expense of your main execution flow. The result is typically 5-15% performance improvement, though gains vary by application.
+
+## When should you use Profile-Guided Optimization?
+
+You'll find PGO particularly beneficial in the later stages of development when real-world workloads are available. It's especially useful for applications where performance is critical and runtime behavior is complex or data-dependent.
+
+For example, consider optimizing "hot" functions that execute frequently. By doing so, you ensure that the most impactful parts of your code are optimized based on actual usage patterns.
+
+## Limitations of Profile-Guided Optimization
+
+While PGO offers substantial performance benefits, it has some limitations to keep in mind.
+
+Your profiling data must accurately represent typical usage scenarios. If it doesn't, the optimizations might not deliver the desired performance improvements and could even degrade performance.
+
+Additionally, the process requires extra build steps, which can increase compile times for large codebases. Use PGO on performance-critical sections that are heavily influenced by actual runtime behavior.
+
+PGO might not be ideal for early-stage development or applications with highly variable or unpredictable usage patterns.

content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-2.md

@@ -1,20 +1,20 @@
 ---
-title: Google Benchmark
+title: Understand Google Benchmark basics
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Google Benchmark
+Before you start working with Profile-Guided Optimization, you need to understand how to measure performance. This section introduces Google Benchmark, the tool you'll use to measure the impact of your optimizations. Don't worry about installing anything yet. You'll set up your environment and run your first benchmark in the next section.
 
-Google Benchmark is a C++ library specifically designed for microbenchmarking – measuring the performance of small code snippets with high accuracy. Microbenchmarking is essential for identifying bottlenecks and optimizing critical sections, especially in performance-sensitive applications. 
+Google Benchmark is a C++ library specifically designed for microbenchmarking, which means measuring the performance of small code snippets with high accuracy. Microbenchmarking helps you identify bottlenecks and optimize critical sections, especially in performance-sensitive applications. 
 
-Google Benchmark simplifies this process by providing a framework that manages iterations, times execution, and performs statistical analysis. This allows you to focus on the code being measured, rather than writing boilerplate or trying to prevent unwanted compiler optimizations manually.
+Google Benchmark simplifies this process by providing a framework that manages iterations, times execution, and performs statistical analysis. This lets you focus on the code being measured, rather than writing test code or trying to prevent unwanted compiler optimizations manually.
 
-To use Google Benchmark, define a function that accepts a `benchmark::State&` parameter and iterate over it to perform the benchmarking. Register the function using the `BENCHMARK` macro and include `BENCHMARK_MAIN()` to generate the benchmark's entry point.
+To use Google Benchmark, you define a function that accepts a `benchmark::State&` parameter and iterate over it to perform the benchmarking. You register the function using the `BENCHMARK` macro and include `BENCHMARK_MAIN()` to generate the benchmark's entry point.
 
-Here's a basic example:
+This example shows a basic benchmark that measures the time it takes to create an empty string:
 
 ```cpp
 #include <benchmark/benchmark.h>
@@ -28,18 +28,18 @@ BENCHMARK(BM_StringCreation);
 BENCHMARK_MAIN();
 ```
 
-### Filtering and Preventing Compiler Optimizations
+## Filter benchmarks and prevent compiler optimizations
 
 Google Benchmark provides tools to ensure accurate measurements by preventing unintended compiler optimizations and allowing flexible benchmark selection.
 
-1. **Preventing Optimizations**: Use `benchmark::DoNotOptimize(value);` to force the compiler to read and store a variable or expression, ensuring it is not optimized away.
-   
-2. **Filtering Benchmarks**: To run a specific subset of benchmarks, use the `--benchmark_filter` command-line option with a regular expression. For example:
+To prevent the compiler from optimizing away your code, use `benchmark::DoNotOptimize(value);` to force the compiler to read and store a variable or expression. This ensures your benchmark actually measures what you intend to measure.
 
-   ```bash
-   .\benchmark_binary --benchmark_filter=BM_String.*
-   ```
-   
-This eliminates the need to repeatedly comment out lines of source code.
+When you have multiple benchmarks, you can run a specific subset using the `--benchmark_filter` command-line option with a regular expression. This example runs all benchmarks that start with "BM_String":
 
-For more detailed information and advanced usage, refer to the [official documentation](https://github.com/google/benchmark).
+```console
+.\benchmark_binary --benchmark_filter=BM_String.*
+```
+
+This approach eliminates the need to repeatedly comment out lines of source code when you want to focus on specific benchmarks.
+
+Now that you understand how Google Benchmark works, you're ready to install it and run your first benchmark. In the next section, you'll set up your environment and use Google Benchmark with Profile-Guided Optimization to measure and improve performance.

content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-3.md

@@ -1,38 +1,38 @@
 ---
-title: Example operation
+title: Create a baseline benchmark
 weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Optimizing costly division operations with Google Benchmark and PGO
+In this section, you'll create a baseline benchmark to measure the performance of a division operation. This baseline will help you see the improvement when you apply Profile-Guided Optimization in the next section. This example demonstrates how even seemingly straightforward operations can benefit from optimization techniques.
 
-In this section, you'll learn how to use Google Benchmark and Profile-Guided Optimization to improve the performance of a simple division operation. This example demonstrates how even seemingly straightforward operations can benefit from optimization techniques.
+Integer division is ideal for benchmarking because it's significantly more expensive than operations like addition, subtraction, or multiplication. On most CPU architectures, including Arm, division instructions have higher latency and lower throughput compared to other arithmetic operations. By applying Profile-Guided Optimization to code containing division operations, you can achieve significant performance improvements.
 
-Integer division is ideal for benchmarking because it's significantly more expensive than operations like addition, subtraction, or multiplication. On most CPU architectures, including Arm, division instructions have higher latency and lower throughput compared to other arithmetic operations. By applying Profile-Guided Optimization to code containing division operations, we can potentially achieve significant performance improvements.
+For this example, you'll use an Arm computer running Windows.
 
-For this example, you can use an Arm computer running Windows.
+## Install the required tools
 
-## What tools are needed to run a Google Benchmark example on Windows?
+### Install vcpkg and Google Benchmark
 
-Download the [Arm GNU Toolchain](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) to install the prerequisite packages.
-
-Next, install the static version of Google Benchmark for Arm64 via vcpkg. Run the following commands in Powershell as Administrator:
+Run the following commands in PowerShell:
 
 ```console
-cd C:\git
-git clone https://github.com/microsoft/vcpkg.git
-cd vcpkg
-.\bootstrap-vcpkg.bat
-.\vcpkg install benchmark:arm64-windows-static
+iex (iwr -useb https://aka.ms/vcpkg-init.ps1)
+cd $HOME
+mkdir pgo-benchmark
+cd pgo-benchmark
+& "$HOME\.vcpkg\vcpkg.exe" new --application
+& "$HOME\.vcpkg\vcpkg.exe" add port benchmark
+& "$HOME\.vcpkg\vcpkg.exe" install
 ```
 
-## Division example
+## Create the division benchmark
 
 Use an editor to copy and paste the C++ source code below into a file named `div_bench.cpp`.
 
-This trivial example takes in a vector of 4096 32-bit integers and divides each element by a number. Importantly, the use of `benchmark/benchmark.h` introduces indirection since the divisor value is unknown at compile time, although it is visible in the source code as 1500.
+This example takes a vector of 4096 32-bit integers and divides each element by a number. The key detail here is that the divisor value is passed through `s.range(0)`, making it unknown at compile time. This prevents the compiler from applying optimizations like strength reduction, which means PGO will have an opportunity to make a real difference.
 
 ```cpp
 #include <benchmark/benchmark.h>
@@ -54,21 +54,34 @@ BENCHMARK(baseDiv)->Arg(1500)->Unit(benchmark::kMicrosecond); // value of 1500 i
 BENCHMARK_MAIN();
 ```
 
-To compile and run the microbenchmark on this function, you need to link with the correct libraries:
+## Compile and run the baseline benchmark
+
+Open an **ARM64 Native Tools Command Prompt** from the Windows Start menu and start PowerShell:
+
+```console
+powershell
+```
+
+Before compiling, set an environment variable to refer to the vcpkg installation directory:
 
-Compile with the command:
+```console
+$VCPKG="$HOME\pgo-benchmark\vcpkg_installed\arm64-windows"
+```
+
+Now compile the benchmark. This command uses the MSVC compiler and links with the Google Benchmark libraries:
 
 ```console
-cl /D BENCHMARK_STATIC_DEFINE div_bench.cpp /link /LIBPATH:"$VCPKG\lib" benchmark.lib benchmark_main.lib shlwapi.lib
+cl /I"$VCPKG\include" /D BENCHMARK_STATIC_DEFINE div_bench.cpp /link /LIBPATH:"$VCPKG\lib" benchmark.lib benchmark_main.lib shlwapi.lib
 ```
 
-Run the program:
+Run the program to establish your baseline performance:
 
 ```console
+$env:PATH += ";$HOME\pgo-benchmark\vcpkg_installed\arm64-windows\bin"
 .\div_bench.exe
 ```
 
-### Example output
+The output is similar to:
 
 ```output
 Running ./div_bench.base
@@ -85,3 +98,5 @@ Benchmark             Time             CPU   Iterations
 -------------------------------------------------------
 baseDiv/1500       7.90 us         7.90 us        88512
 ```
+
+The baseline shows an average execution time of 7.90 microseconds. This gives you a clear starting point to measure improvement. Now that you have this baseline measurement, you're ready to apply Profile-Guided Optimization. In the next section, you'll use PGO to optimize this code and see how much faster it can run.