diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/SPE-settings.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/SPE-settings.png new file mode 100644 index 000000000..26921248f Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/SPE-settings.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_index.md b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_index.md new file mode 100644 index 000000000..e8644669c --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_index.md @@ -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. +--- diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_next-steps.md b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_next-steps.md new file mode 100644 index 000000000..a4a727862 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/_next-steps.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 +--- diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/counting-feature.md b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/counting-feature.md new file mode 100644 index 000000000..67e5e78d6 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/counting-feature.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_ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/host-data.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/host-data.png new file mode 100644 index 000000000..17569c593 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/host-data.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/open-in-wpa.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/open-in-wpa.png new file mode 100644 index 000000000..1066c5cfe Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/open-in-wpa.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-feature.md b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-feature.md new file mode 100644 index 000000000..c162bbb13 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-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 +``` diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-overview.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-overview.png new file mode 100644 index 000000000..c04d4f5cf Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-overview.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-results.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-results.png new file mode 100644 index 000000000..f195be160 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-results.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-settings.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-settings.png new file mode 100644 index 000000000..01ff9d30b Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/sampling-settings.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/settings-page.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/settings-page.png new file mode 100644 index 000000000..8d81b8e01 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/settings-page.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-feature.md b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-feature.md new file mode 100644 index 000000000..249afb927 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-feature.md @@ -0,0 +1,104 @@ +--- +title: The SPE Feature +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Introduction + +The SPE feature is a subset of the Sampling feature that we just discussed. + +## What is The Arm Statistical Profiling Extension (SPE) + +The Arm Statistical Profiling Extension (SPE) is an architectural feature designed for enhanced instruction execution profiling within Arm CPUs. This feature has been available since the introduction of the Neoverse N1 CPU platform in 2019, along with performance monitor units (PMUs) generally available in Arm CPUs. + +The SPE is an optional feature in ARMv8.2 hardware that allows CPU instructions to be sampled and associated with the source code location where that instruction occured. + +Some of the key methodologies that can be applied for performance analysis using SPE-profiled data are as follows: + +1. Precise sampling for hotspot detection in source code +2. Memory access analysis +3. Data sharing analysis + +## SPE filters + +SPE provides hardware configuration options to filter the data of interest from an SPE sample record before storing it to memory. This helps with targeted profiling for specific operation types, events, and threshold latency values. For example, a user might choose to profile the following: + +- Only record load operations. (load_filter) +- Only record store operations. (store_filter) +- Only record branches. (branch_filter) + +## Before you begin + +1. You need to install WindowsPerf and WindowsPerf driver with SPE flag enabled. To do so you can download WindowsPerf from the release page and install the version under the SPE folder. +2. Your arm CPU must have a Statistical Profiling Extension wich has been available since the introduction of the Neoverse N1 CPU platform in 2019. +3. You need to be runing Windows On arm in Test Mode + +## How to check if you have SPE enabled on your machine + +First step is to go to the extension's settings page, available at `Tools -> Options -> Windows Perf -> WindowsPerf Path` and make sure that your WindowsPerf and WindowsPerf driver versions have SPE under their feature string: + +![Extension settings page #center](./settings-page.png) + +This step will let you know wether or not you have installed the version of `WindowsPerf` that supports the SPE feature. + +The second step is to verify if your CPU supports ARM SPE. + +To do so you need to go to go to `Tools -> WindowsPerf Host Data` scroll to the bottom of the list until you find **`spe_device.version_name** if the test result is saying anything but **not implemented** then your CPU supports ARM SPE. + +![Host data page #center](./host-data.png) + +## Configuring the SPE command + +1. **Accessing Sampling Explorer**: + + - In Visual Studio 2022, go to the `View` menu. + - Select `Sampling Explorer` from the dropdown. + +2. **Opening Sampling Settings**: + + - Inside the Sampling Explorer window, find and click on the `settings wheel` icon. + - This action will open the Sampling Settings Dialog. + +3. **Switching to SPE mode**: + + - This can be achieved by clicking on the **Enable SPE mode** checkbox in the Sampling Settings Dialog. + - This will add switch the event list combobox to a list of **SPE filters that you can chose from**. + +4. **Filling in Necessary Fields**: + + - The dialog presents multiple fields for configuration. Essential fields to fill in include: + - File payload + - CPU core selection + - Fill these in according to the specifics of the sampling you wish to perform. + +5. **Command Preview**: + + - As you configure the settings, the dialog provides a real-time preview of the WindowsPerf command that will be executed. + +6. **Saving Your Settings**: + - Once you are satisfied with your configurations, click `save`. + +![SPE settings #center](./SPE-settings.png) + +## Initiating the Sampling Process + +- 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. + +## Exploring the results + +- At the end of the run 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. + +{{% notice Note %}} +All the SPE results will be prefixed by your SPE device version name (e.g. `FEAT_SPEv1p1`) +{{% /notice %}} + +![SPE results #center](./spe-results.png) diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-results.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-results.png new file mode 100644 index 000000000..2357fe4d9 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/spe-results.png differ diff --git a/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/start-counting.png b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/start-counting.png new file mode 100644 index 000000000..8bbcd9770 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/windowsperf-vs-extension/start-counting.png differ