# xjn-la-la-land/amx-gemm-handwritten architecture

> Architecture diagram of the GitHub repository xjn-la-la-land/amx-gemm-handwritten, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xjn-la-la-land/amx-gemm-handwritten
- Repository: https://github.com/xjn-la-la-land/amx-gemm-handwritten

## Overview

This repository implements and benchmarks int8 AMX GEMM in offline-prepacked and online-packing variants. The main workflow is to configure matrix sizes and benchmark conditions, initialize a variant-specific plan, run repeated AMX computations, and record performance results for analysis. The README also documents CPU/perf-based experiments and plotting utilities. Sampled sources show harness planning and compute paths, but not every variant’s entry-point wiring; the graph omits uncertain links.

Main entry points: [`src/common/bench_harness.hpp`](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp) (Benchmark harness), [`src/online-packing/gemm-test.cpp`](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/gemm-test.cpp) (Online variant), [`src/offline-packing/gemm-test.cpp`](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/offline-packing/gemm-test.cpp) (Offline variant), [`scripts/bench.sh`](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/bench.sh) (Benchmark orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Benchmark runtime"]
  node_config["CLI and config<br/>[bench_harness.hpp]"]
  node_harness["Benchmark harness<br/>[bench_harness.hpp]"]
  node_inputs["Matrix inputs<br/>[bench_harness.hpp]"]
  node_threading["NUMA threading<br/>[thread_params.hpp]"]
  node_results["CSV results<br/>[bench_harness.hpp]"]
end

subgraph group_kernels["GEMM variants"]
  node_offline["Offline variant<br/>[gemm-test.cpp]"]
  node_offlinepack["Offline packing<br/>[amx-gemm.cpp]"]
  node_online["Online variant<br/>[gemm-test.cpp]"]
  node_onlinepack["Online packing<br/>[amx-gemm.cpp]"]
  node_autotune["Block autotuning<br/>[autotune.hpp]"]
  node_buffers["Packed buffers<br/>[page_alloc.hpp]"]
end

subgraph group_experiments["Experiment controls"]
  node_bench["Benchmark orchestration<br/>[bench.sh]"]
  node_system["CPU controls<br/>[cpu-isolation.py]"]
  node_frequency["Frequency control<br/>[freq.sh]"]
  node_perf["Perf counters"]
end

subgraph group_analysis["Results analysis"]
  node_plots["Plot utilities<br/>[plot_amx_util.py]"]
  node_stageplots["Stage plots"]
end

node_user(("Engineer"))

node_user -->|"sets options"| node_config
node_user -->|"runs benchmark"| node_bench
node_config -->|"configures"| node_harness
node_harness -->|"creates matrices"| node_inputs
node_harness -->|"selects variant"| node_offline
node_harness -->|"selects variant"| node_online
node_offline -->|"pre-packs"| node_offlinepack
node_offline -->|"allocates packed data"| node_buffers
node_offline -->|"records metrics"| node_results
node_online -->|"computes with packing"| node_onlinepack
node_online -->|"tunes blocks"| node_autotune
node_online -->|"allocates packed data"| node_buffers
node_online -->|"records metrics"| node_results
node_harness -->|"uses thread settings"| node_threading
node_bench -->|"locks frequency"| node_frequency
node_bench -->|"isolates CPUs"| node_system
node_bench -.->|"invokes counters"| node_perf
node_results -->|"feeds utilization plots"| node_plots
node_results -->|"feeds stage plots"| node_stageplots

click node_config "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp"
click node_harness "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp"
click node_inputs "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp"
click node_offline "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/offline-packing/gemm-test.cpp"
click node_offlinepack "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/offline-packing/amx-gemm.cpp"
click node_online "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/gemm-test.cpp"
click node_onlinepack "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/amx-gemm.cpp"
click node_autotune "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/autotune.hpp"
click node_buffers "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/page_alloc.hpp"
click node_threading "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/thread_params.hpp"
click node_results "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp"
click node_bench "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/bench.sh"
click node_system "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/cpu-isolation.py"
click node_frequency "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/freq.sh"
click node_plots "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/tools/plot_amx_util.py"
click node_stageplots "https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/tools/plot_stage_breakdown.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_harness,node_inputs,node_threading,node_results toneBlue
class node_offline,node_offlinepack,node_online,node_onlinepack,node_autotune,node_buffers toneAmber
class node_bench,node_system,node_frequency,node_perf toneMint
class node_plots,node_stageplots toneRose
class node_user toneIndigo
```

## Components

### Benchmark runtime

- [CLI and config](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp): `src/common/bench_harness.hpp`
- [Benchmark harness](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp): `src/common/bench_harness.hpp`
- [Matrix inputs](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp): `src/common/bench_harness.hpp`
- [NUMA threading](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/thread_params.hpp): `src/common/thread_params.hpp`
- [CSV results](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/bench_harness.hpp): `src/common/bench_harness.hpp`

### GEMM variants

- [Offline variant](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/offline-packing/gemm-test.cpp): `src/offline-packing/gemm-test.cpp`
- [Offline packing](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/offline-packing/amx-gemm.cpp): `src/offline-packing/amx-gemm.cpp`
- [Online variant](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/gemm-test.cpp): `src/online-packing/gemm-test.cpp`
- [Online packing](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/amx-gemm.cpp): `src/online-packing/amx-gemm.cpp`
- [Block autotuning](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/online-packing/autotune.hpp): `src/online-packing/autotune.hpp`
- [Packed buffers](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/src/common/page_alloc.hpp): `src/common/page_alloc.hpp`

### Experiment controls

- [Benchmark orchestration](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/bench.sh): `scripts/bench.sh`
- [CPU controls](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/cpu-isolation.py): `scripts/cpu-isolation.py`
- [Frequency control](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/scripts/freq.sh): `scripts/freq.sh`
- **Perf counters**

### Results analysis

- [Plot utilities](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/tools/plot_amx_util.py): `tools/plot_amx_util.py`
- [Stage plots](https://github.com/xjn-la-la-land/amx-gemm-handwritten/blob/master/tools/plot_stage_breakdown.py): `tools/plot_stage_breakdown.py`

### Other components

- **Engineer**

## Connections

- Engineer → CLI and config: sets options
- Engineer → Benchmark orchestration: runs benchmark
- CLI and config → Benchmark harness: configures
- Benchmark harness → Matrix inputs: creates matrices
- Benchmark harness → Offline variant: selects variant
- Benchmark harness → Online variant: selects variant
- Offline variant → Offline packing: pre-packs
- Offline variant → Packed buffers: allocates packed data
- Offline variant → CSV results: records metrics
- Online variant → Online packing: computes with packing
- Online variant → Block autotuning: tunes blocks
- Online variant → Packed buffers: allocates packed data
- Online variant → CSV results: records metrics
- Benchmark harness → NUMA threading: uses thread settings
- Benchmark orchestration → Frequency control: locks frequency
- Benchmark orchestration → CPU controls: isolates CPUs
- Benchmark orchestration → Perf counters: invokes counters
- CSV results → Plot utilities: feeds utilization plots
- CSV results → Stage plots: feeds stage plots