Merge pull request #1970 from ArmDeveloperEcosystem/main

Production update

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/false-sharing-arm-spe/_index.md

@@ -7,17 +7,17 @@ cascade:
 
 minutes_to_complete: 15
 
-who_is_this_for: Cloud developers who are looking to debug and optimize cache access patterns on cloud servers with perf c2c. 
+who_is_this_for: This topic is for developers who want to optimize cache access patterns on Arm servers using Perf C2C. 
 
 learning_objectives: 
-    - Learn basic C++ techniques to avoid false sharing with alignas().
-    - Learn how to enable and use Arm_SPE.
-    - Learn how to investigate cache line performance with perf c2c.
+    - Avoid false sharing in C++ using memory alignment.
+    - Enable and use the Arm Statistical Profiling Extension (SPE) on Linux systems.
+    - Investigate cache line performance with Perf C2C.
 
 prerequisites:
-    - Arm-based cloud instance with Arm Statistical Profiling Extension support.
-    - basic understanding on cache hierarchy and how efficient cache accessing impact performance..
-    - Familiarity with the Linux Perf tool.
+    - Access to an Arm-based cloud instance with support for the Arm Statistical Profiling Extension (SPE).
+    - A basic understanding of cache coherency and its impact on performance.
+    - Familiarity with Linux Perf tools.
 
 author: Kieran Hejmadi
 
@@ -28,6 +28,7 @@ armips:
     - Neoverse
 tools_software_languages:
     - Perf
+    - Runbook
 operatingsystems:
     - Linux
 

content/learning-paths/servers-and-cloud-computing/false-sharing-arm-spe/how-to-1.md

@@ -1,34 +1,36 @@
 ---
-title: Introduction to Arm_SPE and False Sharing
+title: Introduction to Arm SPE and false sharing
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Introduction to Arm Statistical Profiling Extension (SPE)
+## Introduction to the Arm Statistical Profiling Extension (SPE)
 
-Standard performance tracing relies on counting whole instructions, capturing only architectural instructions without revealing the actual memory addresses, pipeline latencies, or considering micro-operations in flight. Moreover, the “skid” phenomenon where events are falsely attributed to later instructions can mislead developers. 
+Standard performance tracing relies on counting completed instructions, capturing only architectural instructions without revealing the actual memory addresses, pipeline latencies, or considering micro-operations in flight. Moreover, the “skid” phenomenon where events are falsely attributed to later instructions can mislead developers. 
 
-The Arm Statistical Profiling Extension (SPE) integrates sampling directly into the CPU pipeline, triggering on individual micro-operations rather than retired instructions, thereby eliminating skid and blind spots. Each SPE sample record includes relevant meta data, such as data addresses, per-µop pipeline latency, triggered PMU event masks, and the memory hierarchy source, enabling fine-grained and precise cache analysis. 
+SPE integrates sampling directly into the CPU pipeline, triggering on individual micro-operations rather than retired instructions, thereby eliminating skid and blind spots. Each SPE sample record includes relevant metadata, such as data addresses, per-µop pipeline latency, triggered PMU event masks, and the memory hierarchy source, enabling fine-grained and precise cache analysis. 
 
-This enables software developers to tune user-space software for characteristics such as memory latency and cache accesses. Importantly, it is the mechanism on Arm to enable cache statistics with the Linux `perf` cache-to-cache utility, referred to as `perf c2c`. Please refer to the [Arm_SPE whitepaper](https://developer.arm.com/documentation/109429/latest/) for more details. 
+This enables software developers to tune user-space software for characteristics such as memory latency and cache accesses. Importantly, cache statistics are enabled with the Linux Perf cache-to-cache (C2C) utility.
 
-In this learning path we will use the `arm_spe` and `perf c2c` to diagnose a cache issue for an application running on a Neoverse server.
+Please refer to the [Arm SPE whitepaper](https://developer.arm.com/documentation/109429/latest/) for more details. 
 
-## False Sharing within the Cache
+In this Learning Path, you will use SPE and Perf C2C to diagnose a cache issue for an application running on a Neoverse server.
 
-Even when two threads touch entirely separate variables, modern processors move data in fixed-size cache lines (nominally 64-bytes). If those distinct variables happen to occupy bytes within the same line, every time one thread writes its variable the core’s cache must gain exclusive ownership of the whole line, forcing the other core’s copy to be invalidated. The second thread, still working on its own variable, then triggers a coherence miss to fetch the line back, and the ping-pong repeats. Please see the illustration below, taken from the [Arm_SPE whitepaper](https://developer.arm.com/documentation/109429/latest/), for a visual explanation.
+## False sharing within the cache
+
+Even when two threads touch entirely separate variables, modern processors move data in fixed-size cache lines (nominally 64-bytes). If those distinct variables happen to occupy bytes within the same line, every time one thread writes its variable the core’s cache must gain exclusive ownership of the whole line, forcing the other core’s copy to be invalidated. The second thread, still working on its own variable, then triggers a coherence miss to fetch the line back, and the ping-pong pattern repeats. Please see the illustration below, taken from the Arm SPE whitepaper, for a visual explanation.
 
 ![false_sharing_diagram](./false_sharing_diagram.png)
 
-Because false sharing hides behind ordinary writes, the easiest time to eliminate it is while reading or refactoring the source code padding or realigning the offending variables before compilation. In large, highly concurrent code-bases, however, data structures are often accessed through several layers of abstraction, and many threads touch memory via indirection, so the subtle cache-line overlap may not surface until profiling or performance counters reveal unexpected coherence misses.
+Because false sharing hides behind ordinary writes, the easiest time to eliminate it is while reading or refactoring the source code by padding or realigning the offending variables before compilation. In large, highly concurrent codebases, however, data structures are often accessed through several layers of abstraction, and many threads touch memory via indirection, so the subtle cache-line overlap may not surface until profiling or performance counters reveal unexpected coherence misses.
 
-From a source-code perspective nothing is “shared,” but at the hardware level both variables are implicitly coupled by their physical colocation.
+From a source-code perspective nothing is “shared,” but at the hardware level both variables are implicitly coupled by their physical location.
 
-## Alignment to Cache Lines
+## Alignment to cache lines
 
-In C++11, we can manually specify the alignment of an object using the `alignas` function. For example, in the C++11 source code below, we manually align the the `struct` every 64 bytes (typical cache line size on a modern processor). This ensures that each instance of `AlignedType` is on a separate cache line. 
+In C++11, you can manually specify the alignment of an object with the `alignas` specifier. For example, the C++11 source code below manually aligns the the `struct` every 64 bytes (typical cache line size on a modern processor). This ensures that each instance of `AlignedType` is on a separate cache line. 
 
 ```cpp
 #include <atomic>
@@ -48,7 +50,7 @@ int main() {
   std::atomic<int> c;
   std::atomic<int> d;
 
-  std::cout << "\n\nWithout Alignment can occupy same cache line\n\n";
+  std::cout << "\n\nWithout alignment, variables can occupy the same cache line\n\n";
   // Print out the addresses
   std::cout << "Address of atomic<int> a - " << &a << '\n';
   std::cout << "Address of atomic<int> b - " << &b << '\n';
@@ -72,9 +74,9 @@ int main() {
 }
 ```
 
-Example output below shows the variables e, f, g and h occur at least 64-bytes addreses apart in our byte-addressable architecture. Whereas variables a, b, c and d occur 8 bytes apart (i.e. occupy the same cache line). 
+The example output below shows the variables e, f, g and h occur at least 64-bytes apart in the byte-addressable architecture. Whereas variables a, b, c and d occur 8 bytes apart, occupying the same cache line. 
 
-Although this is a contrived example, in a production workload there may be several layers of indirection that unintentionally result in false sharing. For these complex cases, to understand the root cause we will use `perf c2c`.
+Although this is a contrived example, in a production workload there may be several layers of indirection that unintentionally result in false sharing. For these complex cases, to understand the root cause you will use Perf C2C.
 
 ```output
 Without Alignment can occupy same cache line
@@ -92,4 +94,6 @@ Address of AlignedType e - 0xffffeb6c6140
 Address of AlignedType f - 0xffffeb6c6100
 Address of AlignedType g - 0xffffeb6c60c0
 Address of AlignedType h - 0xffffeb6c6080
-```
+```
+
+Continue to the next section to learn how to set up a system to run Perf C2C.

content/learning-paths/servers-and-cloud-computing/false-sharing-arm-spe/how-to-2.md

@@ -1,47 +1,73 @@
 ---
-title: Setup
+title: Configure your environment for Arm SPE profiling
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Setup
+## Select a system with SPE support
 
-For this tutorial, I will use a `c6g.metal` instances running Amazon linux 2023 (AL23). Since `SPE` requires support both in hardware and the operating system, instances running specific distributions or kernels may not allow SPE-based profiling. 
+SPE requires both hardware and operating system support. Many cloud instances running Linux do not enable SPE-based profiling.
 
-We can check the underlying Neoverse IP and operating system kernel version with the following commands. 
+You need to identify a system that supports SPE using the information below. 
+
+If you are looking for an AWS system, you can use a `c6g.metal` instance running Amazon Linux 2023 (AL2023). 
+
+Check the underlying Neoverse processor and operating system kernel version with the following commands. 
 
 ```bash
 lscpu | grep -i "model name"
 uname -r
 ```
 
-Here we observe
+The output includes the CPU type and kernel release version:
 
 ```ouput
 Model name:                           Neoverse-N1
-6.1.134-150.224.amzn2023.aarch64
+6.1.134-152.225.amzn2023.aarch64
 ```
 
-Next install the prerequisite packages with the following command. 
+Next, install the prerequisite packages using the package manager:
 
 ```bash
 sudo dnf update -y
 sudo dnf install perf git gcc cmake numactl-devel -y
 ```
 
-Since the `linux` perf utility is a userspace process and SPE is a hardware feature in silicon, we use a built-in kernel module `arm_spe_pmu` to interact. Run the following command.
+Linux Perf is a userspace process and SPE is a hardware feature. The Linux kernel must be compiled with SPE support or the kernel module named `arm_spe_pmu` must be loaded.
+
+Run the following command to confirm if the SPE kernel module is loaded:
 
 ```bash
 sudo modprobe arm_spe_pmu
 ```
 
+If the module is not loaded (blank output), SPE may still be available.
+
+Run this command to check if SPE is included in the kernel:
+
+```bash
+ls /sys/bus/event_source/devices/ | grep arm_spe
+```
+
+If SPE is available, the output is:
+
+```output
+arm_spe_0
+```
+
+If the output is blank then SPE is not available.
+
 ## Run Sysreport
 
-A handy python script is available to summarise your systems capabilities with regard to performance profiling. Install and run System Report python script (`sysreport`) using the [instructions in the learning path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/sysreport/).
+You can install and run a Python script named Sysreport to summarize your system's performance profiling capabilities.
+
+Refer to [Get ready for performance analysis with Sysreport](https://learn.arm.com/learning-paths/servers-and-cloud-computing/sysreport/) to learn how to install and run it.
+
+Look at the Sysreport output and confirm SPE is available by checking the `perf sampling` field. 
 
-To check SPE is available on your system look at the `perf sampling` field. It should read `SPE` highlighted in green.
+If the printed value is SPE then SPE is available.
 
 ```output
 ...
@@ -57,29 +83,48 @@ Performance features:
   perf in userspace:   disabled
 ```
 
-## Confirm Arm_SPE Availability
+## Confirm Arm SPE is available to Perf
 
-Running the following command will confirm the availability of `arm_spe`. 
+Run the following command to confirm SPE is available to Perf: 
 
-```output
+```bash
 sudo perf list "arm_spe*"
 ```
 
-You should observe the following.
+You should see the output below indicating the PMU event is available.
 
 ```output
 List of pre-defined events (to be used in -e or -M):
 
   arm_spe_0//                                        [Kernel PMU event]
 ```
 
-If `arm_spe` is not available on your configuration, the `perf c2c` workload without `SPE` will fail. For example you will observe the following. 
+Assign capabilities to Perf by running:
+
+```bash
+sudo setcap cap_perfmon,cap_sys_ptrace,cap_sys_admin+ep $(which perf)
+```
+
+If `arm_spe` is not available because of your system configuration or if you don't have PMU permission, the `perf c2c` command will fail. 
+
+To confirm Perf can access SPE run:
+
+```bash
+perf c2c record
+```
+
+The output showing the failure is:
 
 ```output
-$ perf c2c record
 failed: memory events not supported
 ```
 
 {{% notice Note %}}
-If you are unable to use Arm SPE. It may be a restriction based on your cloud instance size or operating system. Generally, access to a full server (also known as metal instances) with a relatively new kernel is needed for Arm_SPE support. For more information, see the [perf-arm-spe manual page](https://man7.org/linux/man-pages/man1/perf-arm-spe.1.html)
+If you are unable to use SPE it may be a restriction based on your cloud instance size or operating system.
+
+Generally, access to a full server (also known as metal instances) with a relatively new kernel is needed for Arm SPE support. 
+
+For more information about enabling SPE, see the [perf-arm-spe manual page](https://man7.org/linux/man-pages/man1/perf-arm-spe.1.html)
 {{% /notice %}}
+
+Continue to learn how to use Perf C2C on an example application.

content/learning-paths/servers-and-cloud-computing/false-sharing-arm-spe/how-to-3.md

@@ -6,10 +6,11 @@ weight: 4
 layout: learningpathall
 ---
 
-## Example
+## Example code
 
-Copy and paste the `C++/C` example below into a file named `false_sharing_example.cpp`. The code example below has been adapted from [Joe Mario](https://github.com/joemario/perf-c2c-usage-files) and is discussed thoroughly in the [Arm Statistical Profiling Extension Whitepaper](https://developer.arm.com/documentation/109429/latest/).
+Use a text editor to copy and paste the C example code below into a file named `false_sharing_example.c`
 
+The code is adapted from [Joe Mario](https://github.com/joemario/perf-c2c-usage-files) and is discussed thoroughly in the Arm Statistical Profiling Extension Whitepaper.
 
 ```cpp
 /*
@@ -282,9 +283,13 @@ int main ( int argc, char *argv[] )
 }
 ```
 
-### Code Explanation
+### Code explanation
 
-The key data structure that occupies the cache is the `struct Buf`. With our system using a 64-byte cache line, each line can hold 8, 8-byte `long` integers. If we do **not** pass in the `NO_FALSE_SHARING` macro during compilation our `Buf` data structure will contain the elements below. Where each structure neatly occupies the entire 64-byte cache line. However, the 4 readers and 2 locks are now on the same cache line. 
+The key data structure that occupies the cache is `struct Buf`. With a 64-byte cache line size, each line can hold 8, 8-byte `long` integers. 
+
+If you do not pass in the `NO_FALSE_SHARING` macro during compilation the `Buf` data structure will contain the elements below. Each structure neatly occupies the entire 64-byte cache line. 
+
+However, the 4 readers and 2 locks are now accessing the same cache line. 
 
 ```output
 typedef struct _buf {
@@ -299,7 +304,9 @@ typedef struct _buf {
 } buf __attribute__((aligned (64)));
 ```
 
-Alternatively if we pass in the `NO_FALSE_SHARING` macro during compilation, our `Buf` structure has a different shape. The `(5*8-byte)` padding pushes the reader variables onto a different cache line. However, notice that this is with the tradeoff that our new `Buf` structures occupies 1 and a half cache lines (12 `long`s). Therefore we have unused cache space of 25% per `Buf` structure.
+Alternatively if you pass in the `NO_FALSE_SHARING` macro during compilation, the `Buf` structure has a different shape. 
+
+The 40 bytes of padding pushes the reader variables onto a different cache line. However, notice that this is with the tradeoff the new `Buf` structures occupies multiple cache lines (12 long integers). Therefore it leaves unused cache space of 25% per `Buf` structure.
 
 ```output
 typedef struct _buf {
@@ -314,14 +321,14 @@ typedef struct _buf {
 } buf __attribute__((aligned (64)));
 ```
 
-Compile the example with the command below. 
+Compile the example with the commands: 
 
 ```bash
 gcc -lnuma -pthread false_sharing_example.c -o false_sharing
 gcc -lnuma -pthread false_sharing_example.c -DNO_FALSE_SHARING -o no_false_sharing
 ```
 
-Running both binaries with the command like argument of 1 will show the following, with both binaries successfully return a 0 exit status but the `false_sharing` binary runs almost 2x slower!
+Run both binaries with the command line argument of 1. Both binaries successfully return a 0 exit status but the binary with the false sharing runs almost 2x slower!
 
 ```bash
 time ./false_sharing 1
@@ -338,3 +345,5 @@ user    0m8.869s
 sys     0m0.000s
 ```
 
+Continue to the next section to learn how to use Perf C2C to analyze the example code.
+