# (Optional) Optimize matmul with vector intrinsics

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/)
- [Understand profiling with Arm Performix Instruction Mix](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-1/)
- [Set up and run a GPT-2 baseline](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-2/)
- [Find GPT-2 hotspots and profile with the Arm Performix Instruction Mix recipe](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3/)
- [(Optional) Optimize matmul with vector intrinsics](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4/)
- [Compare Neon and SVE with the Arm Performix Instruction Mix recipe](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5/)
- [Accelerate execution with KleidiAI](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-6/)
- [Next Steps](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_next-steps/)

## Complete the challenge
`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`.

> **Note**  
> Focus on the accumulation loop in `matmul_user` (`acc += row[j] * x[j];`). Think about lane utilization, loop unrolling, and handling the tail when the input width is not an exact multiple of the vector width.

Rebuild after your edits:
```bash
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.

Example solutions are available in:
- `src/kernels/matmul_neon.cpp`
- `src/kernels/matmul_sve.cpp`

You can use `AGENTS.md` in the GPT-2 example repository for guided learning support.

### 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`.

For setup details, see [Automate x86-to-Arm application migration using Arm MCP Server](https://learn.arm.com/learning-paths/servers-and-cloud-computing/arm-mcp-server/).

Install Docker if needed, then pull the MCP server image:
```bash
docker pull armlimited/arm-mcp:latest
```
To allow Performix access to remote targets from inside the container, mount your workspace plus SSH key and known hosts in your Codex MCP configuration (example `~/.codex/config.toml`):
```toml
[mcp_servers.arm-mcp]
command = "docker"
args = [
	"run",
	"--rm",
	"-i",
	"-v", "/path/to/your/workspace:/workspace",
	"-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro",
	"-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro",
	"armlimited/arm-mcp"
]
```
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.

![Coding assistant prompt for Performix analysis through Arm MCP Server](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-instruction-mix/./mcp-performix-prompt.webp "Coding assistant prompt for Performix analysis through Arm MCP Server")

## What you’ve accomplished and what’s next
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.