Merge pull request #1347 from PrzemekWirkus/devel_update_wperf_cheatsheet

Update "Get started with WindowsPerf" - add cheat sheet and fix links

Author: jasonrandrews

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 %}}