Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions BUILDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,17 +33,24 @@ these defaults:
| `WG_TOOLCHAINS` | folder that holds `dxc-v1.10.2605.24\` (the DXC release zip, unpacked) and `rga-2.15\` (the RGA zip, unpacked) | `<repository>\toolchains` (ignored by git) |
| `WG_DXC_DIR` | DXC's `bin\x64` folder (overrides `WG_TOOLCHAINS`) | `%WG_TOOLCHAINS%\dxc-v1.10.2605.24\bin\x64` |
| `WG_RGA` | `rga.exe` (overrides `WG_TOOLCHAINS`) | `%WG_TOOLCHAINS%\rga-2.15\rga.exe` |
| `ROCM_PATH` | HIP SDK folder. Scripts with a `--rocm` argument default to it (the argument wins); the others read it | `C:\Program Files\AMD\ROCm\7.2` |
| `ROCM_PATH` | Not read by the build scripts: they use the newest official AMD HIP SDK 7.x install (`C:\Program Files\AMD\ROCm\<version>`, `/opt/rocm-<version>`; `clean/runner/sdk.py`); `--rocm` or `--clang` outside it needs `--force-sdk` | - |
| `VSDEVCMD` | Visual Studio's `VsDevCmd.bat` (the kernel scripts build two small helper tools); for another edition e.g. `C:\Program Files\Microsoft Visual Studio\18\Professional\Common7\Tools\VsDevCmd.bat` (or `...\18\Enterprise\...`) | `C:\Program Files\Microsoft Visual Studio\18\Community\Common7\Tools\VsDevCmd.bat` |
| `CXX`, `WG_K_RT_CXX`, `WG_K_RT_BUILD`, `WG_CONVERTER_EXE` | Model K table tests (`clean\k\tests\test_k_runtime_tables`, `test_k_runtime_pack`): the compiler is `%CXX%`, else clang++ / g++ on PATH, else the HIP SDK's clang++, else MSVC (`WG_K_RT_CXX=msvc` picks MSVC first); their build folder; an already built converter. With no compiler found the tests skip themselves with that reason | temporary folder; converter built from source |
| `WG_BUILD_ROOT` | default output root of the scripts that have one | `<repository>\build` (ignored by git) |
| `WG_DX12_JOBS`, `WG_RR_JOBS` | parallel kernel compiles | number of CPUs (max 12) / 8 |
| `WG_GPU_LOCK` | optional: a script run as `python <lock> --timeout <s> -- <command>` around GPU jobs | unset: GPU jobs run directly |
| `WRONGGPU_HIP_RUNTIME` | the HIP runtime the launcher's probe loads (tests: the stand-in of step 5.1) | the system's |

Set `ROCM_PATH` to the HIP SDK folder (the commands below also pass it as `--rocm`). Remove `HIP_PATH`, `LLVM_PATH`,
`HIP_DEVICE_LIB_PATH` and `HIP_CLANG_PATH` from the build's environment unless you set them on purpose; the scripts give
the HIP compiler the folder explicitly.
The build scripts use the newest official AMD HIP SDK 7.x install (`C:\Program Files\AMD\ROCm\<version>`; on
other systems `/opt/rocm-<version>` or `/opt/rocm`, which counts with the version it points to, or as a standalone
install with its own), its own clang and device libraries, and the Python tools load the HIP runtime library from it by
full path. They never take an SDK, a compiler or a library from the environment (`ROCM_PATH`,
`HIP_PATH`, `LLVM_PATH`, `HIP_DEVICE_LIB_PATH`, `HIP_CLANG_PATH`) or from `PATH`; every HIP compile checks this at
one place (`device_command`). Remove those variables from the build's environment anyway: the vendor runtime reads
some of them. Another SDK or compiler needs `--rocm <folder>` / `--clang <path>` with `--force-sdk` (build.py,
k_build.py and every script with `--rocm`); every build log names the SDK, compiler and device-library folders, a custom
one only by an id, also in compiler output. The native runtime's and the installer's own HIP runtime lookup are not
part of this rule yet (planned for 0.6.6).

Open a "x64 Native Tools Command Prompt for VS 2026" (or call `vcvars64.bat`) for every step below, at the repository
root. The commands write into `out\`; any folder outside the repository works the same.
Expand Down
5 changes: 4 additions & 1 deletion clean/dx12/compare.py
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,9 @@ def main(argv=None):
ap.add_argument("--candidate-build", help="optional separate native/hybrid build; --build remains the HIP oracle")
ap.add_argument("--kernels", required=True, help="WG_DX12_KERNELS for the hybrid run (names as launched, or all)")
ap.add_argument("--backend", choices=("dx12", "d3d12"), default="dx12", help="candidate device; HIP stays the oracle")
ap.add_argument("--rocm", default=r"C:\Program Files\AMD\ROCm\7.2")
from clean.runner import sdk # the HIP SDK policy: --rocm, --force-sdk
ap.add_argument("--rocm", default="")
sdk.add_force_argument(ap)
ap.add_argument("--models", default=DEFAULT_MODELS, help="work dir for the synthetic model")
ap.add_argument("--frames", type=int, default=4)
ap.add_argument("--quick", action="store_true", help="only the small odd-size case")
Expand All @@ -350,6 +352,7 @@ def main(argv=None):
ap.add_argument("--json")
ap.add_argument("--trace", help="new trace path; defaults to a unique directory inside the build")
a = ap.parse_args(argv)
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
if a.frames < 1:
ap.error("--frames must be positive")
if a.probe_unused_capacity and a.frames < 2:
Expand Down
21 changes: 17 additions & 4 deletions clean/dx12/f16lut/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,10 @@
sys.path.insert(0, DX12)
import build_dx12 # noqa: E402

ROCM = os.environ.get("ROCM_PATH", r"C:\Program Files\AMD\ROCm\7.2")
sys.path.insert(0, os.path.dirname(CLEAN))
from clean.runner import sdk # noqa: E402 (the HIP SDK policy)

ROCM = sdk.OFFICIAL_ROCM # main: --rocm through sdk.resolve (an official SDK; another one only with --force-sdk)
# Optional GPU lock (WG_GPU_LOCK: a script run as `python <lock> --timeout <s> -- <command>`, e.g. to keep
# GPU jobs of several shells apart); unset: the command runs directly.
GPU_LOCK = os.environ.get("WG_GPU_LOCK", "")
Expand All @@ -49,11 +52,18 @@ def hip_env():

def run(cmd, **kw):
r = subprocess.run(cmd, capture_output=True, text=True, **kw)
if r.returncode not in (0, 5):
print(r.stdout[-2000:], r.stderr[-2000:])
if r.returncode not in (0, 5): # a custom (forced) SDK appears by id only
print(sdk.redact(r.stdout[-2000:]), sdk.redact(r.stderr[-2000:]))
return r


def hip_clang():
"""The SDK's own clang, through the shared SDK policy check (banner once)."""
clang = sdk.compiler(ROCM, None)
sdk.check(ROCM, clang)
return clang


def gpu(args, **kw):
return run(_locked(args), timeout=1800, **kw)

Expand Down Expand Up @@ -83,11 +93,14 @@ def main():
ap = argparse.ArgumentParser()
ap.add_argument("--work", required=True)
ap.add_argument("--batch", type=int, default=150)
sdk.add_arguments(ap)
a = ap.parse_args()
global ROCM
ROCM = sdk.resolve(a.rocm, a.force_sdk)
w = os.path.abspath(a.work)
os.makedirs(w, exist_ok=True)
co = os.path.join(w, "oracle.co")
r = run([os.path.join(ROCM, "bin", "clang.exe"), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only",
r = run([hip_clang(), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only",
"-nogpuinc", "-O3", "--no-gpu-bundle-output", f"--rocm-path={ROCM}",
f"--rocm-device-lib-path={os.path.join(ROCM, 'amdgcn', 'bitcode')}", "-I", os.path.join(CLEAN, "kernels"),
os.path.join(HERE, "oracle.hip"), "-o", co], env=hip_env())
Expand Down
21 changes: 17 additions & 4 deletions clean/dx12/f16lut/run_in.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,10 @@
sys.path.insert(0, DX12)
import build_dx12 # noqa: E402

ROCM = os.environ.get("ROCM_PATH", r"C:\Program Files\AMD\ROCm\7.2")
sys.path.insert(0, os.path.dirname(CLEAN))
from clean.runner import sdk # noqa: E402 (the HIP SDK policy)

ROCM = sdk.OFFICIAL_ROCM # main: --rocm through sdk.resolve (an official SDK; another one only with --force-sdk)
# Optional GPU lock (WG_GPU_LOCK: a script run as `python <lock> --timeout <s> -- <command>`, e.g. to keep
# GPU jobs of several shells apart); unset: the command runs directly.
GPU_LOCK = os.environ.get("WG_GPU_LOCK", "")
Expand All @@ -54,11 +57,18 @@ def hip_env():

def run(cmd, **kw):
r = subprocess.run(cmd, capture_output=True, text=True, **kw)
if r.returncode not in (0, 5):
print(r.stdout[-2000:], r.stderr[-2000:])
if r.returncode not in (0, 5): # a custom (forced) SDK appears by id only
print(sdk.redact(r.stdout[-2000:]), sdk.redact(r.stderr[-2000:]))
return r


def hip_clang():
"""The SDK's own clang, through the shared SDK policy check (banner once)."""
clang = sdk.compiler(ROCM, None)
sdk.check(ROCM, clang)
return clang


def gpu(args, **kw):
return run(_locked(args), timeout=1800, **kw)

Expand Down Expand Up @@ -89,11 +99,14 @@ def main():
ap = argparse.ArgumentParser()
ap.add_argument("--work", required=True)
ap.add_argument("--batch", type=int, default=150)
sdk.add_arguments(ap)
a = ap.parse_args()
global ROCM
ROCM = sdk.resolve(a.rocm, a.force_sdk)
w = os.path.abspath(a.work)
os.makedirs(w, exist_ok=True)
co = os.path.join(w, "oracle_in.co")
r = run([os.path.join(ROCM, "bin", "clang.exe"), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only",
r = run([hip_clang(), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only",
"-nogpuinc", "-O3", "--no-gpu-bundle-output", f"--rocm-path={ROCM}",
f"--rocm-device-lib-path={os.path.join(ROCM, 'amdgcn', 'bitcode')}", "-I", os.path.join(CLEAN, "kernels"),
os.path.join(HERE, "oracle_in.hip"), "-o", co], env=hip_env())
Expand Down
24 changes: 19 additions & 5 deletions clean/dx12/gelu_lut/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,10 @@
sys.path.insert(0, DX12)
import build_dx12 # noqa: E402

ROCM = os.environ.get("ROCM_PATH", r"C:\Program Files\AMD\ROCm\7.2")
sys.path.insert(0, os.path.dirname(CLEAN))
from clean.runner import sdk # noqa: E402 (the HIP SDK policy)

ROCM = sdk.OFFICIAL_ROCM # main: --rocm through sdk.resolve (an official SDK; another one only with --force-sdk)
# Optional GPU lock (WG_GPU_LOCK: a script run as `python <lock> --timeout <s> -- <command>`, e.g. to keep
# GPU jobs of several shells apart); unset: the command runs directly.
GPU_LOCK = os.environ.get("WG_GPU_LOCK", "")
Expand All @@ -52,21 +55,29 @@ def hip_env():


def run(cmd, **kw):
print(">", " ".join(cmd) if isinstance(cmd, list) else cmd, flush=True)
# a custom (forced) SDK appears by id only, in the command and in the tools' output
print(">", sdk.redact(" ".join(cmd) if isinstance(cmd, list) else cmd), flush=True)
r = subprocess.run(cmd, capture_output=True, text=True, **kw)
print(r.stdout.strip())
print(sdk.redact(r.stdout.strip()))
if r.stderr.strip():
print(r.stderr.strip())
print(sdk.redact(r.stderr.strip()))
return r


def hip_clang():
"""The SDK's own clang, through the shared SDK policy check (banner once)."""
clang = sdk.compiler(ROCM, None)
sdk.check(ROCM, clang)
return clang


def gpu(args, **kw):
return run(_locked(args), **kw)


def build_tools(w):
co = os.path.join(w, "oracle.co")
r = run([os.path.join(ROCM, "bin", "clang.exe"), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only", "-nogpuinc",
r = run([hip_clang(), "-x", "hip", "--offload-arch=gfx1201", "--offload-device-only", "-nogpuinc",
"-O3", "--no-gpu-bundle-output", f"--rocm-path={ROCM}",
f"--rocm-device-lib-path={os.path.join(ROCM, 'amdgcn', 'bitcode')}", "-I", os.path.join(CLEAN, "kernels"),
os.path.join(HERE, "oracle.hip"), "-o", co], env=hip_env())
Expand Down Expand Up @@ -102,7 +113,10 @@ def main():
ap.add_argument("--skip-oracle", action="store_true", help="reuse <work>/rle.bin")
ap.add_argument("--table", help="compact design: this table (mk_headers.py output) instead of running gen.py")
ap.add_argument("--define", action="append", default=[], help="NAME=VALUE for the verify shader (WG_GELU_LUT_ALT=1)")
sdk.add_arguments(ap)
a = ap.parse_args()
global ROCM
ROCM = sdk.resolve(a.rocm, a.force_sdk)
w = os.path.abspath(a.work)
os.makedirs(w, exist_ok=True)
proof = {}
Expand Down
7 changes: 6 additions & 1 deletion clean/dx12/tests/matched_stage_bench.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@
import subprocess
import sys

sys.path.insert(0, str(Path(__file__).resolve().parents[3])) # the repository, for clean.runner
from clean.runner import sdk # noqa: E402 (the HIP SDK policy: --rocm, --force-sdk)

HERE = Path(__file__).resolve().parent
ROOT = HERE.parents[2]

Expand Down Expand Up @@ -252,7 +255,8 @@ def main():
p = argparse.ArgumentParser(description=__doc__)
p.add_argument('--build', required=True, help='frozen complete HIP/native payload build')
p.add_argument('--out', required=True, help='private build and evidence directory')
p.add_argument('--rocm', default=r'C:\Program Files\AMD\ROCm\7.2')
p.add_argument('--rocm', default='')
sdk.add_force_argument(p)
p.add_argument('--prepare', action='store_true', help='CPU-only compile/input/model generation')
p.add_argument('--rebuild', action='store_true', help='with --prepare, recompile while preserving verified original inputs/model')
p.add_argument('--run', action='store_true', help='GPU work: use shared lock + activity wrapper')
Expand All @@ -268,6 +272,7 @@ def main():
p.add_argument('--run-tag', default='paired-r0')
p.add_argument('--clock-co', default=os.environ.get('WG_CLOCK_CO', ''), help='original synthetic cycle/realtime probe')
a = p.parse_args()
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
if not a.prepare and not a.run:
p.error('choose --prepare and/or --run')
if not (math.isfinite(a.warm) and a.warm >= 3 and math.isfinite(a.minimum_window_seconds) and
Expand Down
8 changes: 7 additions & 1 deletion clean/dx12/tests/native_direct_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,21 @@
import os
from pathlib import Path
import subprocess
import sys

sys.path.insert(0, str(Path(__file__).resolve().parents[3])) # the repository, for clean.runner
from clean.runner import sdk # noqa: E402 (the HIP SDK policy: --rocm, --force-sdk)


def main():
p = argparse.ArgumentParser(description=__doc__)
p.add_argument('--out', required=True)
p.add_argument('--rocm', default=r'C:\Program Files\AMD\ROCm\7.2')
p.add_argument('--rocm', default='')
sdk.add_force_argument(p)
p.add_argument('--model-l', action='store_true',
help='also Model L (WG_MODEL_L, clean/l/runtime): the test then runs it with its last argument L')
a = p.parse_args()
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
clean = Path(__file__).resolve().parents[2]
rt = clean / 'runtime'
out = Path(a.out).resolve()
Expand Down
7 changes: 6 additions & 1 deletion clean/dx12/tests/native_direct_dll_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@
import subprocess
import sys

sys.path.insert(0, str(Path(__file__).resolve().parents[3])) # the repository, for clean.runner
from clean.runner import sdk # noqa: E402 (the HIP SDK policy: --rocm, --force-sdk)


COMMON = ('swin_block_c64_nc', 'patch_merge_c64', 'swin_block_c96_nc', 'patch_merge_c96',
'bneck/swin_bneck6_nc', 'swin_block_c96_add_ex_nc', 'expand_c96',
Expand Down Expand Up @@ -193,7 +196,8 @@ def main():
p = argparse.ArgumentParser(description=__doc__)
p.add_argument('--prepare', action='store_true')
p.add_argument('--out', required=True, help='New private directory; never overwrites evidence')
p.add_argument('--rocm', default=r'C:\Program Files\AMD\ROCm\7.2')
p.add_argument('--rocm', default='')
sdk.add_force_argument(p)
p.add_argument('--exe')
p.add_argument('--build')
p.add_argument('--model')
Expand All @@ -202,6 +206,7 @@ def main():
p.add_argument('--frames', type=int, default=8)
p.add_argument('--output-format', choices=('half', 'float'), default='half')
a = p.parse_args()
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
if a.frames < 6 or min(a.shape) < 1:
p.error('positive shapes and at least six frames required')
return build(a) if a.prepare else run(a)
Expand Down
8 changes: 7 additions & 1 deletion clean/dx12/tests/native_game_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,19 @@
import os
from pathlib import Path
import subprocess
import sys

sys.path.insert(0, str(Path(__file__).resolve().parents[3])) # the repository, for clean.runner
from clean.runner import sdk # noqa: E402 (the HIP SDK policy: --rocm, --force-sdk)


def main():
p = argparse.ArgumentParser(description=__doc__)
p.add_argument('--out', required=True)
p.add_argument('--rocm', default=r'C:\Program Files\AMD\ROCm\7.2')
p.add_argument('--rocm', default='')
sdk.add_force_argument(p)
a = p.parse_args()
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
clean = Path(__file__).resolve().parents[2]
rt = clean / 'runtime'
out = Path(a.out).resolve()
Expand Down
5 changes: 4 additions & 1 deletion clean/dx12/tests/native_helpers_check.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
sys.path.insert(0, str(DX12))
import build_dx12 # noqa: E402

ROCM = os.environ.get("ROCM_PATH", r"C:\Program Files\AMD\ROCm\7.2")
ROCM = r"C:\Program Files\AMD\ROCm\7.2" # the official HIP SDK (clean/runner/sdk.py), never ROCM_PATH
GUARD = 16
POISON = np.uint32(0xa5c31f7b)

Expand Down Expand Up @@ -250,14 +250,17 @@ def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--build", required=True, type=Path, help="verified HIP reference build containing frame.co")
ap.add_argument("--out", required=True, type=Path, help="private owned output directory")
from clean.runner import sdk # the HIP SDK policy: --rocm, --force-sdk
ap.add_argument("--rocm", default=ROCM)
sdk.add_force_argument(ap)
ap.add_argument("--n", default=65539, type=int)
ap.add_argument("--seed", default=281, type=int)
phase = ap.add_mutually_exclusive_group()
phase.add_argument("--build-only", action="store_true", help="compile only, no GPU execution")
phase.add_argument("--run-only", action="store_true", help="run existing compiled artifacts; no builds inside GPU lock")
ap.add_argument("--verify-mutation", action="store_true", help="also run an intentionally corrupted HLSL candidate")
args = ap.parse_args()
sdk.apply(args) # --rocm: an official SDK, or a custom one with --force-sdk
if not 1 <= args.n < (1 << 24):
ap.error("--n must be in [1, 2^24)")
args.out = args.out.resolve()
Expand Down
7 changes: 5 additions & 2 deletions clean/dx12/tests/native_qualification.py
Original file line number Diff line number Diff line change
Expand Up @@ -234,13 +234,16 @@ def main(argv=None):
ap.add_argument("--native-build", help="standalone native bundle; --build remains the HIP reference")
ap.add_argument("--models", required=True)
ap.add_argument("--out", required=True, help="new evidence directory (never overwritten)")
ap.add_argument("--rocm", default=r"C:\Program Files\AMD\ROCm\7.2")
from clean.runner import sdk # the HIP SDK policy: --rocm, --force-sdk
ap.add_argument("--rocm", default="")
sdk.add_force_argument(ap)
ap.add_argument("--frames", type=int, default=8)
ap.add_argument("--include-4k", action="store_true", help="also qualify 1920x1080 -> 3840x2160 Performance geometry")
ap.add_argument("--probe-unused-capacity", action="store_true", help="also poison C capacity during the differential check")
ap.add_argument("--worker", action="store_true", help=argparse.SUPPRESS)
ap.add_argument("--skip-compare", action="store_true", help="diagnostic only: native process gate without differential run")
a = ap.parse_args(argv)
sdk.apply(a) # --rocm: an official SDK, or a custom one with --force-sdk
native_build = a.native_build or a.build
if a.frames < 4:
ap.error("at least four frames are needed to exercise the second reset")
Expand Down Expand Up @@ -269,7 +272,7 @@ def main(argv=None):
if not a.skip_compare:
cmd = [sys.executable, str(DX12 / "compare.py"), "--build", a.build, "--models", str(models),
"--candidate-build", native_build,
"--rocm", a.rocm, "--backend", "d3d12", "--kernels", "all", "--frames", str(a.frames),
"--rocm", a.rocm, *sdk.forward(a), "--backend", "d3d12", "--kernels", "all", "--frames", str(a.frames),
"--json", str(out / "compare.json"), "--trace", str(out / "compare-launches.txt")]
if a.include_4k:
cmd.append("--include-4k")
Expand Down
Loading
Loading