Skip to content

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/.gitignore
index 8ab39916..531748e8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,10 @@ c/backend_loader.o
c/coli_cuda.dll
c/coli_cuda.lib
c/coli_cuda.exp
+c/coli_hip.dll
+c/coli_hip.lib
+c/coli_hip.exp
+c/coli_hip.pdb
c/tests/test_*
!c/tests/test_*.c
!c/tests/test_*.cu
diff --git a/GPU_BACKENDS.md b/GPU_BACKENDS.md
index 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/Makefile
index 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
+endif
ROCM_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
+else
HIPCC ?= $(ROCM_HOME)/bin/hipcc
+endif
HIP_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=gf
endif
endif
endif
+# 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
+else
HIPCCFLAGS ?= -O3 -std=c++17 -x hip $(foreach a,$(HIP_ARCH),--offload-arch=$(a)) -Wall -Wextra -fPIE
+endif
GPUCC = $(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_CUDA
CUDA_OBJ = backend_loader.o
endif
+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
+endif
endif
# 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 bench
tests/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.cu
index 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", "");
+#else
if (t && *t && (stat(t, &st) != 0 || !S_ISDIR(st.st_mode))) unsetenv("TEMP");
+#endif
}
#endif
int available = 0;
diff --git a/c/tools/clean.py b/c/tools/clean.py
index 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.md
index 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 at
decode ([#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>"`.