Run frontier MoE models on hardware you already own β pure C, zero deps, experts streamed from disk. Tiny engine, immense model. π¦
C
build(windows): add an opt-in native HIP DLL build
Kenneth-Javier Ortigoza6efd3c97271f
diff --git a/.gitignore b/.gitignoreindex 8ab39916..531748e8 100644--- a/.gitignore+++ b/.gitignore@@ -28,6 +28,10 @@ c/backend_loader.oc/coli_cuda.dllc/coli_cuda.libc/coli_cuda.exp+c/coli_hip.dll+c/coli_hip.lib+c/coli_hip.exp+c/coli_hip.pdbc/tests/test_*!c/tests/test_*.c!c/tests/test_*.cudiff --git a/GPU_BACKENDS.md b/GPU_BACKENDS.mdindex be421bfb..6fa400ca 100644--- a/GPU_BACKENDS.md+++ b/GPU_BACKENDS.md@@ -17,12 +17,90 @@ only β never `#ifdef __HIP__` (or CUDA-specific code) in `backend_cuda.cu`.|---|---|---|---|| CUDA (`CUDA=1`) | Linux x86-64 | CUDA toolkit (nvcc), `CUDA_HOME=/usr/local/cuda` default | `make -C c glm CUDA=1 [CUDA_ARCH=native\|sm_XX]` || HIP (`HIP=1`) | Linux x86-64 | ROCm (hipcc), `ROCM_HOME=/opt/rocm` default; tested on ROCm 7.2 | `make -C c glm HIP=1 [HIP_ARCH=native\|gfxXXXX]` |+| HIP DLL (`HIP_DLL=1`) β **experimental, build only** | Windows x86-64 | HIP SDK (hipcc) + a compatible MSVC x64 host toolchain; `HIP_SDK_ROOT` from `HIP_PATH` | `make -C c hip-dll HIP_DLL=1 HIP_SDK_ROOT=<sdk-root> HIP_ARCH=gfxNNNN` β `c/coli_hip.dll` |`CUDA=1` and `HIP=1` are mutually exclusive and both opt-in: the default build-remains pure, dependency-free CPU. Both are refused on non-Linux with an early-`$(error)`. `*_ARCH=native` targets the local GPU; pass an explicit arch when-distributing or on machines with an unsupported iGPU visible to the runtime-(and mask iGPUs at runtime with `HIP_VISIBLE_DEVICES=<ordinal>` on ROCm).+remains pure, dependency-free CPU. Both are **directly linked** paths and remain+Linux-only, refused elsewhere with an early `$(error)`. The Windows HIP path is+selected separately as `HIP_DLL=1` and does not go through `HIP=1`; on Windows+`CUDA_DLL=1` and `HIP_DLL=1` are likewise mutually exclusive. `*_ARCH=native`+targets the local GPU; pass an explicit arch when distributing or on machines+with an unsupported iGPU visible to the runtime (and mask iGPUs at runtime with+`HIP_VISIBLE_DEVICES=<ordinal>` on ROCm). On Windows `HIP_ARCH` **must** be an+explicit `gfxNNNN` β see below.++### Windows HIP DLL (experimental)++Mirrors the Windows CUDA split: MinGW gcc cannot compile `.cu`, and Windows+hipcc targets the MSVC ABI, so the backend is built into a standalone+`coli_hip.dll` instead of being linked into the host. The same+`c/backend_cuda.cu` and the same `coli_cuda_*` ABI the Linux HIP path already+reuses are used unchanged.++**Build support only.** The host does not yet load `coli_hip.dll` at runtime β+see [Limitations](#windows-hip-limitations).++The two halves are built separately.++*Host build mode* β prepares the host for the DLL split. Needs **no HIP SDK**+and **no `HIP_ARCH`**, because it only compiles `c/backend_loader.c` and links+`colibri.exe`; `amdhip64` is never linked into the host:++```sh+make -C c colibri.exe HIP_DLL=1+```++*Backend DLL* β requires a selected SDK and an explicit architecture:++```sh+make -C c hip-dll \+ HIP_DLL=1 \+ HIP_SDK_ROOT=<sdk-root> \+ HIP_ARCH=gfxNNNN+```++It produces `c/coli_hip.dll`; the linker may also emit `c/coli_hip.lib` (and+`.exp`/`.pdb` on toolchains that generate them). All are ignored by git and+removed by `make -C c clean`.++#### SDK selection variables++No install location is hardcoded. `HIP_SDK_ROOT` defaults from the `HIP_PATH`+environment variable the Windows HIP SDK installer sets; pass it explicitly for+a relocated or source-built SDK (for example from `rocm-sdk path --root`). Every+component can be overridden independently, because packaged layouts do not all+keep runtime, development and device files under one root:++| variable | default | selects |+|---|---|---|+| `HIP_SDK_ROOT` | `$(HIP_PATH)` | SDK root (`--hip-path`) |+| `HIP_BIN_DIR` | `$(HIP_SDK_ROOT)/bin` | directory holding `hipcc` |+| `HIP_INCLUDE_DIR` | `$(HIP_SDK_ROOT)/include` | headers (`-I`) |+| `HIP_LIB_DIR` | `$(HIP_SDK_ROOT)/lib` | `amdhip64` import library (`-L`) |+| `HIP_DEVICE_LIB_PATH` | `$(HIP_SDK_ROOT)/lib/llvm/amdgcn/bitcode` | device bitcode (`--rocm-device-lib-path`) |+| `HIPCC` | `$(HIP_BIN_DIR)/hipcc.exe` | compiler driver |+| `HIP_ARCH` | *(none β must be explicit)* | `--offload-arch=` |++`--hip-path` pins the SDK deliberately: a machine can carry both a+driver-installed HIP SDK and a source-built one, and clang otherwise injects the+former on its own, which silently mixes headers from one tree with the import+library and device bitcode from the other.++`HIP_ARCH=native` is rejected on Windows: `rocm_agent_enumerator` is not+available there, so there is nothing to resolve `native` against.++<a id="windows-hip-limitations"></a>+#### Limitations++- **Build support only.** This documents compilation, not completed runtime+ integration. The host cannot yet load `coli_hip.dll`; runtime DLL-name+ selection is deferred.+- Deterministic `amdhip64_7.dll` runtime selection is **not** part of this+ build slice.+- There is **no hosted CI coverage** for the Windows HIP build β no hosted+ runner provides a Windows HIP toolchain. `engine-hip-syntax` covers the Linux+ HIP compile only.+- Validation therefore requires a suitable local Windows AMD/HIP environment.## Runtime configuration (identical for both vendors)diff --git a/c/Makefile b/c/Makefileindex 56390905..7b6fb6d1 100644--- a/c/Makefile+++ b/c/Makefile@@ -216,8 +216,46 @@ endif# like compat.h does for Windows). HIP_ARCH=native targets the GPU in this# machine; set an explicit arch (e.g. HIP_ARCH=gfx1201) when distributing.HIP ?= 0+# HIP_DLL=1 is the AMD sibling of CUDA_DLL=1 (Windows only): MinGW gcc cannot+# compile .cu and hipcc on Windows targets the MSVC ABI, so the backend goes+# into a standalone coli_hip.dll and the host loads it at runtime β exactly the+# split the CUDA path already uses. The host never links amdhip64. Same single+# source and same coli_cuda_* ABI the Linux HIP path reuses, so the host keeps+# -DCOLI_CUDA; -DCOLI_HIP_DLL only records WHICH DLL it will look for.+HIP_DLL ?= 0+ifneq ($(IS_WIN),)+# One runtime DLL per host binary: the loader resolves a single hardcoded DLL+# name, so a host built for both would silently be a host built for whichever+# arm ran last. Checked FIRST, before the arch and flag guards below, so the+# contradiction is reported instead of whichever downstream check trips.+ifeq ($(CUDA_DLL)$(HIP_DLL),11)+$(error choose CUDA_DLL=1 or HIP_DLL=1, not both)+endif+endifROCM_HOME ?= /opt/rocm+ifneq ($(IS_WIN),)+# --- Windows HIP SDK contract (HIP_DLL only; the Linux ROCM_HOME contract+# above is untouched) ---+# NOTHING here may hardcode an install location: HIP_PATH is the variable the+# official Windows HIP SDK installer sets, and a source-built or relocated SDK+# is selected with HIP_SDK_ROOT=<path> (e.g. from `rocm-sdk path --root`).+# Backslashes become forward slashes so the value survives the shell.+#+# Every component is separately overridable because packaged ROCm layouts do+# not all keep runtime, development and device files under one root:+# HIP_SDK_ROOT SDK root (--hip-path)+# HIP_INCLUDE_DIR headers (-I)+# HIP_LIB_DIR amdhip64.lib import lib (-L)+# HIP_DEVICE_LIB_PATH amdgcn device bitcode (--rocm-device-lib-path)+HIP_SDK_ROOT ?= $(subst \,/,$(HIP_PATH))+HIP_BIN_DIR ?= $(HIP_SDK_ROOT)/bin+HIP_INCLUDE_DIR ?= $(HIP_SDK_ROOT)/include+HIP_LIB_DIR ?= $(HIP_SDK_ROOT)/lib+HIP_DEVICE_LIB_PATH ?= $(HIP_SDK_ROOT)/lib/llvm/amdgcn/bitcode+HIPCC ?= $(HIP_BIN_DIR)/hipcc.exe+elseHIPCC ?= $(ROCM_HOME)/bin/hipcc+endifHIP_ARCH ?= native# HIP_ARCH accepts a list (space- or comma-separated, e.g. "gfx906 gfx1030")# to fat-bundle several targets into one binary; COLI_GPUS picks at runtime.@@ -234,7 +272,48 @@ $(error HIP_ARCH=native but rocm_agent_enumerator found no GPUs; set HIP_ARCH=gfendifendifendif+# Guards for the Windows HIP path, active ONLY when the hip-dll TARGET is+# requested β never for HIP_DLL=1 alone. HIP_DLL=1 selects the host arm, which+# compiles backend_loader.c and links colibri.exe against no HIP library and no+# SDK header: demanding an SDK there blocks a build that needs nothing from one+# (and HIP_PATH is not visible in every shell, e.g. an MSYS2 login shell).+# The default CPU build must never depend on a HIP path either.+#+# Only the string checks live here. Existence checks (hipcc, headers, import+# library, device bitcode) run in the hip-dll recipe instead. The stock Windows+# HIP SDK location may contain spaces, and $(wildcard) splits its argument on+# them, so a parse-time $(wildcard) check can incorrectly report a valid+# installation as missing. The recipe's shell tests are quoted and handle+# spaces correctly.+ifneq ($(IS_WIN),)+HIP_DLL_TARGET_REQUESTED := $(filter hip-dll,$(MAKECMDGOALS))+ifneq ($(HIP_DLL_TARGET_REQUESTED),)+ifeq ($(strip $(HIP_SDK_ROOT)),)+$(error Windows HIP build: no HIP SDK selected. Set HIP_PATH, or pass HIP_SDK_ROOT=<path> (e.g. from `rocm-sdk path --root`))+endif+# Windows has no rocm_agent_enumerator to resolve `native` against, and the+# enumerator branch above is HIP=1-only, so an unset HIP_ARCH would reach hipcc+# as --offload-arch=native and fail deep inside the compiler. Demand the arch+# here, where the cause is still visible.+ifeq ($(strip $(HIP_ARCH)),native)+$(error Windows HIP build: set an explicit HIP_ARCH=gfxNNNN (rocm_agent_enumerator is not available here), e.g. HIP_ARCH=gfx1151)+endif+ifeq ($(strip $(HIP_ARCH)),)+$(error Windows HIP build: HIP_ARCH is empty; set HIP_ARCH=gfxNNNN, e.g. HIP_ARCH=gfx1151)+endif+endif+endif+ifneq ($(IS_WIN),)+# No -fPIE on Windows: it is there for the Linux PIE link of backend_cuda.o into+# the gcc engine (the readelf guard in ci.yml exists because dropping it made+# that link fail), and it is meaningless for a PE DLL MinGW never links against.+# -Wall/-Wextra DO carry over unchanged β hipcc is clang and takes GCC-style+# warning flags directly. nvcc's -Xcompiler=-W3 workaround above is specific to+# nvcc driving cl.exe as its host compiler and must NOT be copied here.+HIPCCFLAGS ?= -O3 -std=c++17 -x hip $(foreach a,$(HIP_ARCH),--offload-arch=$(a)) -Wall -Wextra+elseHIPCCFLAGS ?= -O3 -std=c++17 -x hip $(foreach a,$(HIP_ARCH),--offload-arch=$(a)) -Wall -Wextra -fPIE+endifGPUCC = $(NVCC)GPUFLAGS = $(NVCCFLAGS)GPUCC_NAME = nvcc (set CUDA_HOME or NVCC)@@ -268,12 +347,21 @@ ifneq (,$(LINUX))TEST_BINS += tests/test_uring$(EXE)endif-# Windows CUDA DLL path: host links the loader, NOT cudart.+# Windows CUDA/HIP DLL path: host links the loader, NOT cudart or amdhip64.+# (CUDA_DLL/HIP_DLL mutual exclusion is enforced at the HIP_DLL declaration.)ifneq ($(IS_WIN),)ifeq ($(CUDA_DLL),1)CFLAGS += -DCOLI_CUDACUDA_OBJ = backend_loader.oendif+ifeq ($(HIP_DLL),1)+# -DCOLI_CUDA keeps the existing shared GPU ABI (Linux HIP already reuses the+# coli_cuda_* surface); -DCOLI_HIP_DLL is only the build discriminator, so a+# later phase can point the loader at coli_hip.dll. No LDFLAGS change: linking+# amdhip64 into the MinGW host is exactly what the DLL split exists to avoid.+CFLAGS += -DCOLI_CUDA -DCOLI_HIP_DLL+CUDA_OBJ = backend_loader.o+endifendif# Linux CUDA direct-link path (unchanged).@@ -379,7 +467,7 @@ glm: colibri$(EXE)# rewrite it ONLY when they change (evaluated here at parse time, so the file's# timestamp moves exactly when the config moves). The binary and CUDA/loader objects depend# on it, so they relink on a config change and stay put otherwise. (#306)-BUILD_CONFIG := $(CC)|$(CFLAGS)|$(LDFLAGS)|CUDA=$(CUDA)|CUDA_DLL=$(CUDA_DLL)|ARCH=$(ARCH)|CUDA_ARCH=$(CUDA_ARCH)|METAL=$(METAL)|HIP=$(HIP)|HIP_ARCH=$(HIP_ARCH)|VK=$(VK)+BUILD_CONFIG := $(CC)|$(CFLAGS)|$(LDFLAGS)|CUDA=$(CUDA)|CUDA_DLL=$(CUDA_DLL)|ARCH=$(ARCH)|CUDA_ARCH=$(CUDA_ARCH)|METAL=$(METAL)|HIP=$(HIP)|HIP_DLL=$(HIP_DLL)|HIP_ARCH=$(HIP_ARCH)|VK=$(VK)BUILD_CONFIG_OLD := $(shell cat .build-config 2>/dev/null)ifneq "$(BUILD_CONFIG)" "$(BUILD_CONFIG_OLD)"# $(file ...) writes via make's own primitive (GNU Make >= 4.0, 2013), NOT by@@ -418,6 +506,42 @@ cuda-dll: backend_cuda.cu backend_cuda.h-L"$(CUDA_HOME)/lib/x64" -lcudart \backend_cuda.cu -o coli_cuda.dll+# Windows HIP DLL: the AMD sibling of cuda-dll above. hipcc compiles the SAME+# backend_cuda.cu (through backend_gpu_compat.h) into coli_hip.dll, exporting+# the same coli_cuda_* surface β which is why COLI_CUDA_BUILDING_DLL, and not a+# new HIP-specific export macro, is the correct switch here. No cl.exe guard+# like cuda-dll's: hipcc brings its own clang host pass, but it still needs the+# MSVC linker and Windows SDK, so run this from a vcvars64 shell.+#+# --hip-path pins the SDK: a machine can carry BOTH a driver-installed HIP SDK+# and a source-built one, and clang injects the driver install via -idirafter on+# its own. Without --hip-path the headers came from one tree while -L/-lamdhip64+# and the device bitcode came from the other β the mismatch that made+# <rocwmma/rocwmma.hpp> unfindable even though the selected SDK ships it.+# --hip-path alone resolves both hip/ and rocwmma/ from the selected root;+# -I"$(HIP_INCLUDE_DIR)" is kept because it takes precedence (verified) and is+# the override point for layouts that split headers off the SDK root.+# --rocm-device-lib-path is kept for determinism: clang can otherwise find the+# bitcode relative to its own resource dir, which is a guess, not a contract.+# Every SDK-derived path is quoted so an install under "C:\Program Files\..."+# survives. No path is hardcoded β see the HIP SDK contract above.+#+# make hip-dll HIP_DLL=1 HIP_SDK_ROOT=<sdk> HIP_ARCH=gfx1151+hip-dll: backend_cuda.cu backend_cuda.h backend_gpu_compat.h+ @test -x "$(HIPCC)" || command -v "$(HIPCC)" >/dev/null 2>&1 || { echo "hipcc not found at \"$(HIPCC)\": set HIP_SDK_ROOT=<path>, HIP_BIN_DIR=<path> or HIPCC=<path>" >&2; exit 1; }+ @test -d "$(HIP_INCLUDE_DIR)" || { echo "HIP include dir not found: \"$(HIP_INCLUDE_DIR)\" β set HIP_INCLUDE_DIR=<path>" >&2; exit 1; }+ @test -f "$(HIP_INCLUDE_DIR)/hip/hip_runtime.h" || { echo "hip/hip_runtime.h missing under \"$(HIP_INCLUDE_DIR)\" β set HIP_INCLUDE_DIR=<path>" >&2; exit 1; }+ @case "$(HIPCCFLAGS)" in *COLI_HIP_NO_WMMA*) ;; *) test -f "$(HIP_INCLUDE_DIR)/rocwmma/rocwmma.hpp" || { echo "rocwmma/rocwmma.hpp missing under \"$(HIP_INCLUDE_DIR)\": install the rocWMMA component, or set HIP_INCLUDE_DIR=<path>" >&2; exit 1; } ;; esac+ @test -d "$(HIP_LIB_DIR)" || { echo "HIP lib dir not found: \"$(HIP_LIB_DIR)\" β set HIP_LIB_DIR=<path>" >&2; exit 1; }+ @test -f "$(HIP_LIB_DIR)/amdhip64.lib" || { echo "amdhip64.lib missing under \"$(HIP_LIB_DIR)\" β set HIP_LIB_DIR=<path>" >&2; exit 1; }+ @test -d "$(HIP_DEVICE_LIB_PATH)" || { echo "device bitcode dir not found: \"$(HIP_DEVICE_LIB_PATH)\" β set HIP_DEVICE_LIB_PATH=<path>" >&2; exit 1; }+ "$(HIPCC)" $(HIPCCFLAGS) -shared -DCOLI_CUDA_BUILDING_DLL \+ --hip-path="$(HIP_SDK_ROOT)" \+ -I"$(HIP_INCLUDE_DIR)" \+ --rocm-device-lib-path="$(HIP_DEVICE_LIB_PATH)" \+ -L"$(HIP_LIB_DIR)" -lamdhip64 \+ backend_cuda.cu -o coli_hip.dll+backend_cuda_ink.o: backend_cuda_ink.cu backend_cuda_ink.h .build-config@command -v "$(NVCC)" >/dev/null 2>&1 || { echo "nvcc not found: set CUDA_HOME or NVCC" >&2; exit 1; }"$(NVCC)" $(NVCCFLAGS) -c backend_cuda_ink.cu -o $@@@ -761,7 +885,7 @@ clean:bench: iobench$(EXE)@if [ -n "$(ARGS)" ]; then ./iobench$(EXE) $(ARGS); else echo "built iobench$(EXE) β run: ./iobench$(EXE) <file> <MB> <iters> <threads> <direct 0|1>"; fi-.PHONY: all colibri glm iq3 rans fuzz-rans cuda-test hip-test gpu-compile cuda-bench cuda-dll portable test-c test-python test check clean install uninstall bench+.PHONY: all colibri glm iq3 rans fuzz-rans cuda-test hip-test gpu-compile cuda-bench cuda-dll hip-dll portable test-c test-python test check clean install uninstall benchtests/test_kv_prefix$(EXE): tests/test_kv_prefix.c kv_prefix.h$(CC) $(CFLAGS) tests/test_kv_prefix.c -o tests/test_kv_prefix$(EXE) $(LDFLAGS)diff --git a/c/backend_cuda.cu b/c/backend_cuda.cuindex 2efc557c..9e16224e 100644--- a/c/backend_cuda.cu+++ b/c/backend_cuda.cu@@ -781,7 +781,17 @@ extern "C" int coli_cuda_init(const int *devices, int count) {{const char *t = std::getenv("TEMP");struct stat st;+ /* Same test on both hosts; only the CRT spelling differs. The MSVC CRT+ * (Windows hipcc's host pass) has no S_ISDIR and no unsetenv β it spells+ * the directory bit _S_IFDIR/_S_IFMT and clears a variable by assigning+ * an empty value. This is an OS/CRT difference, NOT a vendor one, so it+ * stays a _WIN32 branch and adds no CUDA-vs-HIP conditional. */+#ifdef _WIN32+ if (t && *t && (stat(t, &st) != 0 ||+ (st.st_mode & _S_IFMT) != _S_IFDIR)) _putenv_s("TEMP", "");+#elseif (t && *t && (stat(t, &st) != 0 || !S_ISDIR(st.st_mode))) unsetenv("TEMP");+#endif}#endifint available = 0;diff --git a/c/tools/clean.py b/c/tools/clean.pyindex 463618fb..1fd23bcb 100644--- a/c/tools/clean.py+++ b/c/tools/clean.py@@ -18,6 +18,8 @@ FILES = ["backend_cuda_bench", "backend_cuda_bench.exe","backend_metal.o", "backend_metal_test","coli_cuda.dll", "coli_cuda.lib", "coli_cuda.exp",+ # hipcc emits an import library, export file and PDB alongside the DLL.+ "coli_hip.dll", "coli_hip.lib", "coli_hip.exp", "coli_hip.pdb",]# Test binaries match this pattern. Only remove executables (.exe on Windows,# no extension on Unix) β never .c or .py source files.diff --git a/docs/windows.md b/docs/windows.mdindex 43c54203..454c84d8 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -112,6 +112,7 @@ Size `CUDA_EXPERT_GB` so dense (~10 GB) + experts + working set stays under your## Reference: build flags & warmup+```sh# AVX-VNNI: Intel Alder Lake+ (and Meteor Lake+) CPUs have a 128-bit int8# dot-product instruction (VPDPBUSD) the engine can use for ~1.3x faster# quantized matmul. The x86-64-v3 default (portable AVX2) compiles it out;@@ -179,3 +180,76 @@ available.**Measured on a single RTX 5070 Ti + Core Ultra 9 (32 GB RAM):** CPU-only 0.63β CUDA attention+dense 0.72 β **1.07 tok/s** with the GPU-resident pipeline atdecode ([#273](https://github.com/JustVugg/colibri/issues/273), merged in #274).++## AMD GPU (experimental, build only)++The AMD sibling of the CUDA split above, and the same reasoning: MinGW gcc+cannot compile `.cu`, and Windows hipcc targets the MSVC ABI, so the backend is+built into a standalone `coli_hip.dll` rather than linked into the host. The+same `c/backend_cuda.cu` and the same `coli_cuda_*` ABI the Linux HIP path+already reuses are used unchanged β see [GPU_BACKENDS.md](../GPU_BACKENDS.md).++> **This is build support, not a working GPU tier yet.** The host does not load+> `coli_hip.dll` at runtime, so there is no end-to-end AMD GPU inference on+> Windows today. Building the DLL verifies that it compiles, exports and links;+> wiring it into the engine is separate follow-up work.++### What you need++| Piece | Why |+|---|---|+| Windows x86-64 | the target platform |+| A compatible **MSVC x64 host toolchain** | hipcc brings its own clang front end but still needs the MSVC linker and Windows SDK; build from a shell with the MSVC environment set (`vcvars64.bat`, or an "x64 Native Tools Command Prompt") |+| A **Windows HIP SDK** providing `hipcc`, the HIP headers, the `amdhip64` import library and the device bitcode | compiles and links the backend |+| Your GPU's **architecture name** (`gfxNNNN`) | must be stated explicitly β see below |++MinGW-w64 `make` and `gcc` from Β§0 are still what build the host.++### Build++Two halves, built separately. The host build needs **no HIP SDK at all** β it+only compiles `c/backend_loader.c` and links `colibri.exe`, and never links+`amdhip64`:++```powershell+# 1. Host build mode (no SDK, no HIP_ARCH needed):+make -C c colibri.exe HIP_DLL=1++# 2. The backend DLL, from a shell with the MSVC environment set:+make -C c hip-dll HIP_DLL=1 HIP_SDK_ROOT=<sdk-root> HIP_ARCH=gfxNNNN+```++`HIP_SDK_ROOT` defaults from the `HIP_PATH` environment variable the HIP SDK+installer sets, so it can be omitted when that is already correct. Pass it+explicitly for a relocated or source-built SDK β that is preferable to editing+your machine-wide `HIP_PATH`. Each component (`HIP_BIN_DIR`, `HIP_INCLUDE_DIR`,+`HIP_LIB_DIR`, `HIP_DEVICE_LIB_PATH`, `HIPCC`) can be overridden on its own for+split layouts; the full list is in+[GPU_BACKENDS.md](../GPU_BACKENDS.md#sdk-selection-variables).++Generated artifacts: `c/coli_hip.dll`, plus `c/coli_hip.lib` if the linker emits+an import library (and `.exp`/`.pdb` on toolchains that produce them). All are+git-ignored and removed by `make -C c clean`.++> **Validated on:** AMD Radeon 8060S (`gfx1151`) with a source-built HIP SDK and+> Visual Studio 2022 (MSVC 14.44). Other SDK versions and MSVC toolchains are+> expected to work but have not been exercised β there is **no hosted CI+> coverage** for this path, because no hosted runner ships a Windows HIP+> toolchain.++### AMD failure index++| Symptom | Cause | Fix |+|---|---|---|+| `choose CUDA_DLL=1 or HIP_DLL=1, not both` | both runtime-DLL modes selected; the host resolves one DLL name | pick one per build |+| `Windows HIP build: no HIP SDK selected` | `hip-dll` requested with neither `HIP_PATH` nor `HIP_SDK_ROOT` set (`HIP_PATH` is not visible in every shell β an MSYS2 login shell drops it) | pass `HIP_SDK_ROOT=<sdk-root>` |+| `Windows HIP build: HIP_ARCH is empty` | no architecture given | pass `HIP_ARCH=gfxNNNN` |+| `Windows HIP build: set an explicit HIP_ARCH=gfxNNNN` | `HIP_ARCH=native` on Windows; `rocm_agent_enumerator` does not exist there, so there is nothing to resolve `native` against | name the arch, e.g. `HIP_ARCH=gfx1151` |+| `hipcc not found at "..."` / `HIP include dir not found` / `amdhip64.lib missing under "..."` / `device bitcode dir not found` | the selected SDK root does not have the expected layout | fix `HIP_SDK_ROOT`, or override just the component named in the message (`HIP_INCLUDE_DIR`, `HIP_LIB_DIR`, `HIP_DEVICE_LIB_PATH`, `HIPCC`) |+| `rocwmma/rocwmma.hpp missing under "..."` | the SDK lacks the rocWMMA component | install it, or point `HIP_INCLUDE_DIR` at a tree that has it |+| A no-SDK error from a **host-only** build | none β the host build is SDK-independent by design | `make -C c colibri.exe HIP_DLL=1` needs no SDK and no `HIP_ARCH`; if you see an SDK error here, you asked for the `hip-dll` target |+| Built the DLL but the GPU never engages | expected today | runtime loading of `coli_hip.dll` is not implemented yet; the engine stays on the CPU path |++SDK paths containing spaces are supported β every SDK-derived path the recipe+passes to the compiler is quoted. If you supply one yourself, quote it:+`HIP_SDK_ROOT="<path with spaces>"`.