another set of edits

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_index.md

@@ -55,7 +55,7 @@ further_reading:
         type: website
     - resource:
         title: KleidiAI GitHub Repository
-        link: https://github.com/ARM-software/kleidiai
+        link: https://gitlab.arm.com/kleidi/kleidiai
         type: website
     - resource:
         title: GPT-2 Example repository

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-1.md

@@ -6,7 +6,7 @@ weight: 2
 layout: learningpathall
 ---
 
-## What the Arm Performix Instruction Mix recipe is
+## Why to use the Arm Performix Instruction Mix recipe
 
 The Arm Performix Instruction Mix recipe shows the types and proportions of machine instructions your workload executes at runtime and in static analysis, so you can see how efficiently your code uses Arm CPU hardware resources.
 
@@ -23,7 +23,7 @@ The Instruction Mix result gives you two complementary views:
 - static analysis, which inspects compiled machine code without running it
 - dynamic analysis, which measures instruction usage during real execution
 
-Together, these views help you verify whether architecture-specific features are actually active in hot code paths.
+Together, these views help you verify whether architecture-specific features are active in hot code paths.
 
 Instruction Mix is useful when you need to confirm that performance-critical code uses Arm CPU features effectively. This is especially helpful when you are, for example, validating the effectiveness of compiler autovectorization.
 
@@ -39,6 +39,6 @@ You'll also try implementing your own `matmul` kernels that target Neon and SVE,
 
 ## What you've learned and what's next
 
-You now know what instruction mix represents and why it matters for LLM inference optimization on Arm.
+You now know what the Arm Instruction Mix recipe represents and why it matters for LLM inference optimization on Arm.
 
 Next, you'll set up the GPT-2 example, build the binaries, and run a baseline test.

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-2.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Prepare the environment
 
-Use an Arm Linux target, such as an Arm Neoverse-based cloud instance. The results in this Learning Path were collected on a Graviton 3-based instance based on Neoverse V1 running Ubuntu 24.04 LTS. 
+Use an Arm Linux target, such as an Arm Neoverse-based cloud instance. The results in this Learning Path were collected on a Graviton 3-based Amazon EC2 instance running Ubuntu 24.04 LTS.  
 
 If you've not configured Arm Performix yet, complete setup and target connection using the [Arm Performix install guide](/install-guides/performix/).
 
@@ -26,8 +26,6 @@ git checkout tags/v0.0.2
 
 The C++ runtime expects exported model binaries. Create a Python virtual environment, install dependencies, and export GPT-2 Medium weights and vocabulary:
 
-The workload uses [openai-community/gpt2-medium on Hugging Face](https://huggingface.co/openai-community/gpt2-medium), which corresponds to the GPT-2 Medium model from the original OpenAI GPT-2 release in 2019. The model has 355 million parameters, and in this workflow it runs with unquantized FP32 (32-bit floating-point) weights.
-
 ```bash
 python3 -m venv venv
 source venv/bin/activate
@@ -40,9 +38,11 @@ This creates:
 - `models/gpt2-medium/weights.bin`
 - `models/gpt2-medium/vocab.bin`
 
+The workload uses [openai-community/gpt2-medium on Hugging Face](https://huggingface.co/openai-community/gpt2-medium), which corresponds to the GPT-2 Medium model from the original OpenAI GPT-2 release in 2019. The model has 355 million parameters and runs with unquantized FP32 (32-bit floating-point) weights.
+
 ## Review the source code
 
-The `src/gpt2.cpp` file implements the end-to-end GPT-2 inference loop. Each generated token triggers a forward pass over all 24 transformer layers. Inside each layer, `matmul` is called multiple times: for the query/key/value projection, the attention output projection, and both feed-forward layers. It is called once more at the end for logits projection over the vocabulary:
+The `src/gpt2.cpp` file implements the end-to-end GPT-2 inference loop. Each generated token triggers a forward pass over all 24 transformer layers. Inside each layer, `matmul` is called multiple times for the query, key, and value projection, the attention output projection, and both feed-forward layers. It's called once more at the end for `logits` projection over the vocabulary:
 
 ```cpp
 // Attention QKV projection
@@ -76,7 +76,7 @@ static void matmul(float *out, const float *x, const float *W, const float *b,
 }
 ```
 
-The baseline kernel (`src/kernels/matmul_ref.cpp`) is a straightforward scalar nested for loop: for each output row, it walks the weight matrix row and accumulates a dot product with the input vector:
+The baseline kernel (`src/kernels/matmul_ref.cpp`) is a scalar nested for loop: for each output row, it walks the weight matrix row and accumulates a dot product with the input vector:
 
 ```cpp
 void matmul_ref(float *out, const float *x, const float *W, const float *b,
@@ -90,24 +90,25 @@ void matmul_ref(float *out, const float *x, const float *W, const float *b,
 }
 ```
 
-This scalar implementation can leave Neon and SVE vector units underused if the compiler cannot efficiently autovectorize it. Because `matmul` is called hundreds of times per token, explicitly optimizing this kernel guarantees SIMD execution where most of the available compute is spent.
+This scalar implementation can leave Neon and SVE vector units underused if the compiler can't efficiently autovectorize it. Because `matmul` is called hundreds of times per token, explicitly optimizing this kernel guarantees SIMD execution where most of the available compute is spent.
 
 ## Build and run the baseline
 
-Configure and build the project with CMake. The project uses `-O2 -g`, which keeps optimization enabled while preserving debug symbols for profiling.
+Configure and build the project with CMake:
 
 ```bash
 cmake -S . -B build -DBUILD_USER_MATMUL=ON
 cmake --build build --parallel
 ```
+The project uses `-O2 -g`, which keeps optimization enabled while preserving debug symbols for profiling.
 
 Run the scalar baseline binary:
 
 ```bash
 ./build/gpt2 --model gpt2-medium "Once upon a time" -n 20
 ```
 
-The output is:
+The output is similar to:
 
 ![Animated terminal output showing GPT-2 baseline inference running on Arm Linux, including generated text and the final tokens-per-second summary.#center](./gpt2-baseline.gif "GPT-2 baseline runtime output on Arm Linux")
 

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3.md

@@ -12,7 +12,7 @@ Before you optimize, identify where the application spends most of its time. Use
 
 Open Arm Performix and select the **Code Hotspots** recipe. If this is your first run on the target, complete tool deployment as prompted.
 
-Set the launch command to your baseline binary with the number of tokens (`-n`) set to 150. This value keeps startup overhead small compared to inference time, so the profile minimizes the time taken to load the model weights.
+Set the launch command to your baseline binary with the number of tokens (`-n`) set to `150`. This value keeps startup overhead small compared to inference time, so the profile minimizes the time taken to load the model weights.
 
 Copy and paste the following command as the Performix Workload. If your path is different, adjust it to point to `gpt2`:
 
@@ -22,9 +22,9 @@ Copy and paste the following command as the Performix Workload. If your path is
 
 ![Arm Performix Code Hotspots recipe configuration showing launch arguments for the GPT-2 baseline run with -n 150 to emphasize inference runtime.#center](./code_hotspot.webp "Code Hotspots recipe configuration for GPT-2 baseline")
 
-The results show that `kernels::matmul_ref()` is the hottest function. Double-clicking on the function shows which lines of source code the samples are mostly attributed to the accumulate step of `kernels::matmul_ref()`.
+The results show that `kernels::matmul_ref()` is the hottest function. Double-click on the function to see which lines of source code are mostly attributed to the accumulate step of `kernels::matmul_ref()`.
 
-![Arm Performix hotspot results table showing matmul_ref as the dominant runtime function during GPT-2 baseline inference.#center](./code_hotspot_results.webp "Hotspot results highlighting matmul_ref")
+![Arm Performix hotspot results table showing `matmul_ref` as the dominant runtime function during GPT-2 baseline inference.#center](./code_hotspot_results.webp "Hotspot results highlighting `matmul_ref`")
 
 This confirms that matrix multiplication is the highest-impact optimization target.
 
@@ -34,7 +34,9 @@ You can use online tools such as [Compiler Explorer](https://godbolt.org/) to co
 
 {{< godbolt width="100%" height="400px" mode="assembly" opt="-O2 -g" src="void matmul_ref(float *out, const float *x, const float *W, const float *b, int n_in, int n_out)\n{\n  for (int i = 0; i < n_out; i++) {\n    float acc = b ? b[i] : 0.f;\n    const float *row = W + (unsigned long long)i * (unsigned long long)n_in;\n    for (int j = 0; j < n_in; j++) {\n      acc += row[j] * x[j];\n    }\n    out[i] = acc;\n  }\n}" >}}
 
-This view helps you spot missed vectorization opportunities. In an optimized build, you'd expect the accumulation step to use SIMD instructions, for example `fmla v0.4s, v3.4s, v2.4s` with use of the vector register (`v0->v3`). However, assembly inspection has limitations. First, you need familiarity with SIMD mnemonics to recognize vectorized code. Second, this narrow snippet doesn't show whether changing compiler flags introduces regressions in other parts of the codebase. Third, and most importantly, this static view doesn't show which instructions in this function run most often on the CPU.
+With this view, you can spot missed vectorization opportunities. In an optimized build, you'd expect the accumulation step to use SIMD instructions, for example `fmla v0.4s, v3.4s, v2.4s` with use of the vector register (`v0->v3`). However, assembly inspection has limitations. 
+
+First, you need familiarity with SIMD mnemonics to recognize vectorized code. Second, this narrow snippet doesn't show whether changing compiler flags introduces regressions in other parts of the codebase. Third, and most importantly, this static view doesn't show which instructions in this function run most often on the CPU.
 
 The Instruction Mix recipe helps fill this gap.
 
@@ -56,22 +58,22 @@ Use the same model and prompt arguments as your baseline terminal run so the mea
 
 ### Analyze static disassembly
 
-After the run completes, review static disassembly first. This view is ordered by percentage contribution and provides a high-level profile of the application’s generated instruction stream. It can help you identify broad characteristics, such as whether the code is branch-heavy, dominated by memory operations, or making effective use of SIMD instructions.
+After the run completes, review static disassembly first. This view is ordered by percentage contribution and provides a high-level profile of the application’s generated instruction stream. By reviewing static disassembly, you can identify broad characteristics, such as whether the code is branch-heavy, dominated by memory operations, or making effective use of SIMD instructions.
 
 Use this static view to understand overall code generation patterns rather than to attribute performance to specific functions or source lines. Dynamic analysis is typically more relevant for optimization because it reflects the instructions that are actually executed at runtime.
 
-![Arm Performix static disassembly view showing instruction category breakdown for GPT-2 hot paths, highlighting scalar-heavy sections in baseline matmul code.#center](./static_disassembly.webp "Static disassembly instruction classification")
+![Arm Performix static disassembly view showing instruction category breakdown for GPT-2 hot paths, highlighting scalar-heavy sections in baseline `matmul` code.#center](./static_disassembly.webp "Static disassembly instruction classification")
 
 ### Dynamic analysis
 
 Then, inspect dynamic analysis bar chart to see where sampled runtime work is concentrated. Dynamic data is typically more useful for optimization because it reflects actual execution behavior for your input, runtime settings, and call frequencies.
 
-![Arm Performix dynamic functions table showing most runtime samples in matmul-related functions for baseline GPT-2 inference.#center](./instruction_mix_dynamic_analysis.webp "Dynamic function sample distribution")
+![Arm Performix dynamic functions table showing most runtime samples in functions related to `matmul` for baseline GPT-2 inference.#center](./instruction_mix_dynamic_analysis.webp "Dynamic function sample distribution")
 
 Finally, in dynamic functions, you can break down operation types to individual functions. This is particularly useful when no single function dominates the profile, allowing you to inspect dynamic instruction patterns for specific functions.
 
 ## What you've accomplished and what's next
 
 You've now used Instruction Mix to confirm that baseline runtime is dominated by scalar-heavy `matmul` execution. 
 
-Next, you can optionally learn to optimize matmul with vector intrinsics and use the Arm MCP Server with Performix. You can also skip to [Compare Neon and SVE with the Arm Performix Instruction Mix recipe](/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5/) to compare updated Instruction Mix and throughput across scalar, Neon, SVE, and KleidiAI variants.
+Next, you can optionally learn to optimize `matmul` with vector intrinsics and use the Arm MCP Server with Performix. You can also skip to [Compare Neon and SVE with the Arm Performix Instruction Mix recipe](/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5/) to compare updated Instruction Mix and throughput across scalar, Neon, SVE, and KleidiAI variants.

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Complete the challenge 
 
-In this project, `src/kernels/matmul_user.cpp` is your editable implementation file. The baseline behavior in this file is scalar, and the build uses `-O2 -g`, so compiler optimization is enabled but vector hardware is still underused in the hot loop.
+`src/kernels/matmul_user.cpp` is your editable implementation file. The baseline behavior in this file is scalar, and the build uses `-O2 -g`, so compiler optimization is enabled but vector hardware is still underused in the hot loop.
 
 Use the profiling evidence from Performix to implement your own Neon or SVE intrinsics in `src/kernels/matmul_user.cpp`, then rebuild and profile `gpt2_user`.
 
@@ -25,7 +25,7 @@ cmake -S . -B build -DBUILD_USER_MATMUL=ON
 cmake --build build --parallel
 ```
 
-Then profile the `build/gpt2_user` binary with the same runtime arguments and compare the Instruction Mix and throughput against baseline.
+Then, profile the `build/gpt2_user` binary with the same runtime arguments and compare the Instruction Mix and throughput against baseline.
 
 Example solutions are available in:
 
@@ -64,7 +64,7 @@ args = [
 
 Restart your coding assistant, then prompt it to run Performix Instruction Mix and Code Hotspots on your `gpt2_user` binary and suggest Arm intrinsics improvements.
 
-![Screenshot of a coding assistant prompt configured to use Arm MCP Server tools for running Performix recipes and analyzing matmul_user optimization opportunities in the GPT-2 workload.#center](./mcp-performix-prompt.webp "Coding assistant prompt for Performix analysis through Arm MCP Server")
+![Screenshot of a coding assistant prompt configured to use Arm MCP Server tools for running Performix recipes and analyzing `matmul_user` optimization opportunities in the GPT-2 workload.#center](./mcp-performix-prompt.webp "Coding assistant prompt for Performix analysis through Arm MCP Server")
 
 ## What you've accomplished and what's next
 

content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5.md

@@ -30,9 +30,9 @@ Rename each run with a descriptive name, such as baseline and Neon, so you can i
 
 The baseline profile is mostly scalar instructions. After you add Neon intrinsics, the instruction mix shifts toward Advanced SIMD (Neon) instructions, showing that the code is using Arm Neon hardware more effectively.
 
-![Instruction Mix comparison view showing scalar-dominant baseline versus Neon variant with increased ASIMD instruction share in the hot matmul path.#center](./neon_scalar_instruction_mix.webp "Neon versus scalar instruction mix")
+![Instruction Mix comparison view showing scalar-dominant baseline versus Neon variant with increased ASIMD instruction share in the hot `matmul` path.#center](./neon_scalar_instruction_mix.webp "Neon versus scalar instruction mix")
 
-You can also compare SVE variants in the same way. The increase in SVE operations shows that this path is now utilizing SVE hardware.
+You can also compare SVE variants in the same way. The increase in SVE operations shows that this path is now using SVE hardware.
 
 ![Instruction Mix comparison between baseline and SVE variant showing increased vector instruction usage and reduced scalar share in hot execution paths.#center](./sve_vs_baseline.webp "SVE versus baseline instruction mix")
 
@@ -54,7 +54,7 @@ For variable-length vectorization, compare with an explicit SVE implementation t
 {{< godbolt width="100%" height="400px" mode="assembly" opt="-O2 -g -march=armv8.2-a+sve" src="#include <arm_sve.h>\n#include <stddef.h>\n\nvoid matmul_sve(float *out, const float *x, const float *W, const float *b,\n                int n_in, int n_out) {\n    for (int i = 0; i < n_out; i++) {\n        float acc = b ? b[i] : 0.f;\n        const float *row = W + (size_t)i * n_in;\n        svfloat32_t vacc = svdup_f32(0.f);\n        int j = 0;\n        while (j < n_in) {\n            svbool_t pg = svwhilelt_b32((uint64_t)j, (uint64_t)n_in);\n            svfloat32_t vw = svld1(pg, row + j);\n            svfloat32_t vx = svld1(pg, x + j);\n            vacc = svmla_f32_m(pg, vacc, vw, vx);\n            j += svcntw();\n        }\n        acc += svaddv_f32(svptrue_b32(), vacc);\n        out[i] = acc;\n    }\n}" >}}
 
 
-For a full-page view, open a [Godbolt session with all three matmul kernels](https://godbolt.org/z/E4a7Wxh8K).
+For a full-page view, open a [Godbolt session with all three `matmul` kernels](https://godbolt.org/z/E4a7Wxh8K).
 
 ## Measure speedup