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
38.8 KB
Raw Blame
#!/usr/bin/env python3
"""Hardware detection for the one-step setup (`coli setup`, the MCP server).

What it answers, and nothing more: how much RAM there is, how much disk is free
where the model would go, which CPU features the engine can use, and which GPUs
are there (Vulkan devices with their type and memory, NVIDIA cards through
nvidia-smi with their compute capability). It never changes anything on the
machine.

Every probe is split in two: a function that runs a command or a system call,
and a pure parser that turns its output into data. The parsers are what the
tests exercise with mocked hardware (tests/test_setup_hw.py); the probes are
thin and fail closed (a probe that cannot run reports nothing, never a guess).

Vulkan is probed through the loader itself with ctypes, in a child process: the
same vkEnumeratePhysicalDevices the engine calls, the same device ranking
(discrete > integrated > virtual > other > CPU), and the device-local heap
budget from VK_EXT_memory_budget when the driver has it. A child process,
because a broken driver can crash the process that loads it. When the loader
cannot be loaded, `vulkaninfo --summary` is parsed instead (names and types,
no memory figures).
"""
import ctypes
import glob
import json
import os
import platform
import posixpath
import re
import shutil
import struct
import subprocess
import sys

HERE = os.path.dirname(os.path.realpath(__file__))
GB = 1_000_000_000


def host_os():
    """The OS whose conventions decide which probes apply (WSL driver search,
    no Vulkan on macOS). Patchable, so tests model any OS on any host."""
    return sys.platform

# ---------------------------------------------------------------- memory


def memory_from_meminfo(text):
    """{"total": bytes, "available": bytes} from /proc/meminfo text.

    Missing lines come back as None rather than 0: zero would read as a
    measurement ("no RAM free") when it is only an absence."""
    out = {"total": None, "available": None}
    for key, field in (("MemTotal", "total"), ("MemAvailable", "available")):
        match = re.search(rf"^{key}:\s+(\d+)\s+kB\s*$", text or "", re.M)
        if match:
            out[field] = int(match.group(1)) * 1024
    return out


def memory_from_windows_status(total_phys, avail_phys, avail_pagefile=None):
    """GlobalMemoryStatusEx figures. Available is the smaller of free physical
    memory and the commit Windows can still grant (resource_plan's rule, #1375)."""
    available = avail_phys
    if avail_pagefile and 0 < avail_pagefile < avail_phys:
        available = avail_pagefile
    return {"total": int(total_phys) if total_phys else None,
            "available": int(available) if available else None}


def memory_from_darwin(memsize_text, vm_stat_text=""):
    """hw.memsize plus the reclaimable pages of vm_stat (free, inactive,
    speculative, purgeable), the engine's own definition of available."""
    try:
        total = int((memsize_text or "").strip())
    except ValueError:
        total = None
    page_match = re.search(r"page size of (\d+) bytes", vm_stat_text or "")
    page = int(page_match.group(1)) if page_match else 16384
    pages = 0
    for key in ("Pages free", "Pages inactive", "Pages speculative", "Pages purgeable"):
        match = re.search(rf"{key}:\s+(\d+)\.", vm_stat_text or "")
        if match:
            pages += int(match.group(1))
    return {"total": total, "available": pages * page if pages else None}


def _windows_memory():
    try:
        from resource_plan import WINDOWS_MEMORYSTATUSEX_FIELDS

        class MEMORYSTATUSEX(ctypes.Structure):
            _fields_ = [(name, getattr(ctypes, kind))
                        for name, kind in WINDOWS_MEMORYSTATUSEX_FIELDS]

        stat = MEMORYSTATUSEX(dwLength=ctypes.sizeof(MEMORYSTATUSEX))
        kernel32 = ctypes.windll.kernel32
        kernel32.GlobalMemoryStatusEx.argtypes = [ctypes.c_void_p]
        kernel32.GlobalMemoryStatusEx.restype = ctypes.c_int
        if kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
            return memory_from_windows_status(stat.ullTotalPhys, stat.ullAvailPhys,
                                              stat.ullAvailPageFile)
    except (OSError, AttributeError, ImportError, ValueError):
        pass
    return {"total": None, "available": None}


def detect_memory():
    if sys.platform == "win32":
        return _windows_memory()
    if sys.platform == "darwin":
        return memory_from_darwin(_run(["sysctl", "-n", "hw.memsize"]), _run(["vm_stat"]))
    try:
        with open("/proc/meminfo", encoding="ascii", errors="replace") as handle:
            mem = memory_from_meminfo(handle.read(256 * 1024))
    except OSError:
        mem = {"total": None, "available": None}
    # A container limit is what kills the process, whatever the host has free:
    # resource_plan already knows how to read it.
    try:
        from resource_plan import memory_available
        budget = memory_available()
        if budget is not None:
            mem["available"] = budget if mem["available"] is None else min(mem["available"], budget)
    except Exception:  # a malformed cgroup is reported by `coli plan`, not here
        pass
    return mem


# ---------------------------------------------------------------- CPU

#: The flags that change which kernels the engine compiles in (ARCH=native).
CPU_FEATURES_OF_INTEREST = (
    "avx2", "fma", "f16c", "avx_vnni", "avx512f", "avx512bw", "avx512_vnni",
    "avx512_bf16", "amx_tile", "asimd", "asimddp", "i8mm", "sve",
)


def cpu_from_cpuinfo(text):
    """Model name and feature flags from /proc/cpuinfo (x86 `flags`, Arm `Features`)."""
    name = None
    flags = set()
    for line in (text or "").splitlines():
        key, sep, value = line.partition(":")
        if not sep:
            continue
        key = key.strip().lower()
        if key in ("model name", "hardware", "cpu model") and not name:
            name = value.strip() or None
        elif key in ("flags", "features") and not flags:
            flags = set(value.split())
    # Linux spells the VNNI flags avx512_vnni / avx_vnni; some kernels avx512vnni.
    if "avx512vnni" in flags:
        flags.add("avx512_vnni")
    features = [f for f in CPU_FEATURES_OF_INTEREST if f in flags]
    return {"name": name, "features": features}


#: IsProcessorFeaturePresent codes (winnt.h).
WINDOWS_PF = {"avx2": 40, "avx512f": 41, "asimd": 43}


def cpu_features_from_windows(is_present):
    """`is_present(code) -> bool` is kernel32.IsProcessorFeaturePresent."""
    return [name for name, code in WINDOWS_PF.items() if is_present(code)]


def _windows_cpu():
    name, features = None, []
    try:
        import winreg
        key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE,
                             r"HARDWARE\DESCRIPTION\System\CentralProcessor\0")
        name = winreg.QueryValueEx(key, "ProcessorNameString")[0].strip()
    except (OSError, ImportError):
        pass
    try:
        k32 = ctypes.windll.kernel32
        k32.IsProcessorFeaturePresent.argtypes = [ctypes.c_uint]
        k32.IsProcessorFeaturePresent.restype = ctypes.c_int
        features = cpu_features_from_windows(lambda code: bool(k32.IsProcessorFeaturePresent(code)))
    except (OSError, AttributeError):
        pass
    return {"name": name, "features": features}


def detect_cpu():
    if sys.platform == "win32":
        cpu = _windows_cpu()
    elif sys.platform == "darwin":
        name = _run(["sysctl", "-n", "machdep.cpu.brand_string"]).strip() or None
        feats = _run(["sysctl", "-n", "machdep.cpu.features", "machdep.cpu.leaf7_features"]).lower().split()
        flags = set(feats)
        if platform.machine().lower() in ("arm64", "aarch64"):
            flags.update({"asimd", "asimddp"})
        cpu = {"name": name, "features": [f for f in CPU_FEATURES_OF_INTEREST if f in flags]}
    else:
        try:
            with open("/proc/cpuinfo", encoding="utf-8", errors="replace") as handle:
                cpu = cpu_from_cpuinfo(handle.read(1 << 20))
        except OSError:
            cpu = {"name": None, "features": []}
    cpu["arch"] = platform.machine().lower() or None
    cpu["logical_cores"] = os.cpu_count()
    try:
        from resource_plan import physical_cpu_count
        cpu["physical_cores"] = physical_cpu_count()
    except Exception:
        cpu["physical_cores"] = None
    return cpu


# ---------------------------------------------------------------- OS / WSL


def is_wsl(osrelease_text=None, environ=None):
    environ = os.environ if environ is None else environ
    if environ.get("WSL_DISTRO_NAME") or environ.get("WSL_INTEROP"):
        return True
    if osrelease_text is None:
        try:
            with open("/proc/sys/kernel/osrelease", encoding="ascii", errors="replace") as handle:
                osrelease_text = handle.read(4096)
        except OSError:
            return False
    lowered = osrelease_text.lower()
    return "microsoft" in lowered or "wsl" in lowered


def os_release(text=None):
    """ID and ID_LIKE from /etc/os-release, for the package hints."""
    if text is None:
        try:
            with open("/etc/os-release", encoding="utf-8", errors="replace") as handle:
                text = handle.read(65536)
        except OSError:
            return {}
    out = {}
    for line in text.splitlines():
        key, sep, value = line.partition("=")
        if sep and key in ("ID", "ID_LIKE", "PRETTY_NAME", "VERSION_ID"):
            out[key] = value.strip().strip('"')
    return out


def detect_os():
    info = {"platform": sys.platform, "machine": platform.machine().lower(),
            "wsl": sys.platform.startswith("linux") and is_wsl()}
    if sys.platform.startswith("linux"):
        info.update({k.lower(): v for k, v in os_release().items()})
    elif sys.platform == "win32":
        info["pretty_name"] = f"Windows {platform.release()}"
    elif sys.platform == "darwin":
        info["pretty_name"] = f"macOS {platform.mac_ver()[0]}"
    return info


# ---------------------------------------------------------------- disk


def existing_ancestor(path):
    path = os.path.abspath(os.path.expanduser(path))
    while not os.path.exists(path):
        parent = os.path.dirname(path)
        if parent == path:
            break
        path = parent
    return path


def disk_free(path):
    try:
        return shutil.disk_usage(existing_ancestor(path)).free
    except OSError:
        return None


def path_warnings(path, wsl):
    """Advice about where a model lives; the engine streams it, so it matters.

    The WSL check is about a Linux path, so it is normalized with POSIX rules
    whatever Python runs it: os.path on Windows would turn /mnt/c/x into
    C:\\mnt\\c\\x and the check would silently pass everything."""
    warnings = []
    if not wsl:
        return warnings
    expanded = os.path.expanduser(path)
    if not expanded.startswith("/"):
        expanded = posixpath.join(os.getcwd(), expanded)
    absolute = posixpath.normpath(expanded)
    if re.match(r"^/mnt/[a-zA-Z](/|$)", absolute):
        warnings.append(
            f"{absolute} is a Windows drive seen from WSL: reading it is many times "
            "slower than the Linux disk, and the engine streams the model from it. "
            "Keep the model in the Linux home (for example ~/colibri-models).")
    return warnings


def fixed_drives_from_mask(mask, drive_type):
    """Drive roots from GetLogicalDrives' bitmask, kept when GetDriveTypeW says
    DRIVE_FIXED (3): no network shares, no removable sticks."""
    roots = []
    for index in range(26):
        if mask & (1 << index):
            root = f"{chr(ord('A') + index)}:\\"
            if drive_type(root) == 3:
                roots.append(root)
    return roots


def windows_fixed_drives():
    if sys.platform != "win32":
        return []
    try:
        k32 = ctypes.windll.kernel32
        k32.GetDriveTypeW.argtypes = [ctypes.c_wchar_p]
        k32.GetDriveTypeW.restype = ctypes.c_uint
        return fixed_drives_from_mask(k32.GetLogicalDrives(), k32.GetDriveTypeW)
    except (OSError, AttributeError):
        return []


# ---------------------------------------------------------------- NVIDIA

#: What the setup asks nvidia-smi, in this order. compute_cap is the card's CUDA
#: compute capability ("7.0" for a V100): which nvcc can build for the card
#: depends on it (setup_flow.choose_backend). pci.bus_id ties a row to the CUDA
#: driver's own device when compute_cap has to come from there.
NVIDIA_FIELDS = ("index", "name", "memory.total", "memory.free", "driver_version",
                 "compute_cap", "pci.bus_id")
#: The same without compute_cap: a driver that predates the field refuses the
#: whole query and prints no rows, so the setup asks again without it.
NVIDIA_FIELDS_NO_CC = tuple(f for f in NVIDIA_FIELDS if f != "compute_cap")


def nvidia_smi_query(fields=NVIDIA_FIELDS):
    return [f"--query-gpu={','.join(fields)}", "--format=csv,noheader,nounits"]


NVIDIA_SMI_QUERY = nvidia_smi_query()


def parse_nvidia_smi(text, fields=NVIDIA_FIELDS):
    """Rows of `nvidia-smi --query-gpu=<fields> --format=csv,noheader,nounits`
    (memory in MiB). A unified-memory part prints [N/A] for memory: that is
    None, not zero; so is a compute capability the driver does not report.
    Rows with fewer columns than `fields` (an older query) leave the missing
    ones None."""
    import csv
    gpus = []
    for row in csv.reader((text or "").splitlines()):
        row = [f.strip() for f in row]
        if len(row) < 4:
            continue
        values = dict(zip(fields, row))
        try:
            index = int(values["index"])
        except (KeyError, ValueError):
            continue

        def mib(value):
            try:
                return int(float(value)) * 1024 * 1024
            except (TypeError, ValueError):
                return None

        def known(value):
            return value if value and not value.startswith("[") else None

        gpus.append({"index": index, "name": values.get("name"),
                     "total_bytes": mib(values.get("memory.total")),
                     "free_bytes": mib(values.get("memory.free")),
                     "driver": known(values.get("driver_version")),
                     "compute_cap": compute_cap_text(values.get("compute_cap")),
                     "pci_bus_id": known(values.get("pci.bus_id"))})
    return gpus


def compute_cap_text(value):
    """A compute capability as "7.0", from nvidia-smi or the CUDA driver; None
    for [N/A], an empty field or anything that is not major.minor."""
    match = re.match(r"^\s*(\d+)\.(\d+)\s*$", value or "")
    return f"{int(match.group(1))}.{int(match.group(2))}" if match else None


def compute_cap_sm(value):
    """The number nvcc names an architecture by: "7.0" -> 70 (compute_70,
    sm_70), "12.0" -> 120, "10.3" -> 103. None when the capability is unknown."""
    text = compute_cap_text(value)
    if text is None:
        return None
    major, minor = text.split(".")
    return int(major) * 10 + int(minor)


def pci_bus_key(value):
    """nvidia-smi writes 00000000:01:00.0, the CUDA driver 0000:01:00.0: the
    same slot. (domain, bus, device, function) as integers, or None."""
    match = re.match(r"^\s*([0-9a-fA-F]+):([0-9a-fA-F]+):([0-9a-fA-F]+)\.([0-7])\s*$", value or "")
    return tuple(int(part, 16) for part in match.groups()) if match else None


def fill_compute_caps(gpus, cuda_devices):
    """Give each nvidia-smi row without a compute capability the one the CUDA
    driver reports for the same PCI slot. Rows that cannot be matched stay None:
    an unknown capability is not a guess."""
    by_slot = {pci_bus_key(d.get("pci_bus_id")): compute_cap_text(d.get("compute_cap"))
               for d in cuda_devices or []}
    by_slot.pop(None, None)
    for gpu in gpus:
        if gpu.get("compute_cap") is None:
            gpu["compute_cap"] = by_slot.get(pci_bus_key(gpu.get("pci_bus_id")))
    return gpus


def nvidia_smi_path():
    found = shutil.which("nvidia-smi")
    if found:
        return found
    for candidate in ("/usr/lib/wsl/lib/nvidia-smi",
                      r"C:\Windows\System32\nvidia-smi.exe"):
        if os.path.isfile(candidate):
            return candidate
    return None


def detect_nvidia():
    """The NVIDIA cards, each with its compute capability when anything can tell.

    First nvidia-smi with compute_cap. A driver that does not know that field
    refuses the whole query, so no rows means asking again without it; then
    (and for any card printed as [N/A]) the CUDA driver itself is asked, in a
    child process like the Vulkan probe, and its answer matched by PCI slot."""
    exe = nvidia_smi_path()
    if not exe:
        return []
    gpus = parse_nvidia_smi(_run([exe] + nvidia_smi_query(NVIDIA_FIELDS), timeout=10), NVIDIA_FIELDS)
    if not gpus:
        gpus = parse_nvidia_smi(_run([exe] + nvidia_smi_query(NVIDIA_FIELDS_NO_CC), timeout=10),
                                NVIDIA_FIELDS_NO_CC)
    if any(gpu.get("compute_cap") is None for gpu in gpus):
        probe = _probe_cuda_child()
        if probe:
            fill_compute_caps(gpus, probe.get("devices"))
    return gpus


def _cuda_driver_library():
    names = {"win32": ["nvcuda.dll"]}.get(sys.platform, ["libcuda.so.1", "libcuda.so"])
    for name in names:
        try:
            return ctypes.CDLL(name)
        except OSError:
            continue
    return None


def _cuda_probe_inprocess():
    """Compute capability and PCI slot of every device, from the CUDA driver
    API (the same driver the engine's CUDA runtime talks to)."""
    lib = _cuda_driver_library()
    if lib is None:
        return {"driver": False, "devices": []}
    c_int = ctypes.c_int
    if lib.cuInit(0) != 0:
        return {"driver": True, "devices": []}
    count = c_int(0)
    if lib.cuDeviceGetCount(ctypes.byref(count)) != 0:
        return {"driver": True, "devices": []}
    devices = []
    for ordinal in range(count.value):
        device = c_int(0)
        if lib.cuDeviceGet(ctypes.byref(device), ordinal) != 0:
            continue
        major, minor = c_int(0), c_int(0)
        # CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR = 75, _MINOR = 76 (cuda.h)
        lib.cuDeviceGetAttribute(ctypes.byref(major), 75, device)
        lib.cuDeviceGetAttribute(ctypes.byref(minor), 76, device)
        bus = ctypes.create_string_buffer(64)
        name = ctypes.create_string_buffer(256)
        lib.cuDeviceGetPCIBusId(bus, 64, device)
        lib.cuDeviceGetName(name, 256, device)
        devices.append({"name": name.value.decode("utf-8", "replace"),
                        "pci_bus_id": bus.value.decode("ascii", "replace"),
                        "compute_cap": f"{major.value}.{minor.value}" if major.value else None})
    return {"driver": True, "devices": devices}


def _probe_cuda_child(timeout=25):
    try:
        result = subprocess.run([sys.executable, os.path.join(HERE, "setup_hw.py"), "--cuda-probe"],
                                capture_output=True, text=True, timeout=timeout)
    except (OSError, subprocess.SubprocessError):
        return None
    for line in reversed(result.stdout.splitlines()):
        line = line.strip()
        if line.startswith("{"):
            try:
                return json.loads(line)
            except ValueError:
                return None
    return None


# ---------------------------------------------------------------- Vulkan

VK_DEVICE_TYPES = {0: "other", 1: "integrated", 2: "discrete", 3: "virtual", 4: "cpu"}
#: The engine's own ranking (backend_vulkan.c, coli_vk_init).
VK_TYPE_RANK = {"discrete": 4, "integrated": 3, "virtual": 2, "other": 1, "cpu": 0}
VK_VENDORS = {0x10DE: "NVIDIA", 0x1002: "AMD", 0x1022: "AMD", 0x8086: "Intel",
              0x13B5: "Arm", 0x5143: "Qualcomm", 0x106B: "Apple", 0x1414: "Microsoft",
              0x10005: "Mesa"}


def vk_version(value):
    return f"{value >> 22 & 0x7F}.{value >> 12 & 0x3FF}.{value & 0xFFF}"


def _vulkan_library():
    names = {"win32": ["vulkan-1.dll"],
             "darwin": ["libvulkan.1.dylib", "libMoltenVK.dylib"]}.get(
                 sys.platform, ["libvulkan.so.1", "libvulkan.so"])
    for name in names:
        try:
            return ctypes.CDLL(name)
        except OSError:
            continue
    return None


def _vk_probe_inprocess():
    """Enumerate Vulkan physical devices with the loader, as the engine does.

    Raw buffers and explicit offsets rather than full ctypes mirrors of the
    Vulkan structs: only the leading fields are read, and a buffer larger than
    the struct cannot be overrun by a newer driver. Offsets are the C layout on
    every 64-bit ABI colibri builds for."""
    lib = _vulkan_library()
    if lib is None:
        return {"loader": False, "devices": []}
    u32, vp = ctypes.c_uint32, ctypes.c_void_p

    lib.vkCreateInstance.argtypes = [vp, vp, ctypes.POINTER(vp)]
    lib.vkCreateInstance.restype = ctypes.c_int32
    lib.vkEnumeratePhysicalDevices.argtypes = [vp, ctypes.POINTER(u32), vp]
    lib.vkEnumeratePhysicalDevices.restype = ctypes.c_int32
    lib.vkGetPhysicalDeviceProperties.argtypes = [vp, vp]
    lib.vkGetPhysicalDeviceProperties.restype = None
    lib.vkGetPhysicalDeviceMemoryProperties.argtypes = [vp, vp]
    lib.vkGetPhysicalDeviceMemoryProperties.restype = None
    lib.vkEnumerateDeviceExtensionProperties.argtypes = [vp, ctypes.c_char_p, ctypes.POINTER(u32), vp]
    lib.vkEnumerateDeviceExtensionProperties.restype = ctypes.c_int32
    lib.vkDestroyInstance.argtypes = [vp, vp]
    lib.vkDestroyInstance.restype = None

    instance_version = 1 << 22  # 1.0
    if hasattr(lib, "vkEnumerateInstanceVersion"):
        lib.vkEnumerateInstanceVersion.argtypes = [ctypes.POINTER(u32)]
        lib.vkEnumerateInstanceVersion.restype = ctypes.c_int32
        value = u32(0)
        if lib.vkEnumerateInstanceVersion(ctypes.byref(value)) == 0:
            instance_version = value.value
    api = min(instance_version, (1 << 22) | (3 << 12))

    class AppInfo(ctypes.Structure):
        _fields_ = [("sType", u32), ("pNext", vp), ("pApplicationName", ctypes.c_char_p),
                    ("applicationVersion", u32), ("pEngineName", ctypes.c_char_p),
                    ("engineVersion", u32), ("apiVersion", u32)]

    class CreateInfo(ctypes.Structure):
        _fields_ = [("sType", u32), ("pNext", vp), ("flags", u32), ("pApplicationInfo", vp),
                    ("enabledLayerCount", u32), ("ppEnabledLayerNames", vp),
                    ("enabledExtensionCount", u32), ("ppEnabledExtensionNames", vp)]

    app = AppInfo(0, None, b"colibri-setup", 1, b"colibri", 1, api)
    info = CreateInfo(1, None, 0, ctypes.cast(ctypes.byref(app), vp), 0, None, 0, None)
    instance = vp()
    result = lib.vkCreateInstance(ctypes.byref(info), None, ctypes.byref(instance))
    if result != 0 or not instance:
        return {"loader": True, "instance_error": result, "devices": []}
    devices = []
    try:
        count = u32(0)
        lib.vkEnumeratePhysicalDevices(instance, ctypes.byref(count), None)
        handles = (vp * max(count.value, 1))()
        lib.vkEnumeratePhysicalDevices(instance, ctypes.byref(count), handles)
        props2 = None
        if api >= (1 << 22) | (1 << 12):
            props2 = getattr(lib, "vkGetPhysicalDeviceMemoryProperties2", None)
            if props2 is not None:
                props2.argtypes = [vp, vp]
                props2.restype = None
        for handle in handles[:count.value]:
            raw = (ctypes.c_ubyte * 2048)()
            lib.vkGetPhysicalDeviceProperties(handle, raw)
            props = bytes(raw)
            api_v, driver_v, vendor, device_id, dtype = struct.unpack_from("<5I", props, 0)
            name = props[20:276].split(b"\0", 1)[0].decode("utf-8", "replace")

            ext_count = u32(0)
            lib.vkEnumerateDeviceExtensionProperties(handle, None, ctypes.byref(ext_count), None)
            ext_raw = (ctypes.c_ubyte * (260 * max(ext_count.value, 1)))()
            lib.vkEnumerateDeviceExtensionProperties(handle, None, ctypes.byref(ext_count), ext_raw)
            ext_bytes = bytes(ext_raw)
            extensions = {ext_bytes[i * 260:i * 260 + 256].split(b"\0", 1)[0].decode("ascii", "replace")
                          for i in range(ext_count.value)}
            has_budget = "VK_EXT_memory_budget" in extensions and props2 is not None

            budget_raw = (ctypes.c_ubyte * 512)()
            if has_budget:
                mem2 = (ctypes.c_ubyte * 1024)()
                struct.pack_into("<I", budget_raw, 0, 1000237000)
                struct.pack_into("<I", mem2, 0, 1000059006)
                struct.pack_into("<Q", mem2, 8, ctypes.addressof(budget_raw))
                props2(handle, mem2)
                memory = bytes(mem2)[16:16 + 520]
            else:
                mem = (ctypes.c_ubyte * 1024)()
                lib.vkGetPhysicalDeviceMemoryProperties(handle, mem)
                memory = bytes(mem)[:520]
            devices.append(_vk_device_record(name, dtype, vendor, device_id, api_v, driver_v,
                                             memory, bytes(budget_raw) if has_budget else None,
                                             "VK_KHR_cooperative_matrix" in extensions))
    finally:
        lib.vkDestroyInstance(instance, None)
    return {"loader": True, "instance_version": vk_version(instance_version), "devices": devices}


def _vk_device_record(name, dtype, vendor, device_id, api_v, driver_v, memory, budget, coop):
    """Turn VkPhysicalDeviceMemoryProperties (and the budget struct) into figures."""
    heap_count = struct.unpack_from("<I", memory, 260)[0]
    heaps = []
    for index in range(min(heap_count, 16)):
        size, flags = struct.unpack_from("<QI", memory, 264 + index * 16)
        heap = {"size": size, "device_local": bool(flags & 1)}
        if budget is not None:
            heap["budget"] = struct.unpack_from("<Q", budget, 16 + index * 8)[0]
            heap["usage"] = struct.unpack_from("<Q", budget, 144 + index * 8)[0]
        heaps.append(heap)
    local = [h for h in heaps if h["device_local"]]
    return {
        "name": name,
        "type": VK_DEVICE_TYPES.get(dtype, "other"),
        "vendor": VK_VENDORS.get(vendor, f"0x{vendor:04x}"),
        "vendor_id": vendor,
        "device_id": device_id,
        "api_version": vk_version(api_v),
        "api_version_raw": api_v,
        "device_local_bytes": sum(h["size"] for h in local) or None,
        "budget_bytes": (sum(h.get("budget", 0) for h in local) or None) if budget is not None else None,
        "memory_budget_ext": budget is not None,
        "cooperative_matrix": coop,
        "heaps": heaps,
    }


def parse_vulkaninfo_summary(text):
    """Devices from `vulkaninfo --summary`: names, types and API versions. The
    summary carries no memory figures, so those stay None."""
    devices = []
    current = None
    for line in (text or "").splitlines():
        stripped = line.strip()
        if re.match(r"^GPU\d+:$", stripped):
            current = {"name": None, "type": "other", "vendor": None, "vendor_id": None,
                       "device_id": None, "api_version": None, "api_version_raw": None,
                       "device_local_bytes": None, "budget_bytes": None,
                       "memory_budget_ext": False, "cooperative_matrix": False, "heaps": []}
            devices.append(current)
            continue
        if current is None:
            continue
        key, sep, value = stripped.partition("=")
        if not sep:
            continue
        key, value = key.strip(), value.strip()
        if key == "deviceName":
            current["name"] = value
        elif key == "deviceType":
            kind = value.replace("PHYSICAL_DEVICE_TYPE_", "").lower()
            current["type"] = {"integrated_gpu": "integrated", "discrete_gpu": "discrete",
                               "virtual_gpu": "virtual"}.get(kind, kind if kind in VK_TYPE_RANK else "other")
        elif key == "apiVersion":
            version = value.split()[0]
            current["api_version"] = version
            parts = [int(p) for p in re.findall(r"\d+", version)[:3]] + [0, 0, 0]
            current["api_version_raw"] = (parts[0] << 22) | (parts[1] << 12) | parts[2]
        elif key == "vendorID":
            try:
                vendor = int(value.split()[0], 0)
                current["vendor_id"] = vendor
                current["vendor"] = VK_VENDORS.get(vendor, f"0x{vendor:04x}")
            except ValueError:
                pass
        elif key == "deviceID":
            try:
                current["device_id"] = int(value.split()[0], 0)
            except ValueError:
                pass
    return [d for d in devices if d["name"]]


def vulkan_usable(device):
    """A device the GPU path can use: a real GPU (not a CPU rasterizer such as
    llvmpipe/Lavapipe) with Vulkan 1.2, the engine's floor."""
    if device.get("type") not in ("discrete", "integrated", "virtual"):
        return False
    raw = device.get("api_version_raw")
    return raw is None or raw >= (1 << 22) | (2 << 12)


def best_vulkan_device(devices):
    """The device the engine will pick: the highest-ranked type, first wins."""
    best, rank = None, -1
    for device in devices:
        value = VK_TYPE_RANK.get(device.get("type"), 0)
        if value > rank:
            best, rank = device, value
    return best


def find_user_icds(home=None):
    """Vulkan driver manifests installed under the home directory.

    A driver built by hand (Mesa's Dozen for WSL2 is the usual case) installs
    its manifest under a prefix in $HOME, which the loader does not search. Only
    manifests are returned; whether one gives a usable device is the probe's
    question."""
    home = home or os.path.expanduser("~")
    patterns = (".local/share/vulkan/icd.d/*.json",
                "*/share/vulkan/icd.d/*.json",
                "*/install/share/vulkan/icd.d/*.json",
                "*/*/share/vulkan/icd.d/*.json")
    found = []
    for pattern in patterns:
        for path in sorted(glob.glob(os.path.join(home, pattern))):
            if path not in found and os.path.isfile(path):
                found.append(path)
    return found


def _probe_vulkan_child(extra_env=None, timeout=25):
    env = dict(os.environ)
    if extra_env:
        env.update(extra_env)
    try:
        result = subprocess.run([sys.executable, os.path.join(HERE, "setup_hw.py"), "--vulkan-probe"],
                                capture_output=True, text=True, timeout=timeout, env=env)
    except (OSError, subprocess.SubprocessError):
        return None
    for line in reversed(result.stdout.splitlines()):
        line = line.strip()
        if line.startswith("{"):
            try:
                return json.loads(line)
            except ValueError:
                return None
    return None


def detect_vulkan(wsl=None, home=None):
    """{"devices": [...], "icd": manifest-or-None, "source": "loader"|"vulkaninfo"|None}.

    On WSL the system drivers usually see no GPU (only the CPU rasterizer); a
    Dozen driver installed under $HOME does. When the default search finds no
    usable GPU there, each user manifest is tried in turn and the first one that
    yields a usable device is reported with its path, so the run configuration
    can point the engine at the same driver."""
    if host_os() == "darwin":
        return {"devices": [], "icd": None, "source": None}
    wsl = is_wsl() if wsl is None else wsl
    probe = _probe_vulkan_child()
    if probe is not None and probe.get("loader"):
        result = {"devices": probe.get("devices", []), "icd": None, "source": "loader"}
    else:
        summary = _run(["vulkaninfo", "--summary"], timeout=20) if shutil.which("vulkaninfo") else ""
        result = {"devices": parse_vulkaninfo_summary(summary), "icd": None,
                  "source": "vulkaninfo" if summary else None}
    if not any(vulkan_usable(d) for d in result["devices"]) and host_os().startswith("linux") \
            and not os.environ.get("VK_ICD_FILENAMES") and not os.environ.get("VK_DRIVER_FILES"):
        for manifest in find_user_icds(home):
            extra = _probe_vulkan_child({"VK_ICD_FILENAMES": manifest, "VK_DRIVER_FILES": manifest})
            if extra and any(vulkan_usable(d) for d in extra.get("devices", [])):
                result = {"devices": extra["devices"], "icd": manifest, "source": "loader"}
                break
    if os.environ.get("VK_ICD_FILENAMES") or os.environ.get("VK_DRIVER_FILES"):
        result["icd"] = os.environ.get("VK_ICD_FILENAMES") or os.environ.get("VK_DRIVER_FILES")
    return result


# ---------------------------------------------------------------- Windows video (informational)


def parse_win_video_controllers(text):
    """`Name|AdapterRAM` lines from Win32_VideoController. AdapterRAM is a uint32
    and saturates at 4 GiB, so it is shown, never planned with."""
    out = []
    for line in (text or "").splitlines():
        name, sep, ram = line.strip().partition("|")
        if not name:
            continue
        try:
            ram_bytes = int(ram) if sep and ram.strip() else None
        except ValueError:
            ram_bytes = None
        out.append({"name": name.strip(), "adapter_ram_bytes": ram_bytes})
    return out


def detect_windows_video():
    if sys.platform != "win32":
        return []
    text = _run(["powershell", "-NoProfile", "-Command",
                 "Get-CimInstance Win32_VideoController | ForEach-Object { $_.Name + '|' + $_.AdapterRAM }"],
                timeout=20)
    return parse_win_video_controllers(text)


# ---------------------------------------------------------------- the report


def _run(cmd, timeout=10):
    try:
        # errors="replace": a GPU name in the console code page must not turn
        # into a UnicodeDecodeError that throws the whole probe away.
        return subprocess.run(cmd, capture_output=True, text=True, errors="replace",
                              timeout=timeout).stdout
    except (OSError, subprocess.SubprocessError, ValueError):
        return ""


def gpu_summary(vulkan, nvidia):
    """What the setup acts on: the Vulkan device the engine would pick (when it
    is a usable GPU) and the NVIDIA cards."""
    devices = vulkan.get("devices", []) if vulkan else []
    best = best_vulkan_device(devices)
    usable = best if best is not None and vulkan_usable(best) else None
    return {"vulkan": usable, "vulkan_icd": vulkan.get("icd") if vulkan else None,
            "nvidia": nvidia, "has_gpu": bool(usable or nvidia)}


def detect(target_dir=None, probe_gpu=True):
    """The whole report, as plain data (JSON-serialisable)."""
    os_info = detect_os()
    target = os.path.abspath(os.path.expanduser(target_dir)) if target_dir else None
    report = {
        "os": os_info,
        "cpu": detect_cpu(),
        "memory": detect_memory(),
        "disk": None,
        "vulkan": {"devices": [], "icd": None, "source": None},
        "nvidia": [],
        "windows_video": [],
    }
    if target:
        report["disk"] = {"path": target, "free_bytes": disk_free(target),
                          "warnings": path_warnings(target, os_info.get("wsl"))}
    if probe_gpu:
        report["vulkan"] = detect_vulkan(wsl=os_info.get("wsl"))
        report["nvidia"] = detect_nvidia()
        if not report["vulkan"]["devices"]:
            report["windows_video"] = detect_windows_video()
    report["gpu"] = gpu_summary(report["vulkan"], report["nvidia"])
    return report


def fmt_gb(value):
    if value is None:
        return "?"
    return f"{value / GB:.1f} GB" if value < 100 * GB else f"{value / GB:.0f} GB"


def format_report(report):
    cpu, mem, osi = report["cpu"], report["memory"], report["os"]
    lines = []
    cores = cpu.get("physical_cores")
    threads = cpu.get("logical_cores")
    core_text = f"{cores} cores ({threads} threads)" if cores and threads and cores != threads \
        else f"{threads or cores or '?'} cores"
    features = ", ".join(f.upper() for f in cpu.get("features", []) if f in
                         ("avx2", "avx_vnni", "avx512f", "avx512_vnni", "avx512_bf16", "asimddp", "sve"))
    lines.append(f"  CPU     {cpu.get('name') or cpu.get('arch') or '?'}, {core_text}"
                 + (f", {features}" if features else ""))
    lines.append(f"  RAM     {fmt_gb(mem.get('total'))}"
                 + (f" ({fmt_gb(mem.get('available'))} free now)" if mem.get("available") else ""))
    disk = report.get("disk")
    if disk:
        lines.append(f"  Disk    {fmt_gb(disk.get('free_bytes'))} free in {disk['path']}")
        for warning in disk.get("warnings", []):
            lines.append(f"          warning: {warning}")
    gpu = report.get("gpu", {})
    shown = False
    if gpu.get("vulkan"):
        device = gpu["vulkan"]
        memory = device.get("budget_bytes") or device.get("device_local_bytes")
        share = ", shares RAM" if device["type"] == "integrated" else ""
        lines.append(f"  GPU     {device['name']} via Vulkan {device.get('api_version') or ''}"
                     f" ({device['type']}{share}"
                     + (f", {fmt_gb(memory)} {'budget' if device.get('budget_bytes') else 'device memory'}" if memory else "")
                     + ")")
        if gpu.get("vulkan_icd"):
            lines.append(f"          driver manifest: {gpu['vulkan_icd']}")
        shown = True
    for card in gpu.get("nvidia", []):
        lines.append(f"  GPU     {card['name']} (NVIDIA, {fmt_gb(card.get('total_bytes'))} VRAM"
                     + (f", compute {card['compute_cap']}" if card.get("compute_cap") else "")
                     + (f", driver {card['driver']}" if card.get("driver") else "") + ")")
        shown = True
    if not shown:
        cpu_only = [d for d in report.get("vulkan", {}).get("devices", []) if d.get("type") == "cpu"]
        others = report.get("windows_video") or []
        if others:
            names = ", ".join(v["name"] for v in others)
            lines.append(f"  GPU     {names} (no Vulkan driver answered; the engine will use the CPU)")
        elif cpu_only:
            lines.append(f"  GPU     none usable (Vulkan sees only {cpu_only[0]['name']}, a CPU rasterizer)")
        else:
            lines.append("  GPU     none found (the engine runs on the CPU)")
    system = osi.get("pretty_name") or osi.get("platform")
    if osi.get("wsl"):
        system = f"{system} under WSL2"
    lines.append(f"  System  {system}")
    return "\n".join(lines)


def main(argv=None):
    argv = sys.argv[1:] if argv is None else argv
    if argv[:1] == ["--vulkan-probe"]:
        try:
            print(json.dumps(_vk_probe_inprocess()))
        except Exception as error:  # report, never crash the parent's parse
            print(json.dumps({"loader": False, "error": str(error), "devices": []}))
        return 0
    if argv[:1] == ["--cuda-probe"]:
        try:
            print(json.dumps(_cuda_probe_inprocess()))
        except Exception as error:  # same rule as the Vulkan probe
            print(json.dumps({"driver": False, "error": str(error), "devices": []}))
        return 0
    sys.path.insert(0, HERE)
    targets = [arg for arg in argv if not arg.startswith("--")]
    report = detect(targets[0] if targets else os.path.expanduser("~"))
    if "--json" in argv:
        print(json.dumps(report, indent=2))
    else:
        print(format_report(report))
    return 0


if __name__ == "__main__":
    sys.exit(main())