Merge pull request #2581 from tdunkleArm/add-windows-instructions-to-cpp-pgo-path

Add Learning Path for profile guided optimization (PGO) on Windows.

Author: jasonrandrews

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

@@ -0,0 +1,46 @@
+---
+title: Optimize C++ performance with Profile-Guided Optimization and Google Benchmark
+
+minutes_to_complete: 15
+
+who_is_this_for: Developers looking to optimize C++ performance on an Arm-based Windows device, based on runtime behavior.
+
+learning_objectives: 
+    - Microbenchmark a function using Google Benchmark.
+    - Apply profile-guided optimization to build performance-tuned binaries for Windows on Arm.
+
+prerequisites:
+    - Basic C++ understanding.
+    - Access to an Arm-based Windows machine.
+
+author: Tom Dunkle
+
+### Tags
+skilllevels: Introductory
+subjects: ML
+armips:
+    - Neoverse
+tools_software_languages:
+    - Google Benchmark
+    - Runbook
+operatingsystems:
+    - Windows
+
+further_reading:
+    - resource:
+        title: MSVC profile-guided optimization documentation
+        link: https://learn.microsoft.com/en-us/cpp/build/profile-guided-optimizations?view=msvc-170
+        type: documentation
+    - resource:
+        title: Google Benchmark Library 
+        link: https://github.com/google/benchmark
+        type: documentation
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

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

@@ -0,0 +1,26 @@
+---
+title: Profile-Guided Optimization
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### What is Profile-Guided Optimization (PGO) and how does it work?
+
+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: 
+
+- 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.
+
+### When should I use Profile-Guided Optimization?
+
+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.
+
+### What are the limitations of Profile-Guided Optimization and when should I avoid it?
+
+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.
+
+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 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.

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

@@ -0,0 +1,45 @@
+---
+title: Google Benchmark
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Google Benchmark
+
+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 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.
+
+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.
+
+Here's a basic example:
+
+```cpp
+#include <benchmark/benchmark.h>
+
+static void BM_StringCreation(benchmark::State& state) {
+  for (auto _ : state)
+    std::string empty_string;
+}
+BENCHMARK(BM_StringCreation);
+
+BENCHMARK_MAIN();
+```
+
+### Filtering and Preventing 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:
+
+   ```bash
+   .\benchmark_binary --benchmark_filter=BM_String.*
+   ```
+   
+This eliminates the need to repeatedly comment out lines of source code.
+
+For more detailed information and advanced usage, refer to the [official documentation](https://github.com/google/benchmark).

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

@@ -0,0 +1,87 @@
+---
+title: Example operation
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Optimizing costly division operations with Google Benchmark and PGO
+
+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, we can potentially achieve significant performance improvements.
+
+For this example, you can use an Arm computer running Windows.
+
+## What tools are needed to run a Google Benchmark example on Windows?
+
+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:
+
+```console
+cd C:\git
+git clone https://github.com/microsoft/vcpkg.git
+cd vcpkg
+.\bootstrap-vcpkg.bat
+.\vcpkg install benchmark:arm64-windows-static
+```
+
+## Division example
+
+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.
+
+```cpp
+#include <benchmark/benchmark.h>
+#include <vector>
+
+// Benchmark division instruction
+static void baseDiv(benchmark::State &s) {
+  std::vector<int> v_in(4096);
+  std::vector<int> v_out(4096);
+
+  for (auto _ : s) {
+    for (size_t i = 0; i < v_in.size(); i++) v_out[i] = v_in[i] / s.range(0);
+    // s.range(0) is unknown at compile time, cannot be reduced
+  }
+}
+
+BENCHMARK(baseDiv)->Arg(1500)->Unit(benchmark::kMicrosecond); // value of 1500 is passed through as an argument so strength reduction cannot be applied
+
+BENCHMARK_MAIN();
+```
+
+To compile and run the microbenchmark on this function, you need to link with the correct libraries:
+
+Compile with the command:
+
+```console
+cl /D BENCHMARK_STATIC_DEFINE div_bench.cpp /link /LIBPATH:"$VCPKG\lib" benchmark.lib benchmark_main.lib shlwapi.lib
+```
+
+Run the program:
+
+```console
+.\div_bench.exe
+```
+
+### Example output
+
+```output
+Running ./div_bench.base
+Run on (4 X 2100 MHz CPU s)
+CPU Caches:
+  L1 Data 64 KiB (x4)
+  L1 Instruction 64 KiB (x4)
+  L2 Unified 1024 KiB (x4)
+  L3 Unified 32768 KiB (x1)
+Load Average: 0.00, 0.00, 0.00
+***WARNING*** Library was built as DEBUG. Timings may be affected.
+-------------------------------------------------------
+Benchmark             Time             CPU   Iterations
+-------------------------------------------------------
+baseDiv/1500       7.90 us         7.90 us        88512
+```

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

@@ -0,0 +1,89 @@
+---
+title: Using Profile Guided Optimization (Windows)
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### Build with PGO
+
+To generate a binary optimized using runtime profile data, first build an instrumented binary that records usage data. Before building, open the Arm dev shell so that the compiler is in your PATH:
+
+```console
+& "C:\Program Files\Microsoft Visual Studio\18\Community\Common7\Tools\Launch-VsDevShell.ps1" -Arch arm64
+```
+
+(**note:** you may need to change the version number in your Visual Studio path, depending on which Visual Studio version you've installed.)
+
+Next, set an environment variable to refer to the installed packages directory:
+
+```console
+$VCPKG="C:\git\vcpkg\installed\arm64-windows-static"
+```
+
+Next, run the following command, which includes the `/GENPROFILE` flag, to build the instrumented binary:
+
+```console
+cl /O2 /GL /D BENCHMARK_STATIC_DEFINE /I "$VCPKG\include" /Fe:div_bench.exe div_bench.cpp /link /LTCG /GENPROFILE /PGD:div_bench.pgd /LIBPATH:"$VCPKG\lib" benchmark.lib benchmark_main.lib shlwapi.lib
+```
+
+The compiler options used in this command are:
+
+* **/O2**: Creates [fast code](https://learn.microsoft.com/en-us/cpp/build/reference/o1-o2-minimize-size-maximize-speed?view=msvc-170)
+* **/GL**: Enables [whole program optimization](https://learn.microsoft.com/en-us/cpp/build/reference/gl-whole-program-optimization?view=msvc-170).
+* **/D**: Enables the Benchmark [static preprocessor definition](https://learn.microsoft.com/en-us/cpp/build/reference/d-preprocessor-definitions?view=msvc-170).
+* **/I**: Adds the arm64 includes to the [list of include directories](https://learn.microsoft.com/en-us/cpp/build/reference/i-additional-include-directories?view=msvc-170).
+* **/Fe**: Specifies a name for the [executable file output](https://learn.microsoft.com/en-us/cpp/build/reference/fe-name-exe-file?view=msvc-170).
+* **/link**: Specifies [options to pass to linker](https://learn.microsoft.com/en-us/cpp/build/reference/link-pass-options-to-linker?view=msvc-170).
+
+The linker options used in this command are:
+
+* **/LTCG**: Specifies [link time code generation](https://learn.microsoft.com/en-us/cpp/build/reference/ltcg-link-time-code-generation?view=msvc-170).
+* **/GENPROFILE**: Specifies [generation of a .pgd file for PGO](https://learn.microsoft.com/en-us/cpp/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build?view=msvc-170).
+* **/PGD**: Specifies a [database for PGO](https://learn.microsoft.com/en-us/cpp/build/reference/pgd-specify-database-for-profile-guided-optimizations?view=msvc-170).
+* **/LIBPATH**: Specifies the [additional library path](https://learn.microsoft.com/en-us/cpp/build/reference/libpath-additional-libpath?view=msvc-170).
+
+Next, run the instrumented binary to generate the profile data:
+
+```console
+.\div_bench.exe
+```
+
+This execution creates profile data files (typically with a `.pgc` extension) in the same directory. 
+
+Now recompile the program using the `/USEPROFILE` flag to apply optimizations based on the collected data: 
+
+```console
+cl /O2 /GL /D BENCHMARK_STATIC_DEFINE /I "$VCPKG\include" /Fe:div_bench_opt.exe div_bench.cpp /link /LTCG:PGOptimize /USEPROFILE /PGD:div_bench.pgd /LIBPATH:"$VCPKG\lib" benchmark.lib benchmark_main.lib shlwapi.lib
+```
+
+In this command, the [USEPROFILE linker option](https://learn.microsoft.com/en-us/cpp/build/reference/useprofile?view=msvc-170) instructs the linker to enable PGO with the profile generated during the previous run of the executable. 
+
+### Run the optimized binary 
+
+Now run the optimized binary:
+
+```console
+.\div_bench_opt.exe
+```
+
+The following output shows the performance improvement:
+
+```output
+Running ./div_bench.opt
+Run on (4 X 2100 MHz CPU s)
+CPU Caches:
+  L1 Data 64 KiB (x4)
+  L1 Instruction 64 KiB (x4)
+  L2 Unified 1024 KiB (x4)
+  L3 Unified 32768 KiB (x1)
+Load Average: 0.10, 0.03, 0.01
+***WARNING*** Library was built as DEBUG. Timings may be affected.
+-------------------------------------------------------
+Benchmark             Time             CPU   Iterations
+-------------------------------------------------------
+baseDiv/1500       2.86 us         2.86 us       244429
+```
+
+As the terminal output above shows, the average execution time is reduced from 7.90 to 2.86 microseconds. This improvement occurs because the profile data informed the compiler that the input divisor was consistently 1500 during the profiled runs, allowing it to apply specific optimizations.