Merge pull request #1335 from nader-zouaoui/windowsPerf-vs-extension-lp

docs: add full tutorial list to WindowsPerf vs extension

Author: jasonrandrews

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

@@ -0,0 +1,41 @@
+---
+title: WindowsPerf Visual Studio extension
+
+minutes_to_complete: 30
+
+who_is_this_for: WindowsPerf users who want to integrate WindowsPerf into their development flow.
+
+learning_objectives:
+  - Learn how to use the WindowsPerf Visual Studio extension
+  - Generate a counting report and explore the data
+  - (Optional) 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:
+  - Windows on Arm desktop or development machine
+  - 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
+
+author_primary: Nader Zouaoui
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+  - Cortex-A
+operatingsystems:
+  - Windows
+tools_software_languages:
+  - WindowsPerf
+  - perf
+  - Visual Studio
+
+### 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/windowsperf-vs-extension/_index.md

@@ -0,0 +1,42 @@
+---
+next_step_guidance: Now that you have an idea of how the extensin works, You can try exploring the WindowsPerf CLI for more flexibility.
+
+recommended_path: "/learning-paths/laptops-and-desktops/windowsperf_sampling_cpython"
+
+further_reading:
+  - resource:
+      title: Announcing WindowsPerf Open-source performance analysis tool for Windows on Arm
+      link: https://community.arm.com/arm-community-blogs/b/infrastructure-solutions-blog/posts/announcing-windowsperf
+      type: blog
+  - resource:
+      title: WindowsPerf Release 3.7.2
+      link: https://www.linaro.org/blog/expanding-profiling-capabilities-with-windowsperf-372-release/
+      type: blog
+  - resource:
+      title: WindowsPerf Visual Studio Extension v2.1.0
+      link: https://www.linaro.org/blog/launching--windowsperf-visual-studio-extension-v210/
+      type: blog
+  - resource:
+      title: Windows on Arm overview
+      link: https://learn.microsoft.com/en-us/windows/arm/overview
+      type: website
+  - resource:
+      title: Linaro Windows on Arm project
+      link: https://www.linaro.org/windows-on-arm/
+      type: website
+  - resource:
+      title: WindowsPerf Visual Studio extension releases
+      link: https://github.com/arm-developer-tools/windowsperf-vs-extension/releases
+      type: website
+  - resource:
+      title: WindowsPerf releases
+      link: https://github.com/arm-developer-tools/windowsperf/releases
+      type: website
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 21 # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps" # Always the same
+layout: "learningpathall" # All files under learning paths have this same wrapper
+---

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

@@ -0,0 +1,85 @@
+---
+title: The Counting Feature
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Introduction
+
+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
+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**:
+
+   - 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.
+
+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. **Timeline Parameters**:
+
+The option to create a timeline is available by toggling the `Timeline` checkbox.
+You then have the option to:
+
+- Choose the number of iterations to run the timeline (defaults to 1).
+- Choose the interval between each iteration (defaults to 0.5 second).
+
+## Initiating the Counting Process
+
+1. **Starting the Counting Process**:
+
+   - 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.
+
+![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.
+
+(**Optional**)
+
+- 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.
+
+![Open in WPA #center](./open-in-wpa.png)
+_WPA UI_

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

@@ -0,0 +1,113 @@
+---
+title: The Sampling Feature
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Introduction
+
+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 to Open Sampling Explorer
+
+1. **Accessing Sampling Explorer**:
+   - In Visual Studio 2022, go to the `View` menu.
+   - Select `Sampling Explorer` from the dropdown.
+
+## Setting Your Sampling Preferences
+
+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.
+
+## Configuring the Sampling Parameters
+
+1. **Filling in Necessary Fields**:
+
+   - 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.
+
+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`.
+
+![Sampling overview #center](./sampling-overview.png)
+_Sampling overview UI_
+
+## Initiating the Sampling Process
+
+1. **Starting the Sampling**:
+
+   - Click on the play button to kickstart the sampling.
+
+   - 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.
+
+## Delving into the Sampling Results
+
+1. **Analyzing the Results**:
+
+   - Post-sampling, you’ll notice the window divides into two sections: a tree view and a detailed analysis section.
+
+   - 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.
+
+   - 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.
+
+![Sampling results #center](./sampling-results.png)
+_Sampling results shown in the code editor_
+
+## Re-evaluating Post Edits
+
+1. **Comparing Results**:
+
+   - 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.
+
+   - With these steps, you are well-equipped to make the best of the sampling feature in the WindowsPerf GUI extension. Happy coding and optimizing!
+
+## Lock Unlock
+
+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.
+
+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
+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.
+
+However, interrupting a running wperf process would result in losing all the collected data. If interrupted, WidowsPerf will show the following error message:
+
+```shell
+warning: other WindowsPerf process hijacked (forced lock) the wperf-driver, see --force-lock.
+Operation terminated, your data was lost!
+
+Received ERROR_BAD_COMMAND, driver status:
+STATUS_INVALID_DEVICE_STATE
+error: PMU_CTL_LOCK_RELEASE can't be release
+```