first pass performix instruction mix

Author: anupras-mohapatra-arm

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

@@ -1,24 +1,20 @@
 ---
 title: Profile GPT-2 instruction mix with Arm Performix
 
-draft: true
-cascade:
-    draft: true
-
 description: Learn how to profile GPT-2 inference on Arm Neoverse with the Arm Performix Instruction Mix recipe, identify scalar versus vector execution patterns, and improve throughput with NEON, SVE, and KleidiAI kernels.
 
 minutes_to_complete: 45
 
-who_is_this_for: This is an introductory topic for developers who want to get started using the instruction mix recipe in Arm Performix through a practical example.
+who_is_this_for: This is an introductory topic for developers who want to get started using the Arm Performix Instruction Mix recipe through a practical example.
 
 learning_objectives: 
-    - Explain how the Instruction Mix recipe combines static disassembly with runtime sampling to show execution behavior
+    - Understand how the Instruction Mix recipe combines static disassembly with runtime sampling to show execution behavior
     - Build and run the GPT-2 inference example on an Arm Linux server
     - Identify why matrix multiplication dominates runtime and how vectorization changes the instruction mix
     - Compare throughput and instruction mix across scalar, NEON, SVE, and KleidiAI implementations
 
 prerequisites:
-    - Access to Arm Performix configured with a remote Arm Linux target. For setup, see the [Arm Performix install guide](/install-guides/performix/)
+    - Access to Arm Performix configured with a remote Arm Linux target. For setup, see the [Arm Performix install guide](/install-guides/performix/).
     - Basic understanding of C++ and compiler optimization
     - Basic understanding of matrix multiplication
     - Basic understanding of writing SIMD code with Neon or SVE

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

@@ -1,44 +1,44 @@
 ---
-title: Understand instruction mix profiling
+title: Understand profiling with Arm Performix Instruction Mix
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Instruction mix overview
+## What the Arm Performix Instruction Mix recipe is
 
 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.
 
-The Instruction Mix recipe classifies each instruction into a group. The available groups depend on the Neoverse architecture version you are profiling. Therefore the categories you see may vary depending on the version of Arm Neoverse you are using. Typical categories include:
+The Instruction Mix recipe classifies each instruction into a group. The available groups depend on the Neoverse architecture version you are profiling. Therefore the categories you see might vary depending on the version of Arm Neoverse you are using. Typical categories include:
 
 - integer and floating-point arithmetic
 - memory loads and stores (including exclusive operations)
 - control flow instructions, such as branches and loops
 - specialized instructions, such as cryptographic operations
 - SIMD (Single Instruction, Multiple Data) instructions, including NEON (fixed 128-bit) and SVE (scalable vector length)
 
-The instruction mix result gives you two complementary views:
+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.
 
-## Detecting missed vectorization
-
-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.
+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.
 
 For example, if a hot function is mostly scalar at runtime when you expected NEON or SVE activity, that often indicates missed vectorization opportunities. You can then focus optimization work on compiler flags, data layout, loop structure, and kernel implementation to improve throughput where it matters most.
 
 ## GPT-2 as a test workload
 
 You can run the [GPT-2 Medium](https://huggingface.co/openai-community/gpt2-medium) model on a minimal C++ inference engine to analyze instruction mix and throughput. This model is available under a [modified MIT License](https://github.com/openai/gpt-2/blob/master/LICENSE). You will confirm that matrix multiplication (`matmul`) is the hot path, then compare how scalar, NEON, and SVE implementations change instruction behavior and token generation speed. 
 
-This example implements only the forward inference path, with no back propagation or training. You do not need to understand the full transformer architecture to complete this Learning Path. Familiarity with matrix multiplication is enough. For background on GPT-2, see the original 2019 paper, [Language Models are Unsupervised Multitask Learners](https://cdn.openai.com/better-language-models/language_models_are_unsupervised_multitask_learners.pdf)
+You'll implement only the forward inference path, with no back propagation or training. You don't need to understand the full transformer architecture to complete this Learning Path. Familiarity with matrix multiplication is enough. For background on GPT-2, see the original 2019 paper, [Language Models are Unsupervised Multitask Learners](https://cdn.openai.com/better-language-models/language_models_are_unsupervised_multitask_learners.pdf).
+
+You'll also try implementing your own `matmul` kernels that target NEON and SVE, then use instruction mix data to verify that these vector paths are active and improving throughput.
 
-You will also try implementing your own `matmul` kernels that target NEON and SVE, then use instruction mix data to verify that these vector paths are active and improving throughput.
+## What you've learned and what's next
 
-## Next steps
+You now know what instruction mix represents and why it matters for LLM inference optimization on Arm.
 
-You now know what instruction mix 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.
+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

@@ -1,5 +1,5 @@
 ---
-title: Set up and run GPT-2 baseline
+title: Set up and run a GPT-2 baseline
 weight: 3
 
 ### FIXED, DO NOT MODIFY
@@ -8,7 +8,9 @@ layout: learningpathall
 
 ## Prepare the environment
 
-Use an Arm Linux target, such as an Arm Neoverse cloud instance. The results in this Learning Path were collected on a Graviton 3 instance based on Neoverse V1 running Ubuntu 24.04 LTS. If you have not configured Arm Performix yet, complete setup and target connection using the [Arm Performix install guide](/install-guides/performix/).
+Use an Arm Linux target, such as an Arm Neoverse 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. 
+
+If you've not configured Arm Performix yet, complete setup and target connection using the [Arm Performix install guide](/install-guides/performix/).
 
 Install build prerequisites and clone the GPT-2 example repository:
 
@@ -109,6 +111,8 @@ The output is:
 
 ![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")
 
-## Next steps
+## What you've accomplished and what's next
+
+You now have a working baseline binary and model files. 
 
-You now have a working baseline binary and model files. Next, you'll use the Instruction Mix recipe in Arm Performix to inspect static disassembly and dynamic runtime behavior.
+Next, you'll use the Instruction Mix recipe in Arm Performix to inspect static disassembly and dynamic runtime behavior.

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

@@ -1,5 +1,5 @@
 ---
-title: Profile with instruction mix
+title: Profile with the Arm Performix Instruction Mix recipe
 weight: 4
 
 ### FIXED, DO NOT MODIFY
@@ -12,29 +12,29 @@ 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 as per the command below. 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 command below as the Performix Workload. If your path is different adjust it to point to `gpt2`. 
+Copy and paste the following command as the Performix Workload. If your path is different, adjust it to point to `gpt2`:
 
 ```console
 /home/ubuntu/GPT-2-Example/build/gpt2 --model gpt2-medium "Once upon a time" -n  150
 ```
 
 ![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 with show 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-clicking on the function shows which lines of source code the samples 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")
 
 This confirms that matrix multiplication is the highest-impact optimization target.
 
 ## Assess compiler output
 
-We can use online tools such as [Compiler Explorer](https://godbolt.org/) to conveniently see how this function is being compiled with the `-O2 -g` flags. The example below uses `GCC 12.1.0`. You can check your installed compiler version with the `g++ --version` command and select the corresponding version from the Compiler Explorer drop-down menu. The generated assembly may differ slightly across compiler versions.
+You can use online tools such as [Compiler Explorer](https://godbolt.org/) to conveniently see how this function is being compiled with the `-O2 -g` flags. The following example uses `GCC 12.1.0`. You can check your installed compiler version with the `g++ --version` command and select the corresponding version from the Compiler Explorer drop-down menu. The generated assembly might differ slightly across compiler versions.
 
 {{< 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 would 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 does not show whether changing compiler flags introduces regressions in other parts of the codebase. Third, and most importantly, this static view does not show which instructions in this function run most often on the CPU.
+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.
 
 The Instruction Mix recipe helps fill this gap.
 
@@ -48,26 +48,30 @@ Set the launch command to your baseline binary with the same runtime arguments u
 /home/ubuntu/GPT-2-Example/build/gpt2 --model gpt2-medium "Once upon a time" -n  150
 ```
 
-Note about number of counters.
+Note the number of counters.
 
 Use the same model and prompt arguments as your baseline terminal run so the measurements are comparable.
 
 ![Arm Performix recipe setup screen showing Instruction Mix recipe selected with launch settings configured for the GPT-2 baseline executable.#center](./configuring-performix.webp "Configure Arm Performix Instruction Mix recipe")
 
 ### 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. 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.
+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.
+
+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")
 
 ### 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.
+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")
 
 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.
 
-## Next steps
+## 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. 
 
-You used Instruction Mix to confirm that baseline runtime is dominated by scalar-heavy `matmul` execution. Next, you'll compare updated instruction mix and throughput across scalar, NEON, SVE, and KleidiAI variants.
+Next, you'll 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

@@ -1,12 +1,12 @@
 ---
-title: Optimize matmul with vector intrinsics
+title: (Optional) Optimize matmul with vector intrinsics
 weight: 5
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Complete the challenge (optional)
+## 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.
 
@@ -34,7 +34,7 @@ Example solutions are available in:
 
 You can use `AGENTS.md` in the GPT-2 example repository for guided learning support.
 
-### Use the Arm MCP Server with Performix (optional)
+### Use the Arm MCP Server with Performix 
 
 You can also use an MCP-compatible coding assistant, such as GitHub Copilot or Codex, with the Arm MCP Server. This gives the assistant direct tool access to run Performix recipes on your remote Arm target and create a faster feedback loop while you iterate on `matmul_user`.
 
@@ -66,6 +66,8 @@ Restart your coding assistant, then prompt it to run Performix Instruction Mix a
 
 ![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")
 
-## Next steps
+## What you've accomplished and what's next
 
-In this optional section, you implemented and profiled a custom `matmul_user` kernel using the same workflow you used for baseline analysis. Next, you'll compare instruction mix and throughput across scalar, NEON, SVE, and KleidiAI variants.
+You've now optionally implemented and profiled a custom `matmul_user` kernel using the same workflow you used for baseline analysis. 
+
+Next, you'll compare instruction mix and throughput across scalar, NEON, SVE, and KleidiAI variants.