Merge pull request #1604 from jasonrandrews/review

Review Visual Studio extension for WindowsPerf Learning Path

Author: jasonrandrews

content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_index.md

@@ -1,5 +1,5 @@
 ---
-title: WindowsPerf Visual Studio extension
+title: Learn how to use the Visual Studio extension for WindowsPerf
 draft: true
 cascade:
     draft: true
@@ -13,15 +13,13 @@ learning_objectives:
   - Generate a counting report and explore the data.
   - Review the report in Windows Performance Analyzer (WPA). 
   - Generate a sample report and explore the data.
-  - Generate a sample SPE report and explore the data.
 
 prerequisites:
   - A desktop or laptop running Windows on Arm.
   - Visual Studio 2022 Community Edition, WindowsPerf, WindowsPerf Visual Studio extension, and Windows Performance Analyzer (WPA) installed. 
 
 author: 
   - Nader Zouaoui
-  - Jason Andrews
 
 ### Tags
 skilllevels: Introductory

content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/counting-feature.md

@@ -1,91 +1,53 @@
 ---
-title: The Counting Feature
-weight: 2
+title: Use the counting feature
+weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Introduction
+The Counting feature in the Visual Studio extension for WindowsPerf is a powerful tool for analyzing and optimizing your code's performance.
 
-- WindowsPerf installed [(Installation guide)](/install-guides/wperf/)
-- Visual Studio 2022 Community Edition installed [(Installation guide)](/install-guides/vs-woa/)
-- WindowsPerf Visual Studio extension installed [(Installation guide)](/install-guides/windows-perf-vs-extension/)
-- (Optional) WindowsPerf WPA plugin installed
-
-
-The Counting feature in the WindowsPerf GUI extension is a powerful tool for analyzing and optimizing your code's performance.
-This tutorial guides you through the entire process, from setting up your counting preferences to analyzing the results and interfacing with the WindowsPerf Windows
+This section guides you through the entire process, from setting up your counting preferences to analyzing the results and interfacing with the WindowsPerf Windows
 Performance Analyzer (WPA) Plugin.
 
-## How to Open Counting Settings
-
-**Accessing Counting Settings**:
-
-- In Visual Studio 2022, go to the `View` menu.
-- Select `Counting Settings` from the dropdown.
-- This action will open the Counting Settings Dialog.
-
-## Configuring the Counting Parameters
-
-1. **Filling in Necessary Fields**:
+## How do I access the counting settings? 
 
-   - The dialog presents multiple fields for configuration. Essential fields to fill in include:
-     - CPU core selection
-       > Note: if no target is selected, the CPU core selection allows for multiple
-       > cores to be selected.
-     - Event or Metric choice
-       > Note: Events can be grouped by selecting the events to group, then clicking on
-       > the `Group events` button.
-   - Fill these in according to the specifics of the counting you wish to perform.
+Open the `View` menu in Visual Studio 2022 and select `Counting Settings` from the dropdown. This opens the `Counting Settings` dialog.
 
-2. **Optional Parameters**:
+## How do I configure the counting parameters?
 
-   - You can also set other parameters as per your requirements.
+The counting settings dialog presents multiple fields for configuration. 
 
-3. **Command Preview**:
+Essential fields to fill in include:
 
-   - As you configure the settings, the dialog provides a real-time preview of the
-     WindowsPerf command that will be executed.
+- CPU core selection: you can select a subset of the CPU cores or all of them.
+- Event List and Metric List: you can select events such as `cpu_cycles` and metrics such as `dcache`.
 
-4. **Timeline Parameters**:
+{{% notice Note %}}
+Events can be grouped by selecting the events to group, then clicking on the `Group events` button.
+{{% /notice %}}
 
-The option to create a timeline is available by toggling the `Timeline` checkbox.
-You then have the option to:
+You can also set other parameters as per your requirements.
 
-- Choose the number of iterations to run the timeline (defaults to 1).
-- Choose the interval between each iteration (defaults to 0.5 second).
+As you configure the settings, the dialog provides the `WindowsPerf command preview`. This the command that will be executed.
+     
+Check the `Timeline` check box create a timeline view.  Choose the number of iterations to run the timeline (defaults to 1) and the interval between each iteration (defaults to 0.5 second).
 
-## Initiating the Counting Process
+## How do I initiate counting?
 
-1. **Starting the Counting Process**:
+To start the counting process click on the `Start` button. 
 
-   - Click on the `Start` button to kickstart the sampling.
-
-     > Note: The `Build and start` button is also available to build the solution
-     > before starting the counting process if the current project target is selected.
-
-   - If you’ve set a timeout, the process will run for the specified duration.
-     Otherwise, you have the flexibility to end the counting manually using the `Stop` button.
-
-   - The `Stop` button can also be used to interrupt the process even if the timeout
-     hasn’t lapsed and the collected counts will be shown in the table below.
+If you’ve set a timeout, the process will run for the specified duration. Otherwise, you have the flexibility to end the counting manually using the `Stop` button.
+     
+For the current code example, you will see the counted events in the `Counting Output` located in the lower section of the dialog. 
 
 ![Start Counting](./start-counting.png)
-_Counting Settings UI_
-
-## Delving into the Counting Results
-
-1. **Analyzing the Results**:
 
-   - Post-counting, you’ll notice the table in the `Counting Output` located at the
-     lower section of the Counting Settings dialog displaying the collected counts.
+## How can I analyze the results? 
 
-(**Optional**)
+You can click the `Open in WPA` button to open the collected counts in the Windows Performance Analyzer (WPA). The WindowsPerf WPA Plugin provides in-depth visualization and analysis of the results.
 
-- The option to **Open in WPA** is available to open the collected counts in the
-  Windows Performance Analyzer (WPA) using the WindowsPerf WPA Plugin for a more
-  in-depth visualization and analysis of the results.
+A screenshot of WPA is below:
 
 ![Open in WPA #center](./open-in-wpa.png)
-_WPA UI_

content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/debug.png

@@ -0,0 +1,97 @@
+---
+title: Configure your development tools
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Which development tools do I need to use WindowsPerf with Visual Studio?
+
+Four development tools are recommended if you want to use WindowsPerf for performance analysis on a Windows on Arm computer. 
+
+Each tool has an install guide explaining how to install and configure it. 
+
+Use the install guides to install and configure each tool before getting started:
+
+- [Visual Studio 2022 Community Edition](/install-guides/vs-woa/)
+- [WindowsPerf](/install-guides/wperf/)
+- [Visual Studio extension for WindowsPerf](/install-guides/windows-perf-vs-extension/)
+- [Windows Performance Analyzer (WPA) plugin](/install-guides/windows-perf-wpa-plugin/)
+
+
+## How can I try out the WindowsPerf features in Visual Studio?
+
+You can use the code example below to demonstrate WindowsPerf features in Visual Studio.
+
+Create a new C++ Console App named `App1` in Visual Studio.
+
+Remove the provided code and replace it with the code below:
+
+```C++
+#include <iostream>
+#include <vector>
+#include <chrono>
+
+const int N = 10000; // Matrix size
+
+void fillRowWise(std::vector<std::vector<int>>& matrix) {
+    for (int i = 0; i < N; ++i) {
+        for (int j = 0; j < N; ++j) {
+            matrix[i][j] = i + j;
+        }
+    }
+}
+
+void fillColumnWise(std::vector<std::vector<int>>& matrix) {
+    for (int j = 0; j < N; ++j) {
+        for (int i = 0; i < N; ++i) {
+            matrix[i][j] = i + j;
+        }
+    }
+}
+
+int main() {
+    std::vector<std::vector<int>> matrix(N, std::vector<int>(N, 0));
+
+    // Measure row-wise traversal
+    auto start = std::chrono::high_resolution_clock::now();
+    fillRowWise(matrix);
+    auto end = std::chrono::high_resolution_clock::now();
+    std::cout << "Row-wise fill time: " 
+              << std::chrono::duration_cast<std::chrono::milliseconds>(end - start).count() 
+              << " ms" << std::endl;
+
+    // Measure column-wise traversal
+    start = std::chrono::high_resolution_clock::now();
+    fillColumnWise(matrix);
+    end = std::chrono::high_resolution_clock::now();
+    std::cout << "Column-wise fill time: " 
+              << std::chrono::duration_cast<std::chrono::milliseconds>(end - start).count() 
+              << " ms" << std::endl;
+
+    return 0;
+}
+```
+
+The example code shows the difference between filling a matrix in a different order. You will see that column-wise traversal is much slower than row-wise traversal. This happens because:
+- Row-wise access follows how memory is stored in contiguous blocks.
+- Column-wise access jumps across rows, causing frequent cache misses.
+
+On the `Build` menu select `Build Solution` to generate `App1.exe`. 
+
+Run the program by opening the `Debug` menu and select `Start Without Debugging`.
+
+This will run the debug build for the program. 
+
+The console output is shown below:
+
+![Run Debug](./debug.png)
+
+Change the Visual Studio target to `Release` instead of `Debug` and build the solution again. 
+
+The console output shows shorter execution time due to compiler optimizations. 
+
+Here is the new output:
+
+![Run Release](./release.png)

content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/get-started.md

@@ -1,109 +1,86 @@
 ---
-title: The Sampling Feature
-weight: 3
+title: Use the sampling feature
+weight: 4
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Introduction
+The Sampling feature in the Visual Studio extension for WindowsPerf is a powerful tool for analyzing and optimizing your code's performance. This section guides you through the entire process, from setting up your sampling preferences to analyzing the results and implementing changes.
 
-The Sampling feature in the WindowsPerf GUI extension is a powerful tool for analyzing and optimizing your code's performance. This tutorial guides you through the entire process, from setting up your sampling preferences to analyzing the results and implementing changes.
+## How do I open the sampling explorer? 
 
-## How to Open Sampling Explorer
+Open the `View` menu in Visual Studio 2022 and select `Sampling Explorer` from the dropdown. This opens the `Sampling Explorer` dialog.
 
-1. **Accessing Sampling Explorer**:
-   - In Visual Studio 2022, go to the `View` menu.
-   - Select `Sampling Explorer` from the dropdown.
+## How do I configure the sampling preferences?
 
-## Setting Your Sampling Preferences
+From the `Sampling Explorer` window, find and click on the `Configure the sampling command` icon, it looks like a gear. This action will open the `Sampling Settings` dialog.
 
-1. **Opening Sampling Settings**:
-   - Inside the Sampling Explorer window, find and click on the `settings wheel` icon.
-   - This action will open the Sampling Settings Dialog.
+Fill in the required fields listed below:
 
-## Configuring the Sampling Parameters
+- File payload: file to profile
+- CPU core selection: cores to sample
+- Event choice: available events
+- Desired frequency: sampling frequency
 
-1. **Filling in Necessary Fields**:
+Fill in these fields with the information you want to sample. 
 
-   - The dialog presents multiple fields for configuration. Essential fields to fill in include:
-     - File payload
-     - CPU core selection
-     - Event choice
-     - Desired frequency
-   - Fill these in according to the specifics of the sampling you wish to perform.
+As you configure the settings, the dialog provides a real-time preview of the WindowsPerf command that will be executed in the `WindowsPerf Command Preview` box. 
 
-2. **Optional Parameters**:
-
-   - You can also set other parameters as per your requirements.
-
-3. **Command Preview**:
-
-   - As you configure the settings, the dialog provides a real-time preview of the WindowsPerf command that will be executed.
-
-4. **Saving Your Settings**:
-   - Once you are satisfied with your configurations, click `save`.
+When you are satisfied with your configurations, click `Save`.
 
 ![Sampling overview #center](./sampling-overview.png)
-_Sampling overview UI_
 
-## Initiating the Sampling Process
+## How do I initiate sampling?
 
-1. **Starting the Sampling**:
+To start the sampling click on the play button.
 
-   - Click on the play button to kickstart the sampling.
+If you have set a timeout, the process will run for the specified duration. Otherwise, you have the flexibility to end the sampling manually using the stop button.
 
-   - If you’ve set a timeout, the process will run for the specified duration. Otherwise, you have the flexibility to end the sampling manually using the stop button.
+The stop button can also be used to interrupt the process even if the timeout hasn’t lapsed and the collected samples will be shown in the next screen.
 
-   - The stop button can also be used to interrupt the process even if the timeout hasn’t lapsed and the collected samples will be shown in the next screen.
+## How do I view the sampling results?
 
-## Delving into the Sampling Results
+When the sampling stops, you notice the window divides into two sections: a tree view and a detailed analysis section.
 
-1. **Analyzing the Results**:
+Navigate through the tree view by clicking on the nodes. This reveals functions triggered, selected events, line numbers in the source code, and the responsible source files.
 
-   - Post-sampling, you’ll notice the window divides into two sections: a tree view and a detailed analysis section.
+Any accessible source file appears as a clickable hyperlink. Selecting it will directly open the file within the Visual Studio IDE.
 
-   - Navigate through the tree view by clicking on the nodes. This will reveal functions triggered, selected events, line numbers in the source code, and the responsible source files.
+## How do I implement code changes?
 
-   - An added convenience: Any accessible source file appears as a clickable hyperlink. Selecting it will directly open the file within the IDE.
-
-## Implementing Code Adjustments
-
-![Sampling settings #center](./sampling-settings.png)
-_Sampling settings UI_
-
-1. **Optimizing Your Code**:
-   - Based on the insights gathered from the sampling results, proceed to make any required optimizations or edits to your source code.
+Based on the insights gathered from the sampling results, proceed to make any required optimizations or edits to your source code.
 
 ![Sampling results #center](./sampling-results.png)
-_Sampling results shown in the code editor_
 
-## Re-evaluating Post Edits
+## How do I evaluate the result after making changes?
 
-1. **Comparing Results**:
+After you make code changes run the sampling process again. 
 
-   - Post editing, run the sampling process again.
+This allows you to instantly compare and contrast the results before and after your code modifications, ensuring optimal performance improvements.
 
-   - This allows you to instantly compare and contrast the results before and after your code modifications, ensuring optimal performance improvements.
+With these steps, you are well-equipped to make use of the sampling feature in the Visual Studio extension for WindowsPerf and improve code performance.
 
-   - With these steps, you are well-equipped to make the best of the sampling feature in the WindowsPerf GUI extension. Happy coding and optimizing!
+## What does lock and unlock for WindowsPerf and the kernel driver?
 
-## Lock Unlock
+When WindowsPerf communicates with the Kernel Driver, the driver acquires a lock and will deny access to other instances of WindowsPerf accessing the driver.
 
-When WindowsPerf communicates with its Kernel Driver, the driver acquires lock and will deny access to other instances of WindowsPerf accessing the driver and its resources. This prevents others from interfering with the current WindowsPerf execution and protects you from interference with your count.
+This prevents others from interfering with the current WindowsPerf execution and protects you from interference with your counting.
 
-When another WindowsPerf process has “locked” access to the driver you will no longer be able to use WindowsPerf, you will instead receive the following error message:
+When another WindowsPerf process has locked access to the driver you will no longer be able to use WindowsPerf, you will instead receive the following error message:
 
-```shell
+```output
 warning: other WindowsPerf process acquired the WindowsPerf-driver.
 Operation canceled!
 ```
 
-In order to force the release of the lock, a new --force-lock command argument was introduced to both WindowsPerf and the extension that lets you interrupt the ongoing WindowsPerf process and take over the lock.
+In order to force the release of the lock, a new --force-lock command argument is available for both WindowsPerf and the Visual Studio extension that allows you to interrupt the ongoing WindowsPerf process and take over the lock.
+
+However, interrupting a running `wperf` process results in loss of collected data. 
 
-However, interrupting a running wperf process would result in losing all the collected data. If interrupted, WidowsPerf will show the following error message:
+If interrupted, WidowsPerf will show the following error message:
 
-```shell
+```output
 warning: other WindowsPerf process hijacked (forced lock) the wperf-driver, see --force-lock.
 Operation terminated, your data was lost!
 

content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/release.png

@@ -1,6 +1,7 @@
 ---
 title: The SPE Feature
-weight: 4
+weight: 5
+draft: true
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall