Merge pull request #3497 from anupras-mohapatra-arm/servers-and-cloud-computing

Arm Instruction Mix recipe for Performix LP review + slight skill tweaks

Author: pareenaverma

.github/skills/learning-path-structure-review/SKILL.md

@@ -10,7 +10,7 @@ Use this skill when a Learning Path needs a structural review. Focus on whether
 ## Workflow
 
 1. Identify the Learning Path directory and read the relevant Markdown files together.
-2. State the owned developer task in one sentence. If the task is unclear, too broad, or split across unrelated goals, flag it.
+2. Summarize the developer task owned by LP in one sentence. If the task is unclear, too broad, or split across unrelated goals, flag it.
 3. Check the required file shape:
    - The Learning Path has an `_index.md` file.
    - The Learning Path has an `_next-steps.md` file.

.github/skills/seo-geo-aeo-review/SKILL.md

@@ -23,9 +23,11 @@ For focused front matter `description` edits only, use `.github/skills/metadata-
 
 ## Workflow
 
+On any given page:
+
 1. Identify the target content type and target developer intent. 
-2. Read the title, front matter description, headings, introduction, prerequisites, main task flow, validation, conclusion, and further reading. If you've previously read a page, use context and don't re-read it unless there's a change since the last read. 
-3. State the page's owned task in one sentence. If the task is unclear or too broad, flag it.
+2. Read the title, front matter description, headings, introduction, prerequisites, main task flow, validation, conclusion, and further reading. If you've previously read the page, use context and don't re-read it unless asked to. 
+3. Summarize the page's owned task in one sentence. If the task is unclear or too broad, flag it.
 4. Review SEO signals:
    - The title is task-led and includes the main technology, platform, or tool.
    - The `description` is one concise sentence that states the task, context, and outcome.

.github/skills/writing-style-review/SKILL.md

@@ -10,10 +10,10 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 ## Workflow
 
 1. Identify the target file, section, or selected text.
-2. Read surrounding context so style edits preserve the author's intent and the technical flow. If you've previously read the page, use context and don't re-read it unless there's a change since the last read. 
+2. Read surrounding context so style edits preserve the author's intent and the technical flow. If you've previously read the page, use context and don't re-read it unless asked to. 
 3. Review the target against the guidelines defined in this skill.
 4. Depending on request type, do the following:
-  - For review requests, report high-impact style issues by file and line when possible. 
+  - For review requests, report style issues by file and line when possible, ordered by severity. 
   - For edit requests, make focused rewrites, then re-open changed sections to check Markdown, shortcodes, links, and code fences.
 
 ## Voice and tone

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

@@ -1,32 +1,78 @@
 ---
-title: Profile GPT-2 instruction mix with Arm Performix
+title: Profile GPT-2 inference with the Arm Performix Instruction Mix recipe
 
-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.
+description: 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
+    - Use the Instruction Mix recipe to combine 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
+    - 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
 
+# START generated_summary_faq
+generated_summary_faq:
+  template_version: summary-faq-v3
+  generated_at: '2026-07-15T19:50:40Z'
+  generator: ai
+  ai_assisted: true
+  ai_review_required: true
+  model: gpt-5
+  prompt_template: summary-faq-v3
+  source_hash: 22b8b268d361bfa326a92845a7a0878e26719ef182c3e907fd6da5dcd5503388
+  summary_generated_at: '2026-07-15T19:50:40Z'
+  summary_source_hash: 22b8b268d361bfa326a92845a7a0878e26719ef182c3e907fd6da5dcd5503388
+  faq_generated_at: '2026-07-15T19:50:40Z'
+  faq_source_hash: 22b8b268d361bfa326a92845a7a0878e26719ef182c3e907fd6da5dcd5503388
+  summary: >-
+    You'll build a GPT-2 inference example on an Arm Linux target and use Arm Performix to analyze
+    execution behavior. After running the Code Hotspots recipe to locate the dominant `matmul`
+    kernel, you'll use the Instruction Mix recipe to compare scalar and vector execution patterns
+    on Arm Neoverse. You'll then compare the scalar `gpt2` baseline with `gpt2_neon`, `gpt2_sve`,
+    optional `gpt2_user`, and the KleidiAI-backed `gpt2_kai_sve` path, validating vectorization
+    and throughput changes with Performix data and tokens-per-second results.
+  faqs:
+  - question: Which Performix recipe should I run first to find the bottleneck?
+    answer: >-
+      Start with the Code Hotspots recipe. Set the launch command to the baseline binary and use
+      `-n 150` to bias the profile toward inference time, then review the top functions.
+  - question: How do I know that matrix multiplication is the hotspot before I change any code?
+    answer: >-
+      The Code Hotspots report ranks functions by sampled time, so `kernels::matmul_ref()` should appear
+      near the top. Use that evidence to decide where to focus subsequent Instruction Mix profiling.
+  - question: Where do I add my Neon or SVE intrinsics, and what part of the loop should I change?
+    answer: >-
+      Edit `src/kernels/matmul_user.cpp`. Focus on the accumulation loop, `acc += row[j] * x[j];`,
+      and consider lane utilization, loop unrolling, and how you handle the tail.
+  - question: What binaries should I expect after building, and where are the reference implementations?
+    answer: >-
+      The build produces the scalar baseline `gpt2`, reference variants `gpt2_neon` and `gpt2_sve`,
+      and `gpt2_user` when the user kernel is enabled. The reference kernels are implemented in
+      `matmul_neon.cpp` and `matmul_sve.cpp`.
+  - question: How do I verify that my vectorization worked using Performix?
+    answer: >-
+      Profile your rebuilt binary with the Instruction Mix recipe and compare the proportion of
+      vector instructions with the baseline. You can also run the reference `gpt2_neon` and `gpt2_sve`
+      and compare instruction mix and the program's tokens-per-second summary.
+# END generated_summary_faq
+
 author:
     - Kieran Hejmadi
     - Oliver Grainge
 
+generate_summary_faq: false
+rerun_summary: false
+rerun_faqs: false
+
 ### Tags
 skilllevels: Introductory
 subjects: Performance and Architecture
@@ -36,7 +82,7 @@ tools_software_languages:
     - Arm Performix
     - C
     - LLM
-    - NEON
+    - Neon
     - SVE
 operatingsystems:
     - Linux
@@ -57,6 +103,10 @@ further_reading:
         title: Arm MCP Server GitHub Repository
         link: https://github.com/arm/mcp
         type: website
+    - resource:
+        title: KleidiAI GitHub Repository
+        link: https://gitlab.arm.com/kleidi/kleidiai
+        type: website
     - resource:
         title: GPT-2 Example repository
         link: https://github.com/arm-education/GPT-2-Example
@@ -69,4 +119,4 @@ further_reading:
 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-instruction-mix/how-to-1.md

@@ -1,44 +1,45 @@
 ---
-title: Understand instruction mix profiling
+title: Understand profiling with Arm Performix Instruction Mix
+description: See how the Arm Performix Instruction Mix recipe combines static disassembly and runtime sampling to reveal scalar and vector execution patterns in GPT-2 inference.
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Instruction mix overview
+## 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.
 
-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)
+- 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.
+Together, these views help you verify whether architecture-specific features are 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.
+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. 
+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. 
+
+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).
 
-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 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 the Arm Instruction Mix recipe 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.