Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++

AMD packages carry the hipBLASLt tuning tables; the engine start picks the one for the card

Niko1221c6aa4223d90c
diff --git a/docs/AMD_HIP.md b/docs/AMD_HIP.md
index cf9e27ba4..a48e78b99 100644
--- a/docs/AMD_HIP.md
+++ b/docs/AMD_HIP.md
@@ -97,9 +97,18 @@ What was run on real hardware:
- **Run by other people:** an RX 7900 XTX on Windows 11 ran the earlier ready-made Windows engine (0.1.40; [report #1173](../bench/results/2026-10-06-community-rx-7900-xtx/README.md));
RX 7900 XTX, XT and GRE owners ran Linux builds ([COMMUNITY.md](../bench/results/COMMUNITY.md)); Strix Halo owners ran Linux builds made from source
(ROCm 7.14 line). Nobody has reported a Strix Halo on Windows, or the packaged `halo` and `rdna3` engines.
-- **Tuning tables:** the packaged AMD engines do not carry the hipBLASLt tuning tables of `tools/hip` yet (they are planned for 0.2.1), so
- the prompt's dense matrix products use plain hipBLAS. Prompt reading is slower than the numbers measured with a table, for example the
- gfx1151 numbers in [STRIX_HALO.md](STRIX_HALO.md); answers are the same. A source build with the table is unchanged (see [Tuning table](#tuning-table)).
+- **Tuning tables (0.2.1):** each AMD package carries the hipBLASLt tuning tables of `tools/hip` that match the hipBLASLt it bundles, as
+ `tuning/<arch>-hipblaslt-<version>.txt` (listed and hashed in the package manifest), and records that version as `hipblaslt_version` in its
+ BUILD.json. Windows `rx9070` has the gfx1201 table, Windows `rdna3` the gfx1100 and gfx1151 ones (all hipBLASLt 1.5.0), Linux `rx7900` the
+ gfx1100 one (1.2.0), Linux `halo` the gfx1151 one (1.4.1). Linux `rx9070` has none: its wheels carry hipBLASLt 1.2.0 and no table in `tools/hip`
+ is for that version (a table calibrated for it on an R9700 read prompts about 1% faster and decode 2% slower, so none is shipped).
+ The engine start picks the table for the card and uses it only when the package's hipBLASLt version is the table's; otherwise it logs
+ why and the dense matrix products stay on plain hipBLAS. **A table changes which GEMM algorithm runs the prompt, so the rounding differs: the
+ answers are not bit-identical to plain hipBLAS** (first-token KL 0.016 on an R9700, see below). Packaged engines therefore do not use the table
+ unless you ask: `STRATA_HIPBLASLT_TABLE=on` (or `"hipblaslt_table": true` in the run config) uses it, `off` never does, and the start log
+ says which table was taken or why none was (`hipBLASLt tuning table: ...`). A `STRATA_HIPBLASLT_TUNING` you set yourself is always kept.
+ A source build is unchanged (see [Tuning table](#tuning-table)). Testers on Strix Halo and RX 7000 cards: please send that log line and a
+ prompt-speed run with `on` and `off`.
Please report a run on an RX 7000 card or a Strix Halo (card, driver, OS, the end of `strata-<model>.log`).
@@ -801,7 +810,17 @@ CASES=$(awk 'NR>2 {printf " --case %s,%s,%s,%s,%s", $1, $5, $2, $3, $4}' tools/h
The file's second line names the architecture and version (`STRATA_HIPBLASLT_TUNING_V1 gfx1201 100401`); save it
as `tools/hip/<arch>-hipblaslt-<version>.txt` for setup, or point `STRATA_HIPBLASLT_TUNING` at it. Compare the
-prompt speed with and without it before keeping it.
+prompt speed with and without it before keeping it. For an engine package, `packaging/stage_tuning.py` (Linux builds) and
+`tools/hip/package_windows.py` copy the tables that match the bundled hipBLASLt into the package's `tuning/` folder.
+
+**Measured for 0.2.1 on a Radeon AI PRO R9700 (gfx1201), the Linux `rx9070` package 0.1.45.3, Q2_0, hipBLASLt 1.2.0, one card, the
+box to itself.** A 1.2.0 table (32 rows, `tune_hipblaslt` over the gfx1201 100500 table's cases) against plain hipBLAS, 6 interleaved pairs
+with a fresh engine per run and a second plain arm as the noise arm: prompt 4K 2,302 vs 2,119 tok/s and 20K 2,671 vs 2,507 (5 and 6 of 6 pairs
+faster, but a plain run alone lands on either of two speeds, 1,970 or 2,290 at 4K, so the medians mix modes; inside one mode the table is
++0.5% at 4K and +1% at 20K), decode 91.2 vs 93.2 tok/s (-2.1%, 0 of 6 pairs faster). Not bit-identical: the final residual of a 4K and a
+20K prompt differs, a 48-token greedy answer after the 20K prompt differs, and the first-token KL against plain is 0.0157 mean, 0.0716 max over
+24 prompts of 1.5K-24K tokens (plain against plain: 0 and 0.00004; top-1 token the same 24 of 24; 24-token answers equal 1 of 6). That is why
+no gfx1201 table is shipped for hipBLASLt 1.2.0 and why packaged engines use a table only when asked.
Shipped tables:
diff --git a/packaging/ENGINE-COMPONENT.md b/packaging/ENGINE-COMPONENT.md
index 68c08dfa8..100811927 100644
--- a/packaging/ENGINE-COMPONENT.md
+++ b/packaging/ENGINE-COMPONENT.md
@@ -109,6 +109,17 @@ the manifest file (which holds every file's hash), used as the package's digest
GPU architecture) into the folder `package_engine.py` packages; libraries the distribution provides are listed in
`SYSTEM-LIBS.txt` inside the package so a missing one can be named on a target PC.
+## hipBLASLt tuning tables in an AMD package
+
+An AMD package records the hipBLASLt it bundles (`hipblaslt_version` in BUILD.json, 1.5.0 is `100500`) and carries the tables of `tools/hip`
+for exactly that version and its `archs` as `tuning/<arch>-hipblaslt-<version>.txt`. They are ordinary files of the manifest (hashed and signed
+with the package). `packaging/stage_tuning.py` does it for the Linux build script, `tools/hip/package_windows.py` for the Windows zip, and
+`package_engine.py` refuses an AMD stage without `hipblaslt_version` or with a table for another version or architecture. The server's start
+(`serve/server.py with_component_engine`, rule in `strata_control/hipblaslt_tuning.py`) picks the table of the card and sets
+`STRATA_HIPBLASLT_TUNING` for the engine; a version mismatch, an unreadable card or a missing version are one log line and plain hipBLAS.
+`STRATA_HIPBLASLT_TABLE=on|off` (or `"hipblaslt_table"` in the run config) overrides; unset it follows `AUTO_USES_TABLE`, which is off until the
+owner decides, because a table changes the rounding of the prompt's GEMMs (docs/AMD_HIP.md, Tuning table). Tests: `tests/terminal/test_hipblaslt_tuning.py`.
+
## Picture readers in an AMD package
A HIP package carries two programs for pictures next to `strata` (`vision` in its BUILD.json): `strata-vision` is the CPU reader, which
diff --git a/packaging/build_hip_gfx1103.sh b/packaging/build_hip_gfx1103.sh
index 4e85546bc..6ec73727a 100644
--- a/packaging/build_hip_gfx1103.sh
+++ b/packaging/build_hip_gfx1103.sh
@@ -31,6 +31,8 @@ python3 packaging/collect_libs.py --binary b1103/strata --search $SDK/lib --sear
--also 'libamd_comgr.so*' --also 'libhiprtc*.so*' --out $STAGE \
--data $SDK/lib/rocblas/library=rocblas/library --data $SDK/lib/hipblaslt/library=hipblaslt/library --data-arch gfx1103 > $R/collect.log 2>&1
st "collected rc=$?"
+python3 packaging/stage_tuning.py --stage $STAGE --archs gfx1103 --rocm $SDK >> $R/stage_tuning.log 2>&1 # hipblaslt_version in BUILD.json + the matching tuning table
+st "tuning tables rc=$?: $(tail -n 1 $R/stage_tuning.log)"
mkdir -p $R/components/engine
python3 packaging/package_engine.py --src $STAGE --backend hip --version 0.1.45 --out $R/components/engine \
--arch gfx1103 --build-id 322e3fdfb+rocm7.14.1-gfx110X --tree > $R/package.log 2>&1
diff --git a/packaging/build_hip_linux.sh b/packaging/build_hip_linux.sh
index 1173ea978..184039595 100644
--- a/packaging/build_hip_linux.sh
+++ b/packaging/build_hip_linux.sh
@@ -86,6 +86,9 @@ for f in "$STAGE"/*.so "$STAGE"/*.so.*; do [ -f "$f" ] && [ ! -L "$f" ] && patch
for f in "$STAGE/strata" "$STAGE/strata-vision" "$STAGE/strata-vision-hip"; do
st "RUNPATH $(basename "$f"): $(readelf -d "$f" | grep -E 'RPATH|RUNPATH' | cut -d'[' -f2 | tr -d ']' | paste -sd' ')"
done
+# the hipBLASLt version of this ROCm into BUILD.json, and the tuning tables of tools/hip that match it (architecture and version) into tuning/
+python3 packaging/stage_tuning.py --stage "$STAGE" --archs "$ARCHLIST" --rocm "$HP" >> "$OUT/stage_tuning.log" 2>&1
+st "tuning tables rc=$?: $(tail -n 1 "$OUT/stage_tuning.log")"
[ -n "${NO_PACKAGE:-}" ] && { st "STAGE-DONE"; exit 0; }
rm -rf "$OUT/components"; mkdir -p "$OUT/components/engine"
ARCHARGS=""; for a in $ARCHLIST; do ARCHARGS="$ARCHARGS --arch $a"; done
diff --git a/packaging/package_engine.py b/packaging/package_engine.py
index 319f3cab8..2c7c570a9 100644
--- a/packaging/package_engine.py
+++ b/packaging/package_engine.py
@@ -80,6 +80,9 @@ def select(src: Path, entrypoint: str, *, tree: bool, include: list[str]) -> lis
top_level = "/" not in rel
if tree or (top_level and wanted(path)) or any(fnmatch.fnmatch(rel, pattern) for pattern in include):
chosen.add(rel)
+ for path in sorted((src / "tuning").glob("*.txt")) if (src / "tuning").is_dir() else []:
+ if path.is_file() and not path.is_symlink(): # the hipBLASLt tuning tables of an AMD package (strata_control/hipblaslt_tuning.py)
+ chosen.add(path.relative_to(src).as_posix())
chosen.discard(entrypoint)
return [entrypoint] + sorted(chosen)
@@ -92,6 +95,11 @@ def build(src: Path, backend: str, version: str, target: str, out: Path, *, entr
raise SystemExit(f"unknown backend {backend!r}")
if backend != "cpu" and not archs:
raise SystemExit(f"a {backend} package needs at least one --arch (sm_86, gfx1201, ...)")
+ if backend == "hip":
+ from strata_control import hipblaslt_tuning
+ problems = hipblaslt_tuning.check_stage(src, archs)
+ if problems:
+ raise SystemExit("refusing to package the AMD engine:\n " + "\n ".join(problems))
entrypoint = entry or ("strata.exe" if target.startswith("windows") else "strata")
if not (src / entrypoint).is_file():
raise SystemExit(f"{src / entrypoint} does not exist")
diff --git a/packaging/stage_tuning.py b/packaging/stage_tuning.py
new file mode 100644
index 000000000..b1e3e305c
--- /dev/null
+++ b/packaging/stage_tuning.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Put the hipBLASLt tuning tables into a staged AMD engine package and record the hipBLASLt version in its BUILD.json.
+
+ python packaging/stage_tuning.py --stage <stage folder> --archs "gfx1200 gfx1201" --rocm <ROCm devel root> [--tables tools/hip]
+ [--expect gfx1201]
+
+The stage folder is the one packaging/package_engine.py is pointed at. The hipBLASLt version is read from the ROCm tree the package's
+libraries come from (include/hipblaslt/hipblaslt-version.h; 1.5.0 is 100500), written to BUILD.json as ``hipblaslt_version``, and every
+table of tools/hip for one of --archs and exactly that version is copied to ``<stage>/tuning/``. An architecture without a table keeps plain
+hipBLAS: it is listed on stdout, and --expect makes it an error for the ones that must have one. The tables are measured per architecture and
+version (docs/AMD_HIP.md, Tuning table); nothing is calibrated or invented here. Windows packages do the same inside tools/hip/package_windows.py.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from strata_control import hipblaslt_tuning as ht # noqa: E402
+
+
+def stage(stage_dir: Path, archs: list[str], version: int | None, tables: Path, expect: list[str]) -> list[str]:
+ if version is None:
+ raise SystemExit("cannot read the hipBLASLt version of this ROCm tree (include/hipblaslt/hipblaslt-version.h): "
+ "an AMD package must record hipblaslt_version")
+ info = stage_dir / "BUILD.json"
+ meta = json.loads(info.read_text(encoding="utf-8-sig")) if info.is_file() else {}
+ meta["hipblaslt_version"] = version
+ info.write_text(json.dumps(meta, indent=1) + "\n", encoding="utf-8")
+ copied = ht.stage_tables(stage_dir, archs, version, tables)
+ left = ht.missing_report(archs, version, tables)
+ for arch, have in left.items():
+ print(f"no hipBLASLt table for {arch} with hipBLASLt {version} (the repo has: {', '.join(map(str, have)) or 'none'}): plain hipBLAS there")
+ bad = [a for a in expect if a in left]
+ if bad:
+ raise SystemExit(f"required tables are missing for {', '.join(bad)} at hipBLASLt {version}")
+ return copied
+
+
+def main(argv=None) -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--stage", required=True, type=Path)
+ ap.add_argument("--archs", required=True, help="space, comma or semicolon separated")
+ ap.add_argument("--rocm", type=Path, help="the ROCm devel root (its include/hipblaslt/hipblaslt-version.h)")
+ ap.add_argument("--version", type=int, help="the hipBLASLt version number (100500), instead of --rocm")
+ ap.add_argument("--tables", type=Path, default=ROOT / "tools" / "hip")
+ ap.add_argument("--expect", default="", help="architectures that must have a table (an error when one is missing)")
+ a = ap.parse_args(argv)
+ archs = [x for x in re.split(r"[;, ]+", a.archs) if x]
+ version = a.version if a.version else ht.version_from_header(a.rocm) if a.rocm else None
+ copied = stage(a.stage, archs, version, a.tables, [x for x in re.split(r"[;, ]+", a.expect) if x])
+ print(f"hipBLASLt {version}: " + (", ".join(copied) if copied else "no tuning tables in this package"))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/serve/server.py b/serve/server.py
index fb496abdf..94a488c66 100644
--- a/serve/server.py
+++ b/serve/server.py
@@ -66,6 +66,7 @@ from serve.frontend import (THINK_END, ChatTemplate, Event, OutputParser, anthro
from serve.mcp import McpCancelled, hub_from_config # noqa: E402
from serve import runconfig # noqa: E402
from strata_control import engine_component # noqa: E402
+from strata_control import hipblaslt_tuning # noqa: E402
from strata_control import vision_reader # noqa: E402
from strata_control import draft_layer # noqa: E402
from serve import ready as ready_file # noqa: E402
@@ -7502,6 +7503,8 @@ def with_component_engine(cfg: dict) -> dict:
cfg = dict(cfg)
cfg["exe"] = _component_exe(cfg["exe"], cfg)
cfg["lib_dirs"] = [*engine_component.package_lib_dirs(Path(cfg["exe"]).parent), *(cfg.get("lib_dirs") or [])]
+ if cfg.get("backend") == "hip": # AMD: the package's own hipBLASLt tuning table for this card, when its hipBLASLt version matches
+ cfg = hipblaslt_tuning.apply(cfg, Path(cfg["exe"]).parent, say=lambda line: print(line, flush=True))
return cfg
diff --git a/setup.py b/setup.py
index c7a2d32aa..9e11b5491 100644
--- a/setup.py
+++ b/setup.py
@@ -3834,15 +3834,20 @@ def hipblaslt_version(lib_dirs):
return None
-def hipblaslt_table(arch, lib_dirs, ver=None):
- """tools/hip/<arch>-hipblaslt-<version>.txt for this card AND the installed hipBLASLt, else None: its solution
+def hipblaslt_table(arch, lib_dirs, ver=None, extra_dirs=()):
+ """<arch>-hipblaslt-<version>.txt for this card AND the installed hipBLASLt, else None: its solution
ids are valid only for that pair (the engine refuses any other table and uses plain hipBLAS). ver: the
- hipBLASLt version the ready-made Windows engine ships (its BUILD.json), else read from the installed headers."""
+ hipBLASLt version the ready-made engine ships (its BUILD.json), else read from the installed headers. extra_dirs: the
+ engine folder's own tuning/ first (a ready-made engine carries its tables), then tools/hip of this checkout.
+ STRATA_HIPBLASLT_TABLE=off: none (strata_control/hipblaslt_tuning.py)."""
+ from strata_control import hipblaslt_tuning as HT
+ if HT.switched_off():
+ say(f" hipBLASLt tuning table: off ({HT.SWITCH}=off); the prompt's dense matrix products use plain hipBLAS")
+ return None
ver = ver or hipblaslt_version(lib_dirs)
- table = ROOT / "tools" / "hip" / f"{arch}-hipblaslt-{ver}.txt"
- if ver is not None and table.exists():
- head = table.read_text(encoding="utf-8").split("\n", 2)[:2]
- if f"STRATA_HIPBLASLT_TUNING_V1 {arch} {ver}" in (h.strip() for h in head):
+ for folder in (*extra_dirs, ROOT / "tools" / "hip"):
+ table = Path(folder) / HT.table_name(arch, ver or 0)
+ if ver is not None and table.exists() and HT.header_ok(table, arch, ver):
ok(f"hipBLASLt tuning table: {table.name} (faster prompts)")
return table
have = sorted(p.name for p in (ROOT / "tools" / "hip").glob(f"{arch}-hipblaslt-*.txt"))
@@ -8210,9 +8215,12 @@ def main() -> int:
# the dense prompt GEMMs through hipBLASLt with kernels measured on this GPU generation (tools/hip; +40-60%
# prompt speed on the 7900 XTX): only a table for this card's arch AND the installed hipBLASLt version (the
# engine refuses any other one and falls back to plain hipBLAS)
- table = hipblaslt_table(gpu["arch"], lib_dirs, meta.get("hipblaslt_version"))
- if table:
- cfg["env"] = {"STRATA_HIPBLASLT_TUNING": str(table)}
+ if CONTROL:
+ pass # the app's engine is a package: the server picks its tuning/ table for the card when it starts (strata_control/hipblaslt_tuning.py)
+ else:
+ table = hipblaslt_table(gpu["arch"], lib_dirs, meta.get("hipblaslt_version"), [eng / "tuning"])
+ if table:
+ cfg["env"] = {"STRATA_HIPBLASLT_TUNING": str(table)}
if GFX1103_OPT_IN and gfx_arch_is(gpu["arch"], "gfx1103") and not WIN:
# the 780M's KFD queues are evicted (a GPU reset) while transparent huge pages move the pinned expert arena
cfg.setdefault("env", {})["STRATA_NO_ARENA_THP"] = "1"
diff --git a/strata_control/hipblaslt_tuning.py b/strata_control/hipblaslt_tuning.py
new file mode 100644
index 000000000..e185e390d
--- /dev/null
+++ b/strata_control/hipblaslt_tuning.py
@@ -0,0 +1,250 @@
+"""The hipBLASLt tuning tables that ship inside the AMD engine packages, and the one rule that decides whether a start uses one.
+
+A table (tools/hip/<arch>-hipblaslt-<version>.txt) lists, per dense GEMM shape of the prompt path, the hipBLASLt solution that was
+fastest on that GPU architecture. Its solution ids are valid for one architecture and one hipBLASLt version only; the engine checks both
+(src/prefill/gemm.cu) and falls back to plain hipBLAS for anything else, so a wrong table can never change a result, it only wastes the
+speed-up. The table picks a GEMM algorithm: it does not change what the model is asked to compute.
+
+Package side (packaging/stage_tuning.py, tools/hip/package_windows.py): ``tuning/<arch>-hipblaslt-<version>.txt`` inside the engine package,
+one per architecture of the package that has a table for the hipBLASLt version the package bundles, and ``hipblaslt_version`` in its BUILD.json.
+The files are listed (and hashed, and signed) in engine-component.json like every other file of the package.
+
+Start side (serve/server.py with_component_engine, setup.py in the app): ``resolve`` reads the package, the GPUs in this PC and the switch,
+and returns the table to use or the reason there is none. Nobody sets STRATA_HIPBLASLT_TUNING by hand:
+
+* ``STRATA_HIPBLASLT_TABLE`` (or ``"hipblaslt_table"`` in the run config): ``off`` / false never uses the packaged table, ``on`` / true
+ uses it when it matches, ``auto`` (unset) follows ``AUTO_USES_TABLE`` below;
+* a ``STRATA_HIPBLASLT_TUNING`` the person set themselves (environment or run config) always wins and is not touched;
+* a table for another hipBLASLt version than the package bundles is not used, and the log says which versions it has.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+SWITCH = "STRATA_HIPBLASLT_TABLE" # on | auto | off
+#: What "auto" (the switch unset) does. A table changes which hipBLASLt solution runs the prompt's dense GEMMs, so their floating-point sums
+#: round differently: on an R9700 (gfx1201, Q2_0) the answers with a table are NOT bit-identical to plain hipBLAS, see phaseA-tests/notes-021-hip.md.
+#: A default that changes bits needs the owner's decision, so the packages carry their tables and the switch ("on") uses them, but "auto" is
+#: off until that decision. Flipping this one constant turns the tables on for every package that carries one.
+AUTO_USES_TABLE = False
+ENGINE_VAR = "STRATA_HIPBLASLT_TUNING" # what the engine reads: the path of one table
+TABLE_DIR = "tuning" # inside an engine package
+HEADER = "STRATA_HIPBLASLT_TUNING_V1"
+OFF_WORDS = ("off", "0", "no", "false", "none", "disable", "disabled")
+ON_WORDS = ("on", "1", "yes", "true", "force", "enable", "enabled")
+_NAME = re.compile(r"^(gfx[0-9a-f]+)-hipblaslt-(\d+)\.txt$")
+
+
+def table_name(arch: str, version: int) -> str:
+ return f"{arch}-hipblaslt-{version}.txt"
+
+
+def version_number(major: int, minor: int, patch: int) -> int:
+ """hipblasLtGetVersion's number: 1.5.0 -> 100500, 1.2.2 -> 100202."""
+ return major * 100000 + minor * 100 + patch
+
+
+def version_from_header(rocm_root) -> int | None:
+ """The hipBLASLt version of a ROCm tree, from include/hipblaslt/hipblaslt-version.h (what a package build has at hand); None when absent."""
+ try:
+ text = (Path(rocm_root) / "include" / "hipblaslt" / "hipblaslt-version.h").read_text(encoding="utf-8")
+ parts = [int(re.search(rf"#define\s+HIPBLASLT_VERSION_{k}\s+(\d+)", text).group(1)) for k in ("MAJOR", "MINOR", "PATCH")]
+ except (OSError, AttributeError, ValueError):
+ return None
+ return version_number(*parts)
+
+
+def header_ok(path: Path, arch: str, version: int) -> bool:
+ """The file's own second line must name the same architecture and version as its file name (the engine checks it again)."""
+ try:
+ with open(path, encoding="utf-8") as f:
+ head = [f.readline().strip(), f.readline().strip()]
+ except OSError:
+ return False
+ return f"{HEADER} {arch} {version}" in head
+
+
+def tables_in(folder) -> dict[tuple[str, int], Path]:
+ """{(arch, version): path} for every table file in a folder."""
+ found = {}
+ try:
+ entries = sorted(Path(folder).iterdir())
+ except OSError:
+ return found
+ for path in entries:
+ m = _NAME.match(path.name)
+ if m and path.is_file():
+ found[(m.group(1), int(m.group(2)))] = path
+ return found
+
+
+# ------------------------------------------------------------------------------------------------- package side
+
+def stage_tables(stage, archs, version: int | None, source) -> list[str]:
+ """Copy the tables for ``archs`` and hipBLASLt ``version`` from the repo folder ``source`` (tools/hip) into ``stage/tuning/``.
+ Returns the file names copied. An architecture without a table for that version is left out (plain hipBLAS stays for it); a
+ table whose header disagrees with its name is an error, because the engine would refuse it on every start."""
+ import shutil
+ stage, copied = Path(stage), []
+ if version is None:
+ return copied
+ have = tables_in(source)
+ for arch in archs:
+ path = have.get((arch, version))
+ if path is None:
+ continue
+ if not header_ok(path, arch, version):
+ raise SystemExit(f"{path}: the second line does not say '{HEADER} {arch} {version}'")
+ (stage / TABLE_DIR).mkdir(parents=True, exist_ok=True)
+ shutil.copy2(path, stage / TABLE_DIR / path.name)
+ copied.append(path.name)
+ return copied
+
+
+def missing_report(archs, version: int | None, source) -> dict[str, list[int]]:
+ """For each architecture without a table for ``version``: the versions the repo does have for it (so a build can say it)."""
+ have = tables_in(source)
+ return {a: sorted(v for (arch, v) in have if arch == a) for a in archs if version is None or (a, version) not in have}
+
+
+def check_stage(stage, archs) -> list[str]:
+ """What is wrong with the tuning of a staged HIP package (empty list: fine): BUILD.json must say which hipBLASLt it carries, and every
+ table in tuning/ must be named <arch>-hipblaslt-<that version>.txt for an architecture of the package with a header that says the same."""
+ stage, problems = Path(stage), []
+ version = package_version(stage)
+ if version is None:
+ problems.append("BUILD.json has no hipblaslt_version (packaging/stage_tuning.py writes it): a start could not match a tuning table to this hipBLASLt")
+ folder = stage / TABLE_DIR
+ if folder.is_dir():
+ for path in sorted(folder.iterdir()):
+ m = _NAME.match(path.name)
+ if not m:
+ problems.append(f"tuning/{path.name} is not named <arch>-hipblaslt-<version>.txt")
+ elif m.group(1) not in archs:
+ problems.append(f"tuning/{path.name} is for {m.group(1)}, which this package has no code for")
+ elif version is not None and int(m.group(2)) != version:
+ problems.append(f"tuning/{path.name} is for hipBLASLt {m.group(2)}, this package carries {version}")
+ elif not header_ok(path, m.group(1), int(m.group(2))):
+ problems.append(f"tuning/{path.name}: the header line does not say '{HEADER} {m.group(1)} {m.group(2)}'")
+ return problems
+
+
+# ------------------------------------------------------------------------------------------------- start side
+
+@dataclass
+class Decision:
+ path: Path | None # the table to hand the engine, or None
+ message: str # one plain line for the log ("" when there is nothing to say)
+ level: str = "info" # info | warn
+
+
+def mode(environ=None, cfg: dict | None = None) -> str:
+ """"on", "off" or "auto": the environment switch first, then the run config's "hipblaslt_table" (true / false)."""
+ environ = os.environ if environ is None else environ
+ word = str(environ.get(SWITCH, "")).strip().lower()
+ if word in OFF_WORDS:
+ return "off"
+ if word in ON_WORDS:
+ return "on"
+ if word in ("", "auto"):
+ value = (cfg or {}).get("hipblaslt_table")
+ return "off" if value is False else "on" if value is True else "auto"
+ return "auto"
+
+
+def switched_off(environ=None, cfg: dict | None = None) -> bool:
+ return mode(environ, cfg) == "off"
+
+
+def package_version(folder) -> int | None:
+ """hipblaslt_version in the package's BUILD.json (an int, 100500), else None."""
+ try:
+ value = json.loads((Path(folder) / "BUILD.json").read_text(encoding="utf-8-sig")).get("hipblaslt_version")
+ except (OSError, ValueError, AttributeError):
+ return None
+ return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def user_choice(environ=None, cfg: dict | None = None) -> str | None:
+ """A STRATA_HIPBLASLT_TUNING the person set (environment first, then the run config's env): theirs to keep, even if the file is gone."""
+ environ = os.environ if environ is None else environ
+ for source in (environ, (cfg or {}).get("env") or {}):
+ value = source.get(ENGINE_VAR)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return None
+
+
+def resolve(folder, archs_present, *, environ=None, cfg: dict | None = None) -> Decision:
+ """The table for an installed AMD engine package ``folder`` on a PC whose GPUs are ``archs_present`` (in the order the engine sees them).
+ Never raises; an empty message means there is nothing worth a line (not an AMD package, or the person chose already)."""
+ folder = Path(folder)
+ if switched_off(environ, cfg):
+ return Decision(None, f"hipBLASLt tuning table: off ({SWITCH}=off); the prompt's dense matrix products use plain hipBLAS")
+ chosen = user_choice(environ, cfg)
+ if chosen:
+ return Decision(None, f"hipBLASLt tuning table: {chosen} (set by you; the engine checks it against this GPU and hipBLASLt)")
+ tuning = folder / TABLE_DIR
+ if not tuning.is_dir():
+ return Decision(None, "") # a package without tables (CUDA, Metal, an older HIP package): nothing to say
+ version = package_version(folder)
+ archs = [a for a in archs_present if isinstance(a, str)]
+ if version is None:
+ return Decision(None, "hipBLASLt tuning table: not used, this engine package does not say which hipBLASLt it carries "
+ "(BUILD.json hipblaslt_version); the prompt's dense matrix products use plain hipBLAS", "warn")
+ if not archs:
+ return Decision(None, "hipBLASLt tuning table: not used, this PC's AMD GPU architecture could not be read; plain hipBLAS", "warn")
+ tables = tables_in(tuning)
+ for arch in dict.fromkeys(archs):
+ path = tables.get((arch, version))
+ if path is None:
+ continue
+ if not header_ok(path, arch, version):
+ return Decision(None, f"hipBLASLt tuning table: {path.name} is not used, its header does not match its name; plain hipBLAS", "warn")
+ if mode(environ, cfg) == "auto" and not AUTO_USES_TABLE:
+ return Decision(None, f"hipBLASLt tuning table: {path.name} is in this package and not used by default (faster prompts, but answers can differ "
+ f"in the last digits); {SWITCH}=on uses it")
+ return Decision(path, f"hipBLASLt tuning table: {path.name} (faster prompts; {SWITCH}=off turns it off)")
+ other = sorted({v for (a, v) in tables if a in archs})
+ if other:
+ return Decision(None, f"hipBLASLt tuning table: not used, this engine carries hipBLASLt {version} and the tables for {', '.join(dict.fromkeys(archs))} "
+ f"are for {', '.join(str(v) for v in other)} (solution ids are valid for one version only); plain hipBLAS", "warn")
+ return Decision(None, f"hipBLASLt tuning table: none for {', '.join(dict.fromkeys(archs))} with hipBLASLt {version}; plain hipBLAS")
+
+
+def apply(cfg: dict, folder, archs_present=None, *, environ=None, say=print) -> dict:
+ """``cfg`` for a start from engine package ``folder``: a copy with ``env[STRATA_HIPBLASLT_TUNING]`` set when a table applies. One log line
+ through ``say`` for an AMD package (nothing for other backends)."""
+ if cfg.get("backend") not in (None, "hip"):
+ return cfg
+ folder = Path(folder)
+ if not (folder / TABLE_DIR).is_dir() and package_version(folder) is None:
+ return cfg # not a package with tables or a hipBLASLt version: nothing to decide
+ if archs_present is None:
+ archs_present = present_archs(cfg)
+ decision = resolve(folder, archs_present, environ=environ, cfg=cfg)
+ if decision.message:
+ say(("[strata] " if decision.level == "info" else "[strata] note: ") + decision.message)
+ if decision.path is None:
+ return cfg
+ out = dict(cfg)
+ out["env"] = {**(cfg.get("env") or {}), ENGINE_VAR: str(decision.path)}
+ return out
+
+
+def present_archs(cfg: dict | None = None) -> list[str]:
+ """The AMD architectures of the GPUs the engine will use, as ``strata_control.engine_component.hip_archs_present`` lists them; the run
+ config's "gpu" picks one card of several when the list is per card (Linux)."""
+ try:
+ from strata_control import engine_component as ec
+ archs = ec.hip_archs_present()
+ except Exception:
+ return []
+ gpu = (cfg or {}).get("gpu")
+ picked = gpu if isinstance(gpu, list) else [gpu] if isinstance(gpu, int) and not isinstance(gpu, bool) else []
+ chosen = [archs[i] for i in picked if 0 <= i < len(archs)] if os.name != "nt" else []
+ return chosen or archs
diff --git a/tests/terminal/test_hipblaslt_tuning.py b/tests/terminal/test_hipblaslt_tuning.py
new file mode 100644
index 000000000..9beaadd4a
--- /dev/null
+++ b/tests/terminal/test_hipblaslt_tuning.py
@@ -0,0 +1,363 @@
+"""The hipBLASLt tuning tables in the AMD engine packages: what a package holds per card family, and the one rule that decides at a start
+whether a table is used (strata_control/hipblaslt_tuning.py). Folders are throwaways; no GPU tool is run.
+
+The packages' hipBLASLt versions below are the ones the 0.2.x release packages bundle (docs/AMD_HIP.md, Ready-made packages): Windows ROCm
+10.2.0a20260930 carries 1.5.0 (100500), the Linux 7.10.0a20251120 wheels 1.2.0 (100200), Linux Strix Halo's 7.14.1 1.4.1 (100401)."""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from strata_control import hipblaslt_tuning as ht
+
+ROOT = Path(__file__).resolve().parents[2]
+TABLES = ROOT / "tools" / "hip"
+sys.path.insert(0, str(ROOT / "packaging"))
+import package_engine # noqa: E402
+import stage_tuning # noqa: E402
+
+#: (platform, variant) -> (archs of the package, hipBLASLt version it bundles, architectures that must carry a table)
+PACKAGES = {
+ ("windows-x86_64", "rx9070"): (("gfx1200", "gfx1201"), 100500, {"gfx1201"}),
+ ("windows-x86_64", "rdna3"): (("gfx1100", "gfx1101", "gfx1102", "gfx1151"), 100500, {"gfx1100", "gfx1151"}),
+ ("linux-x86_64", "rx9070"): (("gfx1200", "gfx1201"), 100200, set()), # no table for 1.2.0 on RDNA4 (docs/AMD_HIP.md)
+ ("linux-x86_64", "rx7900"): (("gfx1100", "gfx1101", "gfx1102"), 100200, {"gfx1100"}),
+ ("linux-x86_64", "halo"): (("gfx1151",), 100401, {"gfx1151"}),
+}
+
+
+ON = {ht.SWITCH: "on"} # the switch that uses a matching table whatever "auto" does
+AUTO = {}
+
+
+def fake_table(folder: Path, arch: str, version: int, *, header: str | None = None) -> Path:
+ folder.mkdir(parents=True, exist_ok=True)
+ path = folder / ht.table_name(arch, version)
+ path.write_text(f"# solution ids are scoped to this hipBLASLt version and device architecture\n"
+ f"{header or f'{ht.HEADER} {arch} {version}'}\nbf16 128 2560 128 4096 73754\n", encoding="utf-8")
+ return path
+
+
+def fake_package(root: Path, *, version: int | None = 100500, tables=(("gfx1201", 100500),), build=True) -> Path:
+ folder = root / "0.2.1-pkg"
+ folder.mkdir(parents=True)
+ meta = {"version": "0.2.1", "backend": "hip"}
+ if version is not None:
+ meta["hipblaslt_version"] = version
+ if build:
+ (folder / "BUILD.json").write_text(json.dumps(meta), encoding="utf-8")
+ for arch, ver in tables:
+ fake_table(folder / ht.TABLE_DIR, arch, ver)
+ return folder
+
+
+class TempDir(unittest.TestCase):
+ def setUp(self):
+ self.dir = tempfile.TemporaryDirectory()
+ self.addCleanup(self.dir.cleanup)
+ self.root = Path(self.dir.name)
+
+
+class Decision(TempDir):
+ """Match, mismatch, switch, the person's own choice."""
+
+ def test_a_table_for_this_card_and_this_hipblaslt_is_used(self):
+ pkg = fake_package(self.root)
+ d = ht.resolve(pkg, ["gfx1201"], environ=ON)
+ self.assertEqual(d.path, pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
+ self.assertIn("gfx1201-hipblaslt-100500.txt", d.message)
+ self.assertIn(ht.SWITCH, d.message) # the line tells how to turn it off
+ self.assertEqual(d.level, "info")
+
+ def test_a_table_for_another_hipblaslt_version_is_not_used_and_the_log_says_why(self):
+ pkg = fake_package(self.root, version=100200, tables=(("gfx1201", 100500),))
+ d = ht.resolve(pkg, ["gfx1201"], environ=ON)
+ self.assertIsNone(d.path)
+ self.assertEqual(d.level, "warn")
+ self.assertIn("100200", d.message)
+ self.assertIn("100500", d.message)
+ self.assertIn("plain hipBLAS", d.message)
+
+ def test_a_card_without_a_table_in_the_package_gets_plain_hipblas_and_one_line(self):
+ pkg = fake_package(self.root)
+ d = ht.resolve(pkg, ["gfx1200"], environ=ON)
+ self.assertIsNone(d.path)
+ self.assertIn("none for gfx1200", d.message)
+
+ def test_the_card_that_has_a_table_is_found_among_several(self):
+ pkg = fake_package(self.root, tables=(("gfx1100", 100500), ("gfx1151", 100500)))
+ self.assertEqual(ht.resolve(pkg, ["gfx1101", "gfx1151"], environ=ON).path.name, "gfx1151-hipblaslt-100500.txt")
+
+ def test_a_package_that_does_not_say_its_hipblaslt_is_not_guessed_at(self):
+ pkg = fake_package(self.root, version=None)
+ d = ht.resolve(pkg, ["gfx1201"], environ=ON)
+ self.assertIsNone(d.path)
+ self.assertEqual(d.level, "warn")
+ self.assertIn("hipblaslt_version", d.message)
+
+ def test_an_unreadable_card_is_a_note_not_a_guess(self):
+ d = ht.resolve(fake_package(self.root), [], environ=ON)
+ self.assertIsNone(d.path)
+ self.assertIn("could not be read", d.message)
+
+ def test_a_table_whose_header_disagrees_with_its_name_is_not_used(self):
+ pkg = fake_package(self.root, tables=())
+ fake_table(pkg / "tuning", "gfx1201", 100500, header=f"{ht.HEADER} gfx1201 100401")
+ d = ht.resolve(pkg, ["gfx1201"], environ=ON)
+ self.assertIsNone(d.path)
+ self.assertIn("header", d.message)
+
+ def test_the_switch_turns_it_off_in_the_environment_and_in_the_run_config(self):
+ pkg = fake_package(self.root)
+ for word in ("off", "OFF", "0", "no", "false", "none"):
+ d = ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: word})
+ self.assertIsNone(d.path, word)
+ self.assertIn("off", d.message)
+ self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ=AUTO, cfg={"hipblaslt_table": False}).path)
+ self.assertIsNotNone(ht.resolve(pkg, ["gfx1201"], environ=AUTO, cfg={"hipblaslt_table": True}).path)
+ self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: "off"}, cfg={"hipblaslt_table": True}).path) # the environment wins
+ for word in ("on", "ON", "1", "yes", "true"):
+ self.assertIsNotNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: word}).path, word)
+
+ def test_auto_follows_the_one_constant_and_says_what_is_available(self):
+ pkg = fake_package(self.root)
+ with mock.patch.object(ht, "AUTO_USES_TABLE", False):
+ d = ht.resolve(pkg, ["gfx1201"], environ=AUTO)
+ self.assertIsNone(d.path)
+ self.assertIn("gfx1201-hipblaslt-100500.txt", d.message)
+ self.assertIn(f"{ht.SWITCH}=on", d.message)
+ self.assertEqual(ht.mode(AUTO), "auto")
+ with mock.patch.object(ht, "AUTO_USES_TABLE", True):
+ d = ht.resolve(pkg, ["gfx1201"], environ=AUTO)
+ self.assertEqual(d.path, pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
+ self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: "off"}).path)
+
+ def test_the_default_is_off_until_the_owner_decides(self):
+ """A table changes the bits of the prompt's dense GEMMs (notes-021-hip.md); this fails on purpose when someone flips the default."""
+ self.assertFalse(ht.AUTO_USES_TABLE)
+
+ def test_a_table_the_person_set_is_never_replaced(self):
+ pkg = fake_package(self.root)
+ mine = str(self.root / "mine.txt")
+ for environ, cfg in (({ht.ENGINE_VAR: mine}, {}), ({}, {"env": {ht.ENGINE_VAR: mine}})):
+ d = ht.resolve(pkg, ["gfx1201"], environ=environ, cfg=cfg)
+ self.assertIsNone(d.path)
+ self.assertIn(mine, d.message)
+ out = ht.apply({"backend": "hip", **cfg}, pkg, ["gfx1201"], environ=environ, say=lambda line: None)
+ self.assertEqual((out.get("env") or {}).get(ht.ENGINE_VAR, mine), mine)
+
+
+class Apply(TempDir):
+ def test_apply_puts_the_table_in_a_copy_of_the_config_and_says_so_once(self):
+ pkg = fake_package(self.root)
+ cfg = {"backend": "hip", "env": {"STRATA_RESIDENT_PIN": "0"}}
+ lines = []
+ out = ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append)
+ self.assertEqual(out["env"][ht.ENGINE_VAR], str(pkg / "tuning" / "gfx1201-hipblaslt-100500.txt"))
+ self.assertEqual(out["env"]["STRATA_RESIDENT_PIN"], "0")
+ self.assertNotIn(ht.ENGINE_VAR, cfg["env"]) # the caller's config is untouched
+ self.assertEqual(len(lines), 1)
+ self.assertTrue(lines[0].startswith("[strata] hipBLASLt tuning table"))
+
+ def test_apply_with_a_mismatch_leaves_the_config_alone_and_warns(self):
+ pkg = fake_package(self.root, version=100200)
+ cfg = {"backend": "hip"}
+ lines = []
+ self.assertIs(ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append), cfg)
+ self.assertEqual(len(lines), 1)
+ self.assertIn("note", lines[0])
+
+ def test_other_backends_and_packages_without_tables_are_silent(self):
+ lines = []
+ pkg = fake_package(self.root)
+ cfg = {"backend": "cuda"}
+ self.assertIs(ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append), cfg)
+ bare = self.root / "cuda-pkg"
+ bare.mkdir()
+ (bare / "BUILD.json").write_text(json.dumps({"version": "0.2.1"}), encoding="utf-8")
+ out = ht.apply({"backend": "hip"}, bare, ["gfx1201"], environ=ON, say=lines.append)
+ self.assertNotIn("env", out)
+ self.assertEqual(lines, [])
+
+ def test_the_server_start_applies_it_for_a_component_engine(self):
+ from serve import server
+ pkg = fake_package(self.root)
+ (pkg / "strata").write_text("x", encoding="utf-8")
+ cfg = {"exe": "component:strata-engine", "backend": "hip"}
+ out = io.StringIO()
+ with mock.patch.object(server.engine_component, "expand", return_value=str(pkg / "strata")), \
+ mock.patch.object(ht, "present_archs", return_value=["gfx1201"]), \
+ mock.patch.dict(os.environ, {}, clear=False), contextlib.redirect_stdout(out):
+ os.environ.pop(ht.SWITCH, None)
+ os.environ.pop(ht.ENGINE_VAR, None)
+ self.assertNotIn(ht.ENGINE_VAR, server.child_env(server.with_component_engine(cfg))) # "auto" is off by default
+ os.environ[ht.SWITCH] = "on"
+ started = server.with_component_engine(cfg)
+ env = server.child_env(started)
+ self.assertEqual(env[ht.ENGINE_VAR], str(pkg / "tuning" / "gfx1201-hipblaslt-100500.txt"))
+ os.environ[ht.SWITCH] = "off"
+ self.assertNotIn(ht.ENGINE_VAR, server.child_env(server.with_component_engine(cfg)))
+ self.assertIn("hipBLASLt tuning table", out.getvalue())
+
+ def test_present_archs_picks_the_configured_card_on_linux(self):
+ with mock.patch("strata_control.engine_component.hip_archs_present", return_value=["gfx1100", "gfx1201"]):
+ if os.name != "nt":
+ self.assertEqual(ht.present_archs({"gpu": 1}), ["gfx1201"])
+ self.assertEqual(ht.present_archs({"gpu": [1, 0]}), ["gfx1201", "gfx1100"])
+ self.assertEqual(ht.present_archs({}), ["gfx1100", "gfx1201"])
+
+
+class PackageContents(TempDir):
+ """What each package of the release matrix carries, from the real tables of tools/hip."""
+
+ def test_every_release_package_carries_the_tables_its_cards_have(self):
+ for (platform, variant), (archs, version, wanted) in PACKAGES.items():
+ stage = self.root / f"{platform}-{variant}"
+ stage.mkdir()
+ copied = ht.stage_tables(stage, archs, version, TABLES)
+ self.assertEqual({n.split("-")[0] for n in copied}, wanted, (platform, variant))
+ on_disk = {p.name for p in (stage / "tuning").glob("*.txt")} if (stage / "tuning").is_dir() else set()
+ self.assertEqual(on_disk, set(copied), (platform, variant))
+ for arch in wanted: # the file the engine start will pick is there and its own header agrees
+ self.assertTrue(ht.header_ok(stage / "tuning" / ht.table_name(arch, version), arch, version), (platform, arch))
+
+ def test_the_missing_report_names_the_architectures_without_a_table(self):
+ left = ht.missing_report(("gfx1100", "gfx1101", "gfx1102"), 100200, TABLES)
+ self.assertEqual(sorted(left), ["gfx1101", "gfx1102"])
+ self.assertEqual(ht.missing_report(("gfx1201",), 100200, TABLES), {"gfx1201": [100202, 100500]})
+
+ def test_every_table_in_the_repo_has_a_header_that_matches_its_name(self):
+ tables = ht.tables_in(TABLES)
+ self.assertGreater(len(tables), 8)
+ for (arch, version), path in tables.items():
+ self.assertTrue(ht.header_ok(path, arch, version), path.name)
+
+ def test_version_from_header_reads_the_rocm_tree(self):
+ inc = self.root / "include" / "hipblaslt"
+ inc.mkdir(parents=True)
+ (inc / "hipblaslt-version.h").write_text("#define HIPBLASLT_VERSION_MAJOR 1\n#define HIPBLASLT_VERSION_MINOR 5\n"
+ "#define HIPBLASLT_VERSION_PATCH 0\n", encoding="utf-8")
+ self.assertEqual(ht.version_from_header(self.root), 100500)
+ self.assertIsNone(ht.version_from_header(self.root / "nowhere"))
+
+ def test_stage_tuning_writes_the_version_and_the_tables(self):
+ stage = self.root / "stage"
+ stage.mkdir()
+ (stage / "BUILD.json").write_text(json.dumps({"version": "0.2.1", "archs": ["gfx1151"]}), encoding="utf-8")
+ with contextlib.redirect_stdout(io.StringIO()):
+ self.assertEqual(stage_tuning.main(["--stage", str(stage), "--archs", "gfx1151", "--version", "100401"]), 0)
+ meta = json.loads((stage / "BUILD.json").read_text(encoding="utf-8"))
+ self.assertEqual(meta["hipblaslt_version"], 100401)
+ self.assertEqual(meta["archs"], ["gfx1151"]) # what was there stays
+ self.assertTrue((stage / "tuning" / "gfx1151-hipblaslt-100401.txt").is_file())
+
+ def test_stage_tuning_can_demand_a_table(self):
+ stage = self.root / "stage"
+ stage.mkdir()
+ with contextlib.redirect_stdout(io.StringIO()), self.assertRaises(SystemExit) as caught:
+ stage_tuning.main(["--stage", str(stage), "--archs", "gfx1201", "--version", "100200", "--expect", "gfx1201"])
+ self.assertIn("gfx1201", str(caught.exception))
+
+ def test_stage_tuning_refuses_a_rocm_whose_version_it_cannot_read(self):
+ stage = self.root / "stage"
+ stage.mkdir()
+ with self.assertRaises(SystemExit):
+ stage_tuning.main(["--stage", str(stage), "--archs", "gfx1201", "--rocm", str(self.root / "no-rocm")])
+
+
+class PackagedAndHashed(TempDir):
+ """packaging/package_engine.py: the tables are files of the package (hashed, so signed with it) and a bad AMD stage is refused."""
+
+ def stage(self, **kw):
+ src = self.root / "src"
+ src.mkdir()
+ (src / "strata").write_bytes(b"engine" * 100)
+ (src / "libamdhip64.so.7").write_bytes(b"hip" * 100)
+ (src / "BUILD.json").write_text(json.dumps({"version": "0.2.1", **kw}), encoding="utf-8")
+ return src
+
+ def build(self, src, archs=("gfx1201",), tree=False):
+ out = self.root / "out"
+ out.mkdir(exist_ok=True)
+ with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]):
+ return package_engine.build(src, "hip", "0.2.1", "linux-x86_64", out, entry="strata", archs=archs, build_id="t", tree=tree,
+ variant="rx9070")
+
+ def test_the_tables_are_listed_and_hashed_in_the_manifest_even_without_tree(self):
+ src = self.stage(hipblaslt_version=100500)
+ fake_table(src / "tuning", "gfx1201", 100500)
+ folder = self.build(src)
+ listed = {f["path"]: f for f in json.loads((folder / "engine-component.json").read_text(encoding="utf-8"))["files"]}
+ self.assertIn("tuning/gfx1201-hipblaslt-100500.txt", listed)
+ self.assertEqual(len(listed["tuning/gfx1201-hipblaslt-100500.txt"]["sha256"]), 64)
+ (folder / "tuning" / "gfx1201-hipblaslt-100500.txt").write_text("changed", encoding="utf-8") # a swapped table fails the start's hash check
+ from strata_control import engine_component as ec
+ with self.assertRaises(ec.ComponentProblem):
+ ec.verify(ec.read_manifest(folder), full=True)
+
+ def test_an_amd_stage_without_a_hipblaslt_version_is_refused(self):
+ src = self.stage()
+ with self.assertRaises(SystemExit) as caught:
+ self.build(src)
+ self.assertIn("hipblaslt_version", str(caught.exception))
+
+ def test_a_table_for_another_version_or_card_than_the_package_is_refused(self):
+ src = self.stage(hipblaslt_version=100500)
+ fake_table(src / "tuning", "gfx1201", 100202)
+ with self.assertRaises(SystemExit) as caught:
+ self.build(src)
+ self.assertIn("100202", str(caught.exception))
+ other = self.root / "other"
+ other.mkdir()
+ src2 = other / "src"
+ src2.mkdir()
+ (src2 / "strata").write_bytes(b"e")
+ (src2 / "BUILD.json").write_text(json.dumps({"hipblaslt_version": 100500}), encoding="utf-8")
+ fake_table(src2 / "tuning", "gfx1100", 100500)
+ with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]), self.assertRaises(SystemExit) as caught:
+ package_engine.build(src2, "hip", "0.2.1", "linux-x86_64", other / "out", entry="strata", archs=("gfx1201",), build_id="t")
+ self.assertIn("gfx1100", str(caught.exception))
+
+ def test_a_cuda_package_needs_no_hipblaslt_version(self):
+ src = self.stage()
+ out = self.root / "out"
+ out.mkdir()
+ with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]):
+ package_engine.build(src, "cuda", "0.2.1", "linux-x86_64", out, entry="strata", archs=("sm_86",), build_id="t")
+
+
+class SetupFindsThePackageTable(TempDir):
+ """setup.py outside the app (a git checkout, or the old Windows zip that START-HERE unpacks): the engine folder's own tuning/ comes first."""
+
+ def load_setup(self):
+ import importlib.util
+ spec = importlib.util.spec_from_file_location("setup_hipblaslt_copy", ROOT / "setup.py")
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+ def test_the_engine_folders_table_wins_over_tools_hip_and_the_switch_turns_it_off(self):
+ setup = self.load_setup()
+ pkg = self.root / "engine"
+ fake_table(pkg / "tuning", "gfx1201", 100500)
+ seen = []
+ with mock.patch.object(setup, "ok", seen.append), mock.patch.object(setup, "say", seen.append), \
+ mock.patch.object(setup, "warn", seen.append), mock.patch.dict(os.environ, {}, clear=False):
+ os.environ.pop(ht.SWITCH, None)
+ self.assertEqual(setup.hipblaslt_table("gfx1201", [], 100500, [pkg / "tuning"]), pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
+ self.assertEqual(setup.hipblaslt_table("gfx1201", [], 100500), TABLES / "gfx1201-hipblaslt-100500.txt")
+ self.assertIsNone(setup.hipblaslt_table("gfx1201", [], 100200, [pkg / "tuning"])) # no table for 1.2.0: warned, plain
+ os.environ[ht.SWITCH] = "off"
+ self.assertIsNone(setup.hipblaslt_table("gfx1201", [], 100500, [pkg / "tuning"]))
+ self.assertTrue(any("no hipBLASLt tuning table" in str(line) for line in seen))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/hip/package_windows.py b/tools/hip/package_windows.py
index 82dc26cc2..657898f59 100644
--- a/tools/hip/package_windows.py
+++ b/tools/hip/package_windows.py
@@ -15,6 +15,8 @@ tools/hip/build_windows.bat runs it after the build. The zip holds:
through the ROCm DLLs, + amd_comgr.dll, which the HIP runtime loads
by name) and the Microsoft C++ runtime they import
rocm/bin/rocblas/library, rocm/bin/hipblaslt/library the GEMM kernels, for these archs only
+ tuning/<arch>-hipblaslt-<version>.txt the hipBLASLt tuning tables of tools/hip for these archs and this hipBLASLt version
+ (BUILD.json hipblaslt_version); the engine start uses the one for the card
rocm/.kpack/ rocBLAS's own device code for these archs (rocblas.dll finds it at
../.kpack from its folder)
rocm/licenses/ the shipped components' licenses, and NOTICE.txt
@@ -35,6 +37,9 @@ import zipfile
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT))
+from strata_control import hipblaslt_tuning as ht # noqa: E402
+
ASSET = "strata-windows-x64-hip.zip"
PROGRAMS = ("strata.exe", "strata-device.exe")
DYNAMIC = ("amd_comgr.dll",) # LoadLibrary'd by amdhip64_7.dll: not in any import table
@@ -170,6 +175,12 @@ def main() -> int:
if a.vision_hip is not None:
meta.update({"vision": "gpu", "vision_gpu": a.vision_hip.name, "vision_archs": archs})
(stage / "BUILD.json").write_text(json.dumps(meta, indent=1), encoding="utf-8")
+ # the hipBLASLt tuning tables of tools/hip for these archs and exactly this hipBLASLt version, in tuning/ (strata_control/hipblaslt_tuning.py):
+ # the engine start points STRATA_HIPBLASLT_TUNING at the one for the card; an arch without a table keeps plain hipBLAS
+ tables = ht.stage_tables(stage, archs, meta["hipblaslt_version"], ROOT / "tools" / "hip")
+ for arch, have in ht.missing_report(archs, meta["hipblaslt_version"], ROOT / "tools" / "hip").items():
+ print(f"no hipBLASLt table for {arch} with hipBLASLt {meta['hipblaslt_version']} (the repo has: {', '.join(map(str, have)) or 'none'}): plain hipBLAS there")
+ print("hipBLASLt tuning tables:", ", ".join(tables) or "none")
z = a.out / ASSET
z.unlink(missing_ok=True)