fix(amd): repair dense Qwen GGUF swapping and anonymize deployment reports

.gitattributes

@@ -0,0 +1 @@
+*.pdf binary

.gitignore

@@ -6,6 +6,13 @@ __pycache__/
 # C extensions
 *.so
 
+# torch.utils.cpp_extension's ROCm auto-hipify writes translated copies next to the
+# CUDA sources it translates (kernel/csrc/gguf/*.cu -> *.hip, *.cuh -> *_hip.cuh);
+# regenerated on every build, never hand-edited.
+*.hip
+*_hip.cuh
+*_hip.h
+
 # Distribution / packaging
 .Python
 build/
@@ -227,3 +234,6 @@ benchmarks/cross_framework
 
 # local e2e/bench artifacts (harnesses may run with repo cwd)
 /results/
+
+# Rendered PDF review images are local QA intermediates, never release inputs.
+/tmp/

.zenodo.json

@@ -0,0 +1,22 @@
+{
+  "title": "FreeToken AMD ROCm/HIP Port for Strix Halo",
+  "description": "Technical white paper and reproducibility package for a native ROCm/HIP port of FreeToken on AMD Strix Halo. Includes gfx1151 validation, controlled benchmark methodology, and portable artifact tooling. This release candidate does not claim strict replication of the upstream NVIDIA result or general AMD superiority.",
+  "creators": [
+    {
+      "name": "FreeToken AMD contributors"
+    }
+  ],
+  "version": "0.1.0-rc1",
+  "license": "Apache-2.0",
+  "keywords": [
+    "AMD ROCm",
+    "HIP",
+    "Strix Halo",
+    "Radeon 8060S",
+    "Mixture of Experts",
+    "LLM serving",
+    "reproducibility"
+  ],
+  "upload_type": "software",
+  "access_right": "open"
+}

CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "Release candidate citation metadata. Replace the release-candidate version with the immutable release tag and DOI before publication."
+title: "FreeToken AMD ROCm/HIP Port for Strix Halo"
+authors:
+  - name: FreeToken AMD contributors
+license: Apache-2.0
+repository-code: "https://github.com/dbourdea/FreeToken"
+version: "0.1.0-rc1"
+abstract: "Native ROCm/HIP port of FreeToken with gfx1151 validation and reproducibility tooling for AMD Strix Halo."

README.md

@@ -56,6 +56,13 @@ For More details:
 - [Supported models](https://github.com/FlashML-org/FreeToken/blob/main/docs/models.md)
 - [CLI reference](https://github.com/FlashML-org/FreeToken/blob/main/docs/cli.md)
 
+### AMD ROCm/HIP port
+
+The `amd-rocm-gfx1151` branch contains the native AMD ROCm/HIP port and
+`gfx1151` validation work. Read [AMD ROCm on Radeon 8060S](docs/amd-rocm-gfx1151.md)
+for scope and platform-specific boundaries, and [Reproducibility and independent
+extension](docs/reproducibility.md) for the portable public evidence workflow.
+
 ## Citation
 
 If you use FreeToken for your research, please cite our [paper](https://arxiv.org/abs/2608.16157):

benchmarks/README.md

@@ -11,6 +11,11 @@ include the full serving path. AIME-25 prompt, checkpoint-recommended sampling.
 python benchmarks/bench_decode_moe.py --model /path/to/model --backend offload,cpu,hybrid
 ```
 
+Use `--cache N` to pin the expert-cache slot count and
+`--num-token-override N` to pin the server KV-token pool.  Supply both when
+comparing cache policies so automatic spare-VRAM allocation does not change the
+tested context capacity.
+
 **`bench_load_weight_generic.py`** — expert-bank load time: serial vs parallel O_DIRECT
 vs pre-repacked FTW, each mode in its own subprocess. Linux-only; stages the FTW under
 `/var/tmp` (`--ftw-dir` overrides; roughly checkpoint-sized).

benchmarks/bench_decode_moe.py

@@ -100,6 +100,15 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         help="hybrid: max PCIe fetches/layer; -1 = auto (benched pcie/cpu bandwidth fraction)",
     )
     p.add_argument("--mem-ratio", type=float, default=0.9, help="target VRAM utilization")
+    p.add_argument(
+        "--num-token-override",
+        type=int,
+        default=None,
+        help=(
+            "pin the server KV-token pool capacity instead of accepting its automatic "
+            "allocation; use this to compare cache policies at the same context capacity"
+        ),
+    )
     p.add_argument("--gpu", default=None,
                    help="GPU for the serve: a UUID or nvidia-smi index (as ft serve --gpu)")
     p.add_argument("--no-graph", action="store_true", help="eager decode instead of CUDA graph")
@@ -187,6 +196,13 @@ def serve_cmd(args: argparse.Namespace, backend: str, port: int) -> list[str]:
     ]
     if args.gpu:
         cmd += ["--gpu", args.gpu]
+    # An explicit token-pool size makes cache-policy comparisons fair: auto cache
+    # sizing otherwise consumes the remaining VRAM for KV pages, while a fixed
+    # expert cache leaves the server's conservative default KV allocation intact.
+    if args.num_token_override is not None:
+        # The benchmark names the value after the Engine field, while the public
+        # CLI intentionally exposes it as the concise ``--num-tokens`` flag.
+        cmd += ["--num-tokens", str(args.num_token_override)]
     if args.cache > 0:
         cmd += ["--moe-cache-size", str(args.cache)]
     elif args.cache_rate is not None:

benchmarks/bench_gguf_q4_dense_kernel.py

@@ -0,0 +1,137 @@
+"""Measure the dense native-GGUF Q4_0 vector kernels used by Gemma 4 on GMKtek EVO-X2.
+
+The Gemma 4 26B A4B Q4_0 checkpoint has four recurring dense projection
+geometries.  They are supplied as defaults here so a HIP optimization can be
+measured before it is allowed into the full OpenAI-compatible server benchmark:
+
+* 2816 by 4096 attention output projection;
+* 8192 by 2816 full-attention QKV projection;
+* 4224 by 2816 fused shared-MLP gate/up projection; and
+* 10240 by 2816 sliding-window QKV projection.
+
+Like ``bench_gguf_q4_moe_kernel.py``, this tool creates valid packed Q4_0
+weights on the accelerator and measures only post-warm-up GPU event time.  It
+does not claim an end-to-end serving rate and must be paired with the API
+benchmark before a kernel candidate is accepted.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+import torch
+
+from freetoken.kernel.gguf import ggml_mul_mat_vec_a8
+from freetoken.models.gguf.dequant import GGML_Q4_0, row_bytes
+
+
+# Output rows and input columns, recovered from the exact GMKtek EVO-X2 Gemma GGUF.
+DEFAULT_SHAPES = ((2816, 4096), (8192, 2816), (4224, 2816), (10240, 2816))
+
+
+def _parse_shape(value: str) -> tuple[int, int]:
+    """Parse a ``ROWSxCOLS`` override and validate its Q4_0 block alignment."""
+    try:
+        rows_text, cols_text = value.lower().split("x", 1)
+        rows, cols = int(rows_text), int(cols_text)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("shape must be ROWSxCOLS, for example 2816x4096") from error
+    if rows <= 0 or cols <= 0 or cols % 32:
+        raise argparse.ArgumentTypeError("rows must be positive and cols must be a positive multiple of 32")
+    return rows, cols
+
+
+def _parse_args() -> argparse.Namespace:
+    """Parse reproducible dense-kernel benchmark controls."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--shape",
+        action="append",
+        type=_parse_shape,
+        help="repeatable ROWSxCOLS override; defaults to all production shapes",
+    )
+    parser.add_argument("--vectors", type=int, default=1, help="input rows per kernel call")
+    parser.add_argument("--warmup", type=int, default=20)
+    parser.add_argument("--repetitions", type=int, default=200)
+    parser.add_argument("--seed", type=int, default=20260828)
+    parser.add_argument("--json", type=Path, help="write one JSON artifact")
+    return parser.parse_args()
+
+
+def _make_q4_weight(rows: int, cols: int, device: torch.device) -> torch.Tensor:
+    """Create finite, contiguous ``[rows, row_bytes(cols)]`` Q4_0 packed weights."""
+    blocks = cols // 32
+    weight = torch.randint(0, 256, (rows, blocks, 18), dtype=torch.uint8, device=device)
+    # Q4_0 starts each 18-byte block with an FP16 scale.  Use 1/32 rather than
+    # arbitrary random bytes so the measured real kernel cannot create NaNs.
+    scale_bytes = torch.tensor([1.0 / 32.0], dtype=torch.float16, device=device).view(torch.uint8)
+    weight[..., :2] = scale_bytes.reshape(1, 1, 2)
+    return weight.reshape(rows, row_bytes(cols, GGML_Q4_0)).contiguous()
+
+
+def _average_event_us(kernel, repetitions: int, device: torch.device) -> float:
+    """Measure an already-warmed kernel with GPU events and return microseconds/call."""
+    start, end = torch.cuda.Event(enable_timing=True), torch.cuda.Event(enable_timing=True)
+    torch.cuda.synchronize(device)
+    start.record()
+    for _ in range(repetitions):
+        kernel()
+    end.record()
+    end.synchronize()
+    return start.elapsed_time(end) * 1000.0 / repetitions
+
+
+def main() -> int:
+    """Run the selected dense projection shapes and write a durable JSON result."""
+    args = _parse_args()
+    if args.vectors <= 0 or args.warmup <= 0 or args.repetitions <= 0:
+        raise ValueError("--vectors, --warmup, and --repetitions must be positive")
+    if not torch.cuda.is_available():
+        raise RuntimeError("this benchmark requires a CUDA or HIP PyTorch device")
+    torch.manual_seed(args.seed)
+    device = torch.device("cuda")
+    shapes = args.shape or DEFAULT_SHAPES
+    measurements = []
+
+    for rows, cols in shapes:
+        weight = _make_q4_weight(rows, cols, device)
+        x = torch.randn(args.vectors, cols, dtype=torch.bfloat16, device=device)
+
+        def call() -> torch.Tensor:
+            return ggml_mul_mat_vec_a8(weight, x, int(GGML_Q4_0), rows)
+
+        for _ in range(args.warmup):
+            result = call()
+        torch.cuda.synchronize(device)
+        if not torch.isfinite(result).all():
+            raise RuntimeError(f"non-finite result for dense Q4_0 shape {rows}x{cols}")
+        measurements.append(
+            {
+                "rows": rows,
+                "cols": cols,
+                "vectors": args.vectors,
+                "output_shape": list(result.shape),
+                "average_us": _average_event_us(call, args.repetitions, device),
+            }
+        )
+
+    output = {
+        "device": torch.cuda.get_device_name(device),
+        "hip": torch.version.hip,
+        "torch": torch.__version__,
+        "quant_type": "Q4_0",
+        "warmup": args.warmup,
+        "repetitions": args.repetitions,
+        "measurements": measurements,
+    }
+    print(json.dumps(output, indent=2, sort_keys=True))
+    if args.json is not None:
+        args.json.parent.mkdir(parents=True, exist_ok=True)
+        args.json.write_text(json.dumps(output, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())