Merge remote-tracking branch 'upstream/main'

Author: Your Name

content/install-guides/windows-perf-wpa-plugin.md

@@ -1,7 +1,7 @@
 ---
 ### Title the install tools article with the name of the tool to be installed
 ### Include vendor name where appropriate
-title: Windows Performance Analyzer (WPA) Plugin
+title: Windows Performance Analyzer (WPA) plugin
 minutes_to_complete: 15
 
 official_docs: https://github.com/arm-developer-tools/windowsperf-wpa-plugin
@@ -29,37 +29,40 @@ layout: installtoolsall # DO NOT MODIFY. Always true for tool install articles
 
 ## What is the Windows Performance Analyzer plugin?
 
-The Windows Performance Analyzer plugin connects Windows Perf to the Windows Performance Analyzer (WPA).
+The Windows Performance Analyzer (WPA) plugin connects [Windows Perf](/learning-paths/laptops-and-desktops/windowsperf/) to the Windows Performance Analyzer. Windows Perf is a lightweight performance profiling tool inspired by Linux Perf and designed for Windows on Arm.
 
-[WindowsPerf](https://github.com/arm-developer-tools/windowsperf) is a lightweight performance profiling tool inspired by Linux Perf and designed for Windows on Arm.
+Windows Performance Analyzer is a useful tool that supports developers with diagnostics and performance tuning. It generates data tables and graphs of Event Tracing for Windows (ETW) events, which are recorded in one of three ways:
+- Windows Performance Recorder (WPR)
+- Xperf
+- or through an assessment that's run in the Assessment Platform.
+ 
+WPA can open event trace log (ETL) files, which you can use for analysis.
 
-Windows Performance Analyzer (WPA) is a tool that creates graphs and data tables of Event Tracing for Windows (ETW) events that are recorded by Windows Performance Recorder (WPR), Xperf, or an assessment that is run in the Assessment Platform. WPA opens event trace log (ETL) files for analysis.
-
-The WPA plugin is built using the [Microsoft Performance Toolkit SDK](https://github.com/microsoft/microsoft-performance-toolkit-sdk), a collection of tools to create and extend performance analysis applications. The plugin parses json output from WidowsPerf so that it can be visualized in WPA. 
+The WPA plugin is built using the [Microsoft Performance Toolkit SDK](https://github.com/microsoft/microsoft-performance-toolkit-sdk), a collection of tools to create and extend performance analysis applications. The plugin parses JSON output from Windows Perf so that it can be visualized in WPA. 
 
 ## What are some of the features of the WPA plugin? 
 
-The WindowsPerf GUI extension is composed of several key features, each designed to streamline the user experience:
+The WindowsPerf GUI extension includes features, which are designed to streamline the user experience:
 
-### What is the timeline view?
+### Timeline view
 
-The timeline view visualizes the `wperf stat` timeline data plotted by event group.
+The timeline view visualizes the `wperf stat` timeline data plotted by event group:
 
 ![Timeline By Core Table](/install-guides/_images/wpa-timeline-by-core.png)
 
-### What is the telemetry view?
+### Telemetry view
 
-The telemetry view displays telemetry events grouped by unit.
+The telemetry view displays telemetry events grouped by unit:
 
 ![Telemetry Table](/install-guides/_images/wpa-telemetry-table.png)
 
 ## How do I install the WPA plugin?
 
-Before using the WPA plugin, make sure you have installed WPA.
+Before installing the plugin, you need to make sure you have installed WPA:
 
-### Windows Performance Analyzer
+### Install WPA
 
-WPA is included in the Windows Assessment and Deployment Kit (Windows ADK) that can be downloaded from [Microsoft](https://go.microsoft.com/fwlink/?linkid=2243390).
+WPA is included in the Windows Assessment and Deployment Kit (Windows ADK), which you can download from [Microsoft](https://go.microsoft.com/fwlink/?linkid=2243390).
 
 {{% notice Note %}}
 The WPA plugin requires WPA version `11.0.7.2` or higher.
@@ -69,46 +72,46 @@ Run the downloaded `adksetup.exe` program.
 
 Specify the default installation location and accept the license agreement. 
 
-Make sure that "Windows Performance Toolkit" is checked under "Select the features you want to install".
+Make sure that **Windows Performance Toolkit** is checked under **Select the features you want to install**.
 
 ![WPA Installation](/install-guides/_images/wpa-installation.png)
 
-Finally, click Install.
+Finally, click **Install**.
 
-### Windows Performance Analyzer plugin
+### Install the WPA plugin
 
-The plugin is a single `.dll` file.
+Now you're ready to install the plugin, which is a single `.dll` file.
 
-Download a `.zip` file from the [GitHub releases page](https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases).
+Download the `.zip` file from the [Windows Perf WPA plugin GitHub releases page](https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases) on GitHub.
 
-To download the latest version from the command prompt:
+Alternatively, you can download the latest version using command prompt:
 
 ```console
 mkdir wpa-plugin
 cd wpa-plugin
 curl -L -O https://github.com/arm-developer-tools/windowsperf-wpa-plugin/releases/download/1.0.2/wpa-plugin-1.0.2.zip
 ```
 
-Extract the `.dll` file from the downloaded `.zip` file. 
+Now extract the `.dll` file from the downloaded `.zip` file. 
 
 ```console
 tar -xmf wpa-plugin-1.0.2.zip
 ```
 
-You now have the file `WPAPlugin.dll` in your `wpa-plugin` directory. 
+The file `WPAPlugin.dll` is now in your `wpa-plugin` directory. 
 
 There are three ways you can install the `WPAPlugin.dll` file: 
 
-###### 1. Copy the plugin dll to the CustomDataSources directory next to the WPA executable.
+#### 1. Copy the .dll file to the CustomDataSources directory next to the WPA executable.
 
 The default location is: 
         `C:\\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\CustomDataSources`
 
-###### 2. Set an environment variable
+#### 2. Set an environment variable.
 
-Set the `WPA_ADDITIONAL_SEARCH_DIRECTORIES` environment variable to the location of the DLL file.
+Set the `WPA_ADDITIONAL_SEARCH_DIRECTORIES` environment variable to the location of the `.dll` file.
 
-###### 3. Start WPA from the command line and pass the plugin directory location using a flag.
+#### 3. Start WPA from the command line and pass the plugin directory location using a flag.
 
 Use the `-addsearchdir` flag for `wpa`:
 
@@ -118,13 +121,13 @@ wpa -addsearchdir "%USERPROFILE%\plugins"
         
 ## How can I verify the WPA plugin is installed?
 
-To verify the plugin is loaded, launch WPA and the plugin should appear under `Help > About Windows Performance Analyzer`
+To verify the plugin is loaded, launch WPA and the plugin should appear under **Help > About Windows Performance Analyzer**.
 
 ![WPA installation confirmation](/install-guides/_images/about-wpa.png)
 
 ## How can I run the WPA plugin from the command line?
 
-To open a json file directly from the command line, you can use the `-i` flag to specify the file path to open.
+To open a JSON file directly from the command line, you can use the `-i` flag to specify the file path to open.
 
 For example: to open `timeline_long.json` in your downloads directory, run the command:
 

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

@@ -1,7 +1,7 @@
 ---
 title: Get started with WindowsPerf
 
-minutes_to_complete: 15
+minutes_to_complete: 20
 
 who_is_this_for: This is an introductory topic for software developers working on laptops and desktops and new to the Arm architecture.
 
@@ -19,6 +19,7 @@ skilllevels: Introductory
 subjects: Performance and Architecture
 armips:
     - Cortex-A
+    - Neoverse
 operatingsystems:
     - Windows
 tools_software_languages:

content/learning-paths/laptops-and-desktops/windowsperf/_review.md

@@ -19,7 +19,7 @@ review:
             - "False"
         correct_answer: 1
         explanation: >
-            The available counters may vary between processors. Use `wprof -l` to generate a list of available counters.
+            The available counters may vary between processors. Use `wperf list` to generate a list of available counters.
 
     - questions:
         question: >
@@ -41,6 +41,26 @@ review:
         explanation: >
             Some `wperf` commands such as `list`, `test` or `stat` can output data in JSON format.
 
+    - questions:
+        question: >
+            Command `wperf sample` can be used together with  `--annotate` or `--disassemble` command line options.
+        answers:
+            - "True"
+            - "False"
+        correct_answer: 1
+        explanation: >
+            Yes, you can add annotate and disassemble output to `wperf sample` command.
+
+    - questions:
+        question: >
+            Command `wperf record` can be used together with  `--annotate` or `--disassemble` command line options.
+        answers:
+            - "True"
+            - "False"
+        correct_answer: 1
+        explanation: >
+            Yes, you can add annotate and disassemble output to `wperf record` command.
+
 
 # ================================================================================
 #       FIXED, DO NOT MODIFY

content/learning-paths/laptops-and-desktops/windowsperf/windowsperf.md

@@ -6,19 +6,19 @@ weight: 2
 
 # Overview
 
-[WindowsPerf](https://gitlab.com/Linaro/WindowsPerf/windowsperf) is a (Linux [perf](https://perf.wiki.kernel.org) inspired) Windows on Arm performance profiling tool. Profiling is based on ARM64 PMU and its hardware counters. WindowsPerf supports the counting model for obtaining aggregate counts of occurrences of special events, and sampling model for determining the frequencies of event occurrences produced by program locations at the function, basic block, and/or instruction levels.
+[WindowsPerf](https://github.com/arm-developer-tools/windowsperf) is a (Linux [perf](https://perf.wiki.kernel.org) inspired) Windows on Arm performance profiling tool. Profiling is based on ARM64 PMU and its hardware counters. WindowsPerf supports the counting model for obtaining aggregate counts of occurrences of special events, and sampling model for determining the frequencies of event occurrences produced by program locations at the function, basic block, and/or instruction levels.
 
 Learn more in this [blog](https://community.arm.com/arm-community-blogs/b/infrastructure-solutions-blog/posts/announcing-windowsperf) announcing the first release.
 
 ## WindowsPerf architecture
 
 `WindowsPerf` is composed of two main components:
-- [wperf](https://gitlab.com/Linaro/WindowsPerf/windowsperf/-/tree/main/wperf) a command line interface (CLI) sometimes referred as "user-space app" and
-- [wperf-driver](https://gitlab.com/Linaro/WindowsPerf/windowsperf/-/tree/main/wperf-driver) a (signed) Kernel-Mode Driver Framework (KMDF) driver.
+- [wperf](https://github.com/arm-developer-tools/windowsperf/tree/main/wperf) a command line interface (CLI) sometimes referred as "user-space app" and
+- [wperf-driver](https://github.com/arm-developer-tools/windowsperf/tree/main/wperf-driver) a (signed) Kernel-Mode Driver Framework (KMDF) driver.
 
 ## WindowsPerf releases
 
-You can find all binary releases of `WindowsPerf` [here](https://gitlab.com/Linaro/WindowsPerf/windowsperf/-/releases).
+You can find all binary releases of `WindowsPerf` [here](https://github.com/arm-developer-tools/windowsperf/releases).
 
 # Installation
 
@@ -106,6 +106,30 @@ wperf test
 You can output `wperf test` command in JSON format. Use `--json` command line option to enable JSON output.
 {{% /notice %}}
 
+## Obtain plain text information about specified event, metric, or group of metrics.
+
+Command line option `man` prints on screen information about specified event, metric, or group of metrics.
+
+```command
+wperf man l1d_cache_mpki
+```
+
+```output
+CPU
+    neoverse-n1
+NAME
+    l1d_cache_mpki - L1D Cache MPKI
+EVENTS
+    inst_retired, l1d_cache_refill
+DESCRIPTION
+    This metric measures the number of level 1 data cache accesses missed per
+    thousand instructions executed.
+FORMULA
+    l1d_cache_refill / inst_retired * 1000
+UNIT
+    MPKI
+```
+
 ## Generate sample profile
 
 Specify the `event` to profile with `-e`. Groups of events, known as `metrics` can be specified with `-m`.
@@ -139,4 +163,4 @@ You can output `wperf stat` command in JSON format. Use `--json` command line op
 {{% /notice %}}
 
 
-Example use cases are provided in the WindowsPerf [documentation](https://gitlab.com/Linaro/WindowsPerf/windowsperf/-/blob/main/wperf/README.md#counting-model).
+Example `wperf stat` command use cases are provided in the WindowsPerf [documentation](https://github.com/arm-developer-tools/windowsperf/tree/main/wperf#counting-model).

content/learning-paths/laptops-and-desktops/windowsperf/windowsperf_cheatsheet.md

@@ -0,0 +1,71 @@
+---
+layout: learningpathall
+title: WindowsPerf cheat sheet
+weight: 2
+---
+
+# WindowsPerf cheat sheet
+
+The cheat sheet for the `wperf` command line tool focuses specifically on counting and sampling commands. It includes `wperf stat` for counting occurrences of specific PMU events and `wperf sample` and `wperf record` for sampling PMU event. Each command is explained with practical example.
+
+## WindowsPerf cheat sheet (PMU Counting Examples)
+
+- Count events `inst_spec`, `vfp_spec`, `ase_spec` and `ld_spec` on core #0 for 3 seconds:
+
+```command
+wperf stat -e inst_spec,vfp_spec,ase_spec,ld_spec -c 0 --timeout 3
+```
+
+- Count metric `imix` (metric events will be grouped) and additional event `l1i_cache` on core #7 for 10.5 seconds:
+
+```command
+wperf stat -m imix -e l1i_cache -c 7 --timeout 10.5
+```
+
+- Count in timeline mode (output counting to CSV file) metric `imix` 3 times on core #1 with 2 second intervals (delays between counts). Each count will last 5 seconds:
+
+```command
+wperf stat -m imix -c 1 -t -i 2 -n 3 --timeout 5
+```
+
+## WindowsPerf cheat sheet (PMU Sampling Examples)
+
+- Launch and pin `python_d.exe –c 10**10**100` to core no. 1 and sample given image name:
+
+```command
+start /affinity 2 python_d.exe -c 10**10**100
+wperf sample -e ld_spec:100000 -c 1 --pe_file python_d.exe --image_name python_d.exe
+```
+
+Same workflow can be wrapped with `wperf record` command, see example below:
+
+- Launch `python_d.exe -c 10**10**100` process and start sampling event `ld_spec` with frequency `100000` on core no. 1 for 30 seconds.
+
+```command
+wperf record -e ld_spec:100000 -c 1 --timeout 30 -- python_d.exe -c 10**10**100
+```
+
+{{% notice Hint%}}
+Add `--annotate` or `--disassemble` to `wperf record` command line parameters to increase sampling "resolution".
+{{% /notice %}}
+
+## WindowsPerf cheat sheet (SPE Examples)
+
+Use Arm SPE optional extension to sample on core no. 1 process `python_d.exe`. SPE filter `load_filter` / `ld` enables collection of load sampled operations, including atomic operations that return a value to a register.
+
+Note: Double-dash operator `--` can be used with SPE as well to launch the process.
+
+```command
+wperf record -e arm_spe_0/ld=1/ -c 1 -– python_d.exe -c 10**10**100
+```
+
+Above command can be replaces by below two commands:
+
+```command
+start /affinity 2 python_d.exe -c 10**10**100
+wperf sample -e arm_spe_0/ld=1/ -c 1 --pe_file python_d.exe --image_name python_d.exe
+```
+
+{{% notice Hint%}}
+Add `--annotate` or `--disassemble` to `wperf record` command line parameters to increase sampling "resolution".
+{{% /notice %}}

content/learning-paths/servers-and-cloud-computing/csp/google.md

@@ -11,7 +11,7 @@ layout: "learningpathall"
 
 As with most cloud service providers, Google Cloud offers a pay-as-you-use [pricing policy](https://cloud.google.com/pricing), including a number of [free](https://cloud.google.com/free/docs/free-cloud-features) services.
 
-This section is to help you get started with [Google Cloud Compute Engine](https://cloud.google.com/compute) compute services, using Arm-based Virtual Machines. Google Cloud offers two generations of Arm-based VMs, `C4A` is the latest generation based on [Google Axion](cloud.google.com/products/axion), Google’s first Arm-based server processor, built using the Armv9 Neoverse V2 CPU. The previous generation VMs are based on Ampere Altra processor and part of [Tau T2A](https://cloud.google.com/tau-vm) family of Virtual Machines. 
+This section is to help you get started with [Google Cloud Compute Engine](https://cloud.google.com/compute) compute services, using Arm-based Virtual Machines. Google Cloud offers two generations of Arm-based VMs, `C4A` is the latest generation based on [Google Axion](https://cloud.google.com/products/axion), Google’s first Arm-based server processor, built using the Armv9 Neoverse V2 CPU. The previous generation VMs are based on Ampere Altra processor and part of [Tau T2A](https://cloud.google.com/tau-vm) family of Virtual Machines. 
 
 Detailed instructions are available in the Google Cloud [documentation](https://cloud.google.com/compute/docs/instances). 
 
@@ -23,7 +23,7 @@ If using an organization's account, you will likely need to consult with your in
 
 ## Browse for an appropriate instance
 
-Google Cloud offers a wide range of instance types, covering all performance (and pricing) points. For an overview of the `C4A` instance types, see this [page](cloud.google.com/products/axion). Similarly, to know more about the `T2A` instance types, see the [General-purpose machine family](https://cloud.google.com/compute/docs/general-purpose-machines#t2a_machines) overview. 
+Google Cloud offers a wide range of instance types, covering all performance (and pricing) points. For an overview of the `C4A` instance types, see the [General-purpose machine family](https://cloud.google.com/compute/docs/general-purpose-machines#c4a_series). Similarly, to know more about the `T2A` instance types, see this [page](https://cloud.google.com/compute/docs/general-purpose-machines#t2a_machines). 
 
 Also note which [regions](https://cloud.google.com/compute/docs/regions-zones#available) these servers are available in.
 
@@ -49,15 +49,15 @@ Select an appropriate `region` and `zone` that support Arm-based servers.
 
 ![google3 #center](https://github.com/ArmDeveloperEcosystem/arm-learning-paths/assets/71631645/f2a19cd0-7565-44d3-9e6f-b27bccad3e86 "Select an appropriate region and zone")
 
-To view the latest information on which available regions and zones support Arm-based servers, see the [Compute Engine documentation](https://cloud.google.com/compute/docs/regions-zones#available). To filter for Arm-based machines, click on `Select a machine type`, then select `T2A` or `C4A` from the pull-down menu.
+To view the latest information on which available regions and zones support Arm-based servers, see the [Compute Engine documentation](https://cloud.google.com/compute/docs/regions-zones#available). To filter for Arm-based machines, click on `Select a machine type`, then select `C4A` or `T2A` from the pull-down menu.
 
-![google4 #center](https://github.com/ArmDeveloperEcosystem/arm-learning-paths/assets/71631645/5b1683dc-724f-4c60-aea6-dc945c7bf6bc "Check which regions and zones support Arm-based machines")
+![google4 #center](images/axion-series.png "Check which regions and zones support Arm-based machines")
 
 ### Machine configuration
 
 Select `C4A` from the `Series` pull-down menu. Then select an appropriate `Machine type` configuration for your needs.
 
-![google5 #center](images/gcp_instance_new.png "Select an appropriate C4A machine type")
+![google5 #center](images/axion-instance.png "Select an appropriate C4A machine type")
 
 ### Boot disk configuration