Enable SPE for Memory Access Recipe - LP

content/learning-paths/servers-and-cloud-computing/spe-on-performix/_index.md

@@ -0,0 +1,73 @@
+---
+title: Enable Arm SPE for Performix memory access analysis
+
+draft: true
+cascade:
+    draft: true
+
+description: Learn how to verify and enable Arm Statistical Profiling Extension (SPE) on Arm Linux machines, including systems hosted through cloud service providers, so the Memory Access recipe in Arm Performix can run on supported environments.
+
+minutes_to_complete: 30
+
+who_is_this_for: This is an introductory topic for software developers and performance engineers who want to prepare Arm Linux machines, including cloud-hosted systems, for Arm Performix memory access profiling.
+
+learning_objectives:
+    - Check whether Arm Statistical Profiling Extension (SPE) is already available on an Arm Linux system using Sysreport and kernel-level checks.
+    - Explain the hardware, platform, and kernel requirements that allow Linux to expose the SPE driver.
+    - Apply Linux-side changes such as loading the SPE PMU module, installing matching kernel modules, or selecting an OS/kernel with SPE support.
+    - Identify when a cloud instance does not expose SPE to the guest OS and choose a suitable system for Arm Performix memory access analysis.
+
+prerequisites:
+    - Access to a Linux-based Arm system, such as an Arm cloud instance or bare-metal server, with sudo or root access.
+    - Access to Arm Performix on your host machine and SSH access to the target system. See the [Arm Performix install guide](/install-guides/performix/) for setup instructions.
+    - Familiarity with the Linux command line and SSH.
+
+author: Kieran Hejmadi
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+cloud_service_providers:
+    - AWS
+    - Google Cloud
+    - Microsoft Azure
+armips:
+    - Neoverse
+tools_software_languages:
+    - Arm Performix
+    - Sysreport
+    - Linux kernel
+    - perf
+operatingsystems:
+    - Linux
+
+further_reading:
+    - resource:
+        title: Arm Performix install guide
+        link: https://learn.arm.com/install-guides/performix/
+        type: documentation
+    - resource:
+        title: Arm Statistical Profiling Extension documentation
+        link: https://developer.arm.com/documentation/100616/0401/?lang=en
+        type: documentation
+    - resource:
+        title: Arm Performix
+        link: https://developer.arm.com/servers-and-cloud-computing/arm-performix
+        type: website
+    - resource:
+        title: Get ready for performance analysis with Sysreport
+        link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/sysreport/
+        type: documentation
+    - resource:
+        title: Analyze cache behavior with Perf C2C on Arm
+        link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/false-sharing-arm-spe/
+        type: learning-path
+
+
+
+### 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/spe-on-performix/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # The weight controls the order of the pages. _index.md always has weight 1.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/servers-and-cloud-computing/spe-on-performix/how-to-1.md

@@ -0,0 +1,55 @@
+---
+title: Get started
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## What is Arm Statistical Profiling Extension
+
+Arm Statistical Profiling Extension (SPE) is a hardware-assisted profiling feature in the Arm A-profile architecture. It was introduced with Armv8.2-A and extended in later architecture revisions. Most modern Arm-based cloud systems support SPE.
+
+Unlike traditional interrupt-driven sampling, SPE records rich metadata for sampled operations, including instruction context, memory address information, and latency-related attributes. This improves attribution accuracy and helps reduce drift (also called skid) when mapping instructions to sampled counts. For more background, see the [performance analysis white paper](https://developer.arm.com/documentation/109429/latest/).
+
+For Arm Performix, this matters because SPE must be enabled to use the `Memory Access` recipe.
+
+## Understand the platform layers that enable SPE
+
+On Linux, SPE is available only when all required layers are aligned:
+
+- **Architecture layer**: the CPU must implement SPE (common on Arm Neoverse systems and the Arm AGI CPU).
+- **Firmware layer**: platform firmware must advertise the SPE PMU and its interrupt path through ACPI or Device Tree. This is usually already enabled, so this check is often skipped.
+- **Kernel layer**: the running kernel must be built with Arm SPE PMU support through the `CONFIG_ARM_SPE_PMU` kernel build option.
+- **Driver layer**: the `arm_spe_pmu` driver must initialize successfully (built-in or loaded as a module). This requires all the above layers to have Arm SPE support.
+
+If any of these layers are missing, Linux cannot expose SPE to profiling tools. Additionally, cloud-based applications usually run on top of a hypervisor which typically disables SPE.
+
+{{% notice Please Note %}}
+
+Cloud providers often disable low-level profiling features on shared (multi-tenant) instances. To use Performix memory access profiling, run your application on an Arm-based **bare-metal instance** with full hardware access. These instances are typically named `metal` instances.
+
+Be aware that this instance type typically has a higher cost.
+
+{{% /notice %}}
+
+
+## What is usually already present
+
+On Neoverse-based systems, architecture support is already present, and firmware support is usually present.
+
+This Learning Path helps you determine which case applies to your system and what action to take next. Because Linux distributions and kernel versions vary widely, this Learning Path provides practical guidance rather than an exhaustive set of steps.
+
+## Check if Arm SPE is enabled
+
+Open Performix from your local machine. If this is your first time using or installing Performix, see the [install guide](https://learn.arm.com/install-guides/performix/).
+
+Connect to your instance, select the `Recipes` tab, and then select the `Memory Access` recipe. This automatically runs a precheck and prints the status at the bottom of the page. If you receive the **SPE is not configured** status shown below, you need to enable SPE before you can run the recipe.
+
+![Screenshot of the Arm Performix Memory Access recipe showing a red status notification at the bottom of the page indicating that SPE has not been configured for the target system. This is the expected message when the arm_spe_pmu driver is missing or not loaded.#center](./memory-access-no-spe.png "Arm Performix Memory Access recipe reporting that SPE is not configured")
+
+If you receive a different error message, SPE is likely **not** the cause of your issue. See the [Performix user guide](https://developer.arm.com/documentation/110163/latest).
+
+
+
+

content/learning-paths/servers-and-cloud-computing/spe-on-performix/how-to-2.md

@@ -0,0 +1,159 @@
+---
+title: Assess OS kernel
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### Step 1.0) Check whether the OS kernel is built with SPE
+
+From the Getting Started section, you know you need to verify both the kernel and driver layers. Start by checking the kernel version:
+
+```bash
+uname -r
+```
+The output will be similar to:
+
+```output
+6.17.0-1010-aws
+```
+
+This AWS instance is running the standard Ubuntu 24.04 LTS Amazon Machine Image (AMI) provided through AWS Quick Start. The command output shows a Linux 6.17 kernel, and the `1010-aws` suffix indicates an AWS-specific build customized for the AWS environment.
+
+Now check whether this kernel was built with SPE support enabled:
+
+```bash
+grep CONFIG_ARM_SPE_PMU /boot/config-$(uname -r) 2>/dev/null || true
+```
+
+The possible outputs are `y`, `m`, or `n`, meaning built-in support, module support, or no support.
+
+- `y` indicates that the kernel was built with SPE support.
+- `m` indicates that SPE is available as a loadable kernel module. This is the typical output for cloud instances.
+- `n` means the kernel was **not** built with SPE support.
+
+If the output from the previous command is `CONFIG_ARM_SPE_PMU = n`, **skip directly to Step 3.0**.
+
+If the output from the previous command is `CONFIG_ARM_SPE_PMU = y`, **you can skip directly to step 1.2.**
+
+### Step 1.1) Check whether the kernel module is available
+
+If your output was `CONFIG_ARM_SPE_PMU = m`, as shown below, the OS kernel includes SPE support. However, you still need to confirm that the driver layer is present and can be loaded.
+
+```output
+CONFIG_ARM_SPE_PMU             = m
+```
+
+Run the following command to check whether the loadable kernel module (driver) is available on the target:
+
+```bash
+modinfo arm_spe_pmu 2>/dev/null || echo "arm_spe_pmu not present for this kernel"
+```
+
+If you see output similar to the following, `arm_spe_pmu` is built as a module. If you see `arm_spe_pmu not present for this kernel`, continue to step 1.2. We will attempt to find and install the module for our specific kernel in later steps.
+
+```output
+filename:       /lib/modules/6.17.0-1010-aws/kernel/drivers/perf/arm_spe_pmu.ko.zst
+license:        GPL v2
+author:         Will Deacon <will.deacon@arm.com>
+description:    Perf driver for the ARMv8.2 Statistical Profiling Extension
+srcversion:     3B6FCB5AD9B37B8BB9FF4A9
+...
+```
+
+Next, run the following command to load the driver:
+
+```bash
+sudo modprobe arm_spe_pmu
+lsmod | grep arm_spe_pmu
+```
+
+If it loads correctly, the output will be similar to:
+
+```output
+arm_spe_pmu            24576  0
+```
+
+In Step 1.2, use Sysreport to review system-level metrics, including SPE status.
+
+### Step 1.2) Run Sysreport
+
+Follow the steps in the [Get ready for performance analysis with Sysreport guide](https://learn.arm.com/learning-paths/servers-and-cloud-computing/sysreport/) and run `sysreport` on your system:
+
+```bash
+python /src/sysreport.py 
+```
+
+This prints information about your system, including whether SPE is enabled. The `perf sampling` label shows SPE status. It also provides useful details for further debugging.
+
+```output
+System feature report:
+  Collected:           2026-04-13 09:40:16.344396
+  Script version:      2026-04-08 08:08:28.656402
+  Running as root:     False
+System hardware:
+  Architecture:        ARMv8.4
+  CPUs:                64
+  CPU types:           64 x Arm Neoverse V1 r1p1
+  cache info:          size, associativity, sharing
+  cache line size:     64
+  Caches:
+    64 x L1D 64K 4-way 64b-line
+    64 x L1I 64K 4-way 64b-line
+    64 x L2U 1M 8-way 64b-line
+    1 x L3U 32M 16-way 64b-line
+  System memory:       126G
+  Atomic operations:   True
+  interconnect:        CMN-650 x 1
+  NUMA nodes:          1
+  Sockets:             1
+OS configuration:
+  Kernel:              6.17.0
+  config:              /boot/config-6.17.0-1010-aws
+  build dir:           /lib/modules/6.17.0-1010-aws/build
+  uses atomics:        True
+  page size:           4K
+  huge pages:          2048kB: 0, 32768kB: 0, 64kB: 0, 1048576kB: 0
+  transparent HP:      madvise
+  MPAM configured:     False
+  resctrl:             False
+  Distribution:        Ubuntu 24.04.4 LTS
+  libc version:        glibc 2.39
+  boot info:           ACPI
+  KPTI enforced:       False
+  Lockdown:            landlock, lockdown, yama, integrity, apparmor
+  Mitigations:         spectre_v2:CSV2, BHB; spec_store_bypass:Speculative Store Bypass disabled via prctl; spectre_v1:__user pointer sanitization
+Performance features:
+  perf tools:          True
+  perf installed at:   /usr/lib/linux-tools/6.17.0-1010-aws/perf
+  perf with OpenCSD:   False
+  perf counters:       6
+  perf sampling:       None
+  perf HW trace:       None
+  perf paranoid:       0
+  CAP_PERFMON:         disabled
+  kptr_restrict:       1
+  perf in userspace:   disabled
+  interconnect perf:   True
+  /proc/kcore:         True
+  /dev/mem:            True
+  eBPF:
+    kernel configured for BPF: True
+    bpftool installed:         True
+      bpftool v7.7.0 using libbpf v1.7 features: 
+    bpftrace installed:        bpftrace v0.20.2
+
+
+Actions that can be taken to improve performance tools experience:
+  perf tools cannot decode hardware trace
+    build with CORESIGHT=1
+  non-invasive sampling (SPE) not enabled
+    ensure APIC table describes SPE interrupt
+    kernel module arm_spe_pmu.ko must be built
+  hardware trace not enabled
+    rebuild kernel with CONFIG_CORESIGHT
+    ensure ACPI describes CoreSight trace fabric
+```
+
+In this example, the output shows `perf sampling:       None`, so continue to the next step.