Merge pull request #3158 from bccbrendan/bccbrendan/performix-system-characterization-lp

Add Learning Path for Performix System Characterization Recipe

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/performix-system-characterization/1-setup.md

@@ -0,0 +1,40 @@
+---
+title: Set up Performix and the target machine
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Understand the System Characterization recipe
+
+The System Characterization recipe runs a set of low-level benchmarks, diagnostic scripts, and system tests to analyze performance on Arm-based platforms. It evaluates key hardware characteristics, including memory latency and bandwidth, and is especially useful for platform bring-up, system tuning, and architectural comparisons. It helps developers and system architects gather early, repeatable insight into performance-critical subsystems.
+
+The latency sweep plot below shows one of the benchmarks that System Characterization provides: the average latency of memory accesses across varying working-set sizes, revealing the latency of each cache level in the memory hierarchy.
+
+![Arm Performix latency sweep plot showing cache-level transitions#center](./latency-sweep-plot.webp "Latency Sweep")
+
+## Before you begin
+
+Make sure Arm Performix is installed on your host machine. The host machine is your local computer where the Arm Performix GUI runs, and it can be a Windows, macOS, or Linux machine. The target machine is the Linux server you wish to benchmark and characterize.
+
+If you do not have Arm Performix installed, see the [Arm Performix install guide](/install-guides/performix/).
+
+From the host machine, open Arm Performix and navigate to the **Targets** tab. Set up an SSH connection to the target you want to benchmark, and test the connection.
+
+The System Characterization recipe requires Python and the `numactl` utility on the target machine.
+Connect to your target machine using SSH and install these required OS packages.
+
+For Ubuntu and other Debian-based distributions, run the following command:
+
+```bash
+sudo apt-get install python3 python3-venv numactl -y
+```
+
+## What you've learned and what's next
+
+In this section:
+- You set up the target machine and established an SSH connection.
+- You installed the packages required to run the System Characterization recipe.
+
+Next, you'll run the recipe and inspect how your hardware platform performs.

content/learning-paths/servers-and-cloud-computing/performix-system-characterization/2-run-system-characterization.md

@@ -0,0 +1,41 @@
+---
+title: Benchmark your platform with System Characterization
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Run the System Characterization recipe
+
+To understand your platform's memory performance in its current configuration, run the System Characterization recipe in Arm Performix.
+
+![Arm Performix System Characterization configuration screen with benchmark selection options#center](./preparing-target.webp "System Characterization Configuration")
+
+You can collect the default benchmark set, gather only static system configuration details, or select individual benchmarks to run.
+
+Select the target you configured in the setup section. If this is your first run on this target, you might need to select **Install Tools** to copy the collection tools to the target. After the tools are installed, the target status changes to ready.
+
+The **Workload type** field is fixed at **Profile the whole system**. System Characterization examines the full platform; it does not profile an individual application or workload.
+
+At the bottom of the recipe configuration page, Arm Performix runs a pre-run check to confirm that required packages such as `numactl` are installed.
+
+![Arm Performix pre-run check confirming required packages are installed#center](./pre-run-check-succeeds.webp "Pre-Run Check")
+
+When the configuration is complete, select **Run Recipe** to launch the workload and collect performance data. Arm Performix shows a progress indicator with an estimated completion time. If you manually select many benchmarks, the run can take around 30 minutes.
+
+![Arm Performix System Characterization progress view while collecting benchmarks#center](./collecting-benchmarks.webp "Collecting Benchmarks")
+
+## View the run results
+
+The System Characterization recipe generates several result views. Arm Performix presents tabular data in views such as **Idle Latency** and **Peak Bandwidth**. Raw data, `.csv` files, and plots are available through the **Open Run Directory** button on the **Summary** tab. The next sections walk through several of these results.
+
+![Arm Performix System Characterization summary view after report generation#center](./report-generated.webp "Results Summary for Run")
+
+## What you've learned and what's next
+
+In this section:
+- You ran the System Characterization recipe on your target machine.
+- You viewed the results generated for the run.
+
+Next, you'll examine benchmark data collected from the individual tests.

content/learning-paths/servers-and-cloud-computing/performix-system-characterization/3-view-data-in-performix.md

@@ -0,0 +1,60 @@
+---
+title: View benchmark results in the Performix UI
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## View the run results in the Performix GUI
+
+Because the System Characterization recipe uses the standalone Arm System Characterization Tool (ASCT), it creates an output directory for all ASCT results and imports a subset of those results into the GUI. At the time of writing, Performix presents the data in tabular form and links to the output directory for plots and raw data.
+
+### Idle Latency
+
+In **Idle Latency**, ASCT reports memory latency for each non-uniform memory access (NUMA) node while the system is idle. You can use this view to spot bottlenecks caused by workload placement and to identify which nodes are closest to memory resources.
+
+![Arm Performix Idle Latency table showing NUMA-node memory latency#center](./idle-latency.webp "Idle Latency Results")
+
+### Peak Bandwidth
+
+**Peak Bandwidth** shows the maximum measured memory bandwidth for different read and write patterns, and compares those results with the theoretical peak bandwidth of the system.
+
+![Arm Performix Peak Bandwidth table comparing measured and theoretical bandwidth#center](./peak-bandwidth.webp "Peak Bandwidth Results")
+
+### Cross-NUMA Bandwidth
+
+**Cross-NUMA Bandwidth** shows the bandwidth achieved when memory requests cross NUMA node boundaries.
+
+![Arm Performix Cross-NUMA Bandwidth table showing inter-node bandwidth#center](./cross-numa-bandwidth.webp "Cross-NUMA Bandwidth Results")
+
+### Latency Sweep
+
+The latency sweep benchmark measures latency by data size to map the cache hierarchy and identify appropriate data sizes for other benchmarks. It highlights the performance characteristics of each level of the cache and memory hierarchy.
+
+![Arm Performix Latency Sweep table mapping latency across data sizes#center](./latency-sweep-table.webp "Latency Sweep Table")
+
+### Bandwidth Sweep
+
+The bandwidth sweep benchmark varies the data size used to generate memory accesses and measures the bandwidth delivered by each level of the memory hierarchy.
+
+![Arm Performix Bandwidth Sweep table mapping bandwidth across data sizes#center](./bandwidth-sweep-table.webp "Bandwidth Sweep Table")
+
+### Core-to-Core Latency
+
+The core-to-core latency benchmark measures the latency of moving data from one core to another. Because the number of core pairs grows quickly, this benchmark runs on only a subset of system cores by default.
+
+![Arm Performix Core-to-Core Latency table showing latency between selected cores#center](./core-to-core-ui.webp "Core-to-Core Latency Table")
+
+### System Information
+
+This table shows the system information collected by ASCT, including CPU, memory, and storage details.
+
+![Arm Performix System Information table with CPU, memory, and storage details#center](./system-information.webp "System Information")
+
+## What you've learned and what's next
+
+In this section:
+- You viewed benchmark results from ASCT in the Arm Performix results view.
+
+Next, you'll inspect plots from the ASCT output directory that are not yet displayed directly in the Performix UI.

content/learning-paths/servers-and-cloud-computing/performix-system-characterization/4-open-results-directory.md

@@ -0,0 +1,48 @@
+---
+title: View raw benchmark results and generated plots
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## View the System Characterization results directory
+
+The previous section showed how to view and interpret the tabular benchmark results in Arm Performix. Performix also provides a link to the underlying Arm System Characterization Tool run directory so you can inspect plots that are not yet available in the GUI and access the underlying `.json` data files for integration with other tools.
+
+Click the **Open Run Directory** button on the **Summary** page of your run.
+
+![Arm Performix Summary view with the Open Run Directory button#center](./report-generated.webp "Open Run Directory")
+
+This opens a file browser that contains `.png` and `.json` files for the various benchmarks.
+
+![File browser opened to the Arm System Characterization run directory#center](./run-directory.webp "Run Directory")
+
+## Some example plots
+
+### Latency Sweep
+
+The latency sweep plot shows how the size of a memory access pattern affects memory latency. Red bars indicate the points at which different cache levels become active.
+
+![Arm System Characterization latency sweep plot showing cache-level transitions#center](./latency-sweep-plot.webp "Latency Sweep")
+
+### Bandwidth Sweep
+
+The `bandwidth.png` file shows the results of the bandwidth sweep benchmark.
+
+![Arm System Characterization bandwidth sweep plot across data sizes#center](./bandwidth-sweep-plot.webp "Bandwidth Sweep")
+
+The plot shows how certain memory access sizes can significantly affect system memory bandwidth.
+
+### Core-to-Core Latency
+
+The `core_latency_heatmap_local.png` plot shows a color-coded heatmap of which core combinations incur higher latency.
+
+![Arm System Characterization core-to-core latency heatmap across selected cores#center](./core-to-core-latency-plot.webp "Core-to-Core Latency")
+
+## What you've learned and what's next
+
+In this section:
+- You viewed several plots generated by ASCT.
+
+You're now ready to analyze and optimize your own platform with Arm Performix and the Arm System Characterization Tool recipe.

content/learning-paths/servers-and-cloud-computing/performix-system-characterization/_index.md

@@ -0,0 +1,49 @@
+---
+title: Understand system characteristics with Arm Performix
+
+
+minutes_to_complete: 60
+
+who_is_this_for: This is an introductory topic for anyone who wants to understand the performance characteristics of a hardware system.
+
+learning_objectives:
+    - Run Arm Performix's System Characterization recipe to understand hardware configuration and performance
+    - Interpret memory latency and bandwidth benchmark results
+    - View the output directory to inspect generated plots and raw results
+
+prerequisites:
+    - A target machine to benchmark. The Arm System Characterization Tool, included with Performix, is cross-platform and cross-OS.
+
+author:
+- Brendan Long
+- David Wong
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Neoverse
+tools_software_languages:
+    - Arm Performix
+    - Arm System Characterization Tool
+    - Runbook
+
+operatingsystems:
+    - Linux
+
+further_reading:
+    - resource:
+        title: "Find CPU Cycle Hotspots with Arm Performix"
+        link: /learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/
+        type: documentation
+    - resource:
+        title: Arm Performix User Guide
+        link: https://developer.arm.com/documentation/110163/latest
+        type: documentation
+
+### 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/servers-and-cloud-computing/performix-system-characterization/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---