Merge branch 'ArmDeveloperEcosystem:main' into nvda

madeline-underwood · web-flow · commit ec46f0376115 · 2026-02-27T15:27:51.000Z
diff --git a/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/_index.md b/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/_index.md
@@ -1,22 +1,18 @@
 ---
 title: Optimize C++ applications on Windows on Arm using Profile-Guided Optimization
 
-draft: true
-cascade:
-    draft: true
-
 minutes_to_complete: 30
 
-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.
+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 (PGO).
 
 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.
+    - 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.
-    - A Windows on Arm machine with [Visual Studio](/install-guides/vs-woa/) and the C++ desktop development tools installed.
+    - Familiarity with C++ development and compiling programs from the command line
+    - A Windows on Arm machine with [Visual Studio](/install-guides/vs-woa/) and the C++ desktop development tools installed
 
 author: Tom Dunkle
 
@@ -47,7 +43,7 @@ further_reading:
         link: https://learn.microsoft.com/en-us/windows/arm/overview
         type: documentation
     - resource:
-        title: Arm Performance optimization resources
+        title: Arm performance optimization resources
         link: https://learn.arm.com/learning-paths/laptops-and-desktops/
         type: website
 
diff --git a/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-1.md b/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-1.md
@@ -1,5 +1,5 @@
 ---
-title: Profile-Guided Optimization
+title: Understand Profile-Guided Optimization
 weight: 2
 
 ### FIXED, DO NOT MODIFY
@@ -14,17 +14,17 @@ First, you compile your program to produce an instrumented binary that collects
 
 This approach identifies frequently executed paths (known as "hot" paths) and optimizes them more aggressively, while reducing emphasis on less critical code paths.
 
-## How does PGO improve performance?
+## How PGO improves performance on Windows on Arm
 
 PGO enables several compiler optimizations that aren't possible with static analysis alone.
 
-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.
+Code layout optimization arranges frequently executed code together in memory, improving instruction cache utilization and reducing 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.
 
 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 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.
+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. Performance improvements typically range from 5-15%, though results vary by workload and architecture.
 
-## When should you use Profile-Guided Optimization?
+## When to use PGO on Arm
 
 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.
 
@@ -39,3 +39,7 @@ Your profiling data must accurately represent typical usage scenarios. If it doe
 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.
+
+## What you've accomplished and what's next
+
+You now understand what PGO is, how it improves performance through code layout and inlining optimizations, and when to apply it. In the next section, you'll learn about Google Benchmark, the tool you'll use to measure these performance improvements.
diff --git a/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-2.md b/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-2.md
@@ -6,15 +6,21 @@ weight: 3
 layout: learningpathall
 ---
 
+## Overview
+
 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.
 
+## What is Google Benchmark?
+
 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 lets you focus on the code being measured, rather than writing test code 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. You can focus on the code being measured, rather than writing test code or trying to prevent unwanted compiler optimizations manually.
 
-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.
+## Write a simple benchmark
 
-This example shows a basic benchmark that measures the time it takes to create an empty string:
+To use Google Benchmark, define a function that accepts a benchmark::State& parameter and use it to run the benchmark in a loop. You register the function using the `BENCHMARK` macro and include `BENCHMARK_MAIN()` to generate the benchmark's entry point.
+
+The following example shows a basic benchmark that measures the time it takes to create an empty string. A minimal benchmark looks like this:
 
 ```cpp
 #include <benchmark/benchmark.h>
@@ -28,7 +34,7 @@ BENCHMARK(BM_StringCreation);
 BENCHMARK_MAIN();
 ```
 
-## Filter benchmarks and prevent compiler optimizations
+## Control benchmark execution
 
 Google Benchmark provides tools to ensure accurate measurements by preventing unintended compiler optimizations and allowing flexible benchmark selection.
 
@@ -40,6 +46,8 @@ When you have multiple benchmarks, you can run a specific subset using the `--be
 .\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.
+Filtering eliminates the need to repeatedly comment out lines of source code when you want to focus on specific benchmarks.
+
+## What you've accomplished and what's next
 
-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.
+You now understand how to write basic benchmarks with Google Benchmark, use `benchmark::DoNotOptimize` to prevent unwanted compiler optimizations, and filter benchmark execution with command-line options. In the next section, you'll install Google Benchmark and create a baseline benchmark to measure division performance on Windows on Arm.
diff --git a/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-3.md b/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-3.md
@@ -6,17 +6,21 @@ weight: 4
 layout: learningpathall
 ---
 
-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.
+## Overview
+
+In this section, you'll create a baseline benchmark to measure the performance of a division operation. This baseline allows you to measure the improvement when you apply profile-guided optimization in the next section.
 
 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.
 
 For this example, you'll use an Arm computer running Windows.
 
-## Install the required tools
+## Set up Google Benchmark on Windows on Arm
+
+Before you can run benchmarks, you need to install vcpkg (a C++ package manager) and Google Benchmark. This is a one-time setup step.
 
 ### Install vcpkg and Google Benchmark
 
-Run the following commands in PowerShell:
+The following commands download and initialize vcpkg, create a project directory, and install Google Benchmark for Windows on Arm:
 
 ```console
 iex (iwr -useb https://aka.ms/vcpkg-init.ps1)
@@ -54,27 +58,29 @@ BENCHMARK(baseDiv)->Arg(1500)->Unit(benchmark::kMicrosecond); // value of 1500 i
 BENCHMARK_MAIN();
 ```
 
-## Compile and run the baseline benchmark
+## Compile the baseline benchmark with MSVC
 
 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:
+Set an environment variable to refer to the vcpkg-installed package directory for the ARM64 Windows target. This simplifies the compiler commands that follow:
 
 ```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:
+Compile the benchmark. This command uses the MSVC compiler and links with the Google Benchmark libraries:
 
 ```console
 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 to establish your baseline performance:
+## Run the benchmark
+
+Add the vcpkg binary directory to your PATH so the program can find required DLLs, then run the benchmark:
 
 ```console
 $env:PATH += ";$HOME\pgo-benchmark\vcpkg_installed\arm64-windows\bin"
@@ -84,7 +90,7 @@ $env:PATH += ";$HOME\pgo-benchmark\vcpkg_installed\arm64-windows\bin"
 The output is similar to:
 
 ```output
-Running ./div_bench.base
+Running ./div_bench.exe
 Run on (4 X 2100 MHz CPU s)
 CPU Caches:
   L1 Data 64 KiB (x4)
@@ -99,4 +105,8 @@ 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.
+The warning appears because the Google Benchmark library was built in debug mode, but it doesn't affect the validity of the measurements for this example.
+
+## What you've accomplished and what's next
+
+You've set up Google Benchmark on Windows on Arm, created a division-heavy benchmark, and established a baseline performance measurement of 7.90 microseconds. This baseline gives you a clear reference point to measure the impact of Profile-Guided Optimization. In the next section, you'll apply PGO to this code and measure the performance improvement.
diff --git a/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-4.md b/content/learning-paths/laptops-and-desktops/win_profile_guided_optimisation/how-to-4.md
@@ -6,11 +6,19 @@ weight: 5
 layout: learningpathall
 ---
 
+## Overview
+
 Now that you have a baseline benchmark, you're ready to apply Profile-Guided Optimization. The PGO process involves three steps: build an instrumented binary, run it to collect profile data, and rebuild with optimizations based on that data.
 
-## Build the instrumented binary
+## Build instrumented binary with MSVC
+
+Open an **ARM64 Native Tools Command Prompt** from the Windows Start menu and start PowerShell if it's not already open. If you're starting a new session, navigate to your project directory and set the `$VCPKG` environment variable again:
 
-You should already have an ARM64 Native Tools Command Prompt open with PowerShell running from the previous section.
+```console
+powershell
+cd $HOME\pgo-benchmark
+$VCPKG="$HOME\pgo-benchmark\vcpkg_installed\arm64-windows"
+```
 
 Build the instrumented binary with the `/GENPROFILE` flag. This creates a version of your program that records how it executes:
 
@@ -20,7 +28,7 @@ cl /O2 /GL /D BENCHMARK_STATIC_DEFINE /I "$VCPKG\include" /Fe:div_bench.exe div_
 
 This command uses several important compiler and linker options. The `/O2` flag creates fast code, while `/GL` enables whole program optimization. The `/GENPROFILE` linker option generates a `.pgd` file for PGO, and `/LTCG` specifies link time code generation. The `/PGD` option specifies the database file where profile data will be stored.
 
-## Collect profile data
+## Collect PGO profile data on Windows on Arm
 
 Run the instrumented binary to generate profile data:
 
@@ -30,7 +38,7 @@ Run the instrumented binary to generate profile data:
 
 This execution creates profile data files (typically with a `.pgc` extension) in the same directory. The profile data captures information about which code paths execute most frequently and how the program behaves at runtime.
 
-## Rebuild with optimizations
+## Rebuild with PGO optimizations
 
 Now recompile the program using the `/USEPROFILE` flag to apply optimizations based on the collected data:
 
@@ -40,7 +48,7 @@ cl /O2 /GL /D BENCHMARK_STATIC_DEFINE /I "$VCPKG\include" /Fe:div_bench_opt.exe
 
 The `/USEPROFILE` linker option instructs the linker to enable PGO with the profile generated during the previous run. The compiler can now make informed decisions about code layout, inlining, and other optimizations based on actual runtime behavior.
 
-## Measure the improvement
+## Measure PGO performance gains
 
 Run the optimized binary to see the performance improvement:
 
@@ -66,6 +74,12 @@ Benchmark             Time             CPU   Iterations
 baseDiv/1500       2.86 us         2.86 us       244429
 ```
 
-The average execution time is reduced from 7.90 to 2.86 microseconds, which is a 64% improvement. This significant gain 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 that wouldn't be possible with static analysis alone.
+The warning appears because the Google Benchmark library was built in debug mode, but it doesn't affect the validity of the measurements.
+
+The average execution time is reduced from 7.90 to 2.86 microseconds, which is a 64% improvement. This result was measured on a Windows on Arm device with Visual Studio 2022 (MSVC 17.0) using the division benchmark with a constant divisor of 1500. Your results may vary depending on your specific hardware and workload.
+
+The compiler used the profile data to determine that the divisor was consistently 1500, enabling optimizations that wouldn't be possible with static analysis alone.
+
+## What you've accomplished
 
-You've successfully used Profile-Guided Optimization to improve performance on Windows on Arm. This same technique can be applied to your own performance-critical code to achieve similar improvements.
+You've applied PGO to reduce execution time by 64% on a division-heavy benchmark. You completed the full PGO workflow: instrument, profile, and optimize. Apply this same technique to performance-critical sections of your own code to achieve similar gains on Windows on Arm.
