Skip to content

Code-first video & image, rendered natively on WebGPU.

9.0 KB
Raw Blame
import { existsSync, readdirSync, readFileSync } from "node:fs";
import path from "node:path";
import { RenderError } from "../errors.js";

/**
 * GPU selection (PLAN.md §8.7). framefields renders through WebGPU (Dawn),
 * which on Linux runs on Vulkan. The image also ships Mesa's CPU Vulkan
 * driver (lavapipe) so a machine without a GPU can still render. Without
 * care, a GPU machine whose Vulkan driver isn't mounted would silently render
 * on the CPU too, so:
 *
 * - auto (default): a machine with a GPU must render on it (Vulkan is limited
 *   to the GPU drivers); a machine without one renders on the CPU.
 * - require: always the GPU; a machine without one fails.
 * - cpu: always the CPU driver.
 */
type GpuMode = "auto" | "require" | "cpu";

export interface GpuHardware {
	vendor: "nvidia" | "amd" | "intel" | "apple";
	/** Model name when the driver reports one. */
	model: string;
}

interface GpuPlan {
	mode: GpuMode;
	hardware: GpuHardware | null;
	/** What the rendering adapter must be. */
	expect: "hardware" | "software";
	/** Vulkan drivers (ICD manifests) to limit the loader to, if any. */
	icds?: string[];
	/** Why this machine can't render as configured. */
	problem?: string;
	hint?: string;
}

/** The adapter framefields renders on (framefields' describeGpu shape). */
export interface GpuAdapter {
	vendor: string;
	architecture: string;
	device: string;
	description: string;
	software: boolean;
}

export interface GpuProbe {
	platform: NodeJS.Platform;
	hardware: GpuHardware | null;
	icds: { hardware: string[]; software: string[] };
}

const ICD_DIRS = [
	"/etc/vulkan/icd.d",
	"/usr/share/vulkan/icd.d",
	"/usr/local/share/vulkan/icd.d",
];
const SOFTWARE_ICD = /lvp|lavapipe|swiftshader/i;
const SOFTWARE_ADAPTER =
	/llvmpipe|lavapipe|softpipe|swiftshader|\bwarp\b|software/i;
const PCI_VENDORS: Record<string, GpuHardware["vendor"]> = {
	"0x10de": "nvidia",
	"0x1002": "amd",
	"0x8086": "intel",
};

function safeList(dir: string): string[] {
	try {
		return readdirSync(dir);
	} catch {
		return [];
	}
}

function nvidiaModel(): string {
	for (const gpu of safeList("/proc/driver/nvidia/gpus")) {
		try {
			const info = readFileSync(
				path.join("/proc/driver/nvidia/gpus", gpu, "information"),
				"utf8",
			);
			const model = /^Model:\s*(.+)$/m.exec(info)?.[1]?.trim();
			if (model) return model;
		} catch {}
	}
	return "NVIDIA GPU";
}

/** Finds a GPU this process can use (device nodes present, not just listed in /sys). */
function detectGpuHardware(
	platform: NodeJS.Platform = process.platform,
): GpuHardware | null {
	if (platform === "darwin") return { vendor: "apple", model: "Metal" };
	if (platform !== "linux") return null;
	if (existsSync("/dev/nvidiactl") || existsSync("/dev/nvidia0")) {
		return { vendor: "nvidia", model: nvidiaModel() };
	}
	// AMD/Intel: needs a render node; /sys lists host GPUs even when the
	// container wasn't given one.
	if (!safeList("/dev/dri").some((n) => n.startsWith("renderD"))) return null;
	for (const card of safeList("/sys/class/drm")) {
		if (!/^card\d+$/.test(card)) continue;
		try {
			const id = readFileSync(
				path.join("/sys/class/drm", card, "device/vendor"),
				"utf8",
			).trim();
			const vendor = PCI_VENDORS[id];
			if (vendor) return { vendor, model: `${vendor.toUpperCase()} GPU` };
		} catch {}
	}
	return null;
}

/** Vulkan driver manifests, split into GPU and CPU drivers. */
export function findVulkanIcds(dirs = ICD_DIRS): GpuProbe["icds"] {
	const hardware: string[] = [];
	const software: string[] = [];
	for (const dir of dirs) {
		for (const name of safeList(dir).sort()) {
			if (!name.endsWith(".json")) continue;
			const file = path.join(dir, name);
			let library = "";
			try {
				library = String(
					JSON.parse(readFileSync(file, "utf8"))?.ICD?.library_path ?? "",
				);
			} catch {}
			(SOFTWARE_ICD.test(name) || SOFTWARE_ICD.test(library)
				? software
				: hardware
			).push(file);
		}
	}
	return { hardware, software };
}

export function probeGpu(): GpuProbe {
	return {
		platform: process.platform,
		hardware: detectGpuHardware(),
		icds:
			process.platform === "linux"
				? findVulkanIcds()
				: { hardware: [], software: [] },
	};
}

/**
 * Decides where to render. `env` is checked for Vulkan driver overrides an
 * operator already set; those are respected as they are.
 */
export function planGpu(
	mode: GpuMode,
	probe: GpuProbe,
	env: NodeJS.ProcessEnv = process.env,
): GpuPlan {
	const { hardware, icds } = probe;
	const linux = probe.platform === "linux";
	const overridden = Boolean(env.VK_DRIVER_FILES || env.VK_ICD_FILENAMES);
	const limit = (files: string[]) =>
		linux && !overridden && files.length ? files : undefined;

	if (mode === "cpu") {
		if (linux && !overridden && icds.software.length === 0) {
			return {
				mode,
				hardware,
				expect: "software",
				problem: "FF_GPU=cpu but no CPU Vulkan driver is installed.",
				hint: "Install mesa-vulkan-drivers (lavapipe).",
			};
		}
		return { mode, hardware, expect: "software", icds: limit(icds.software) };
	}

	if (hardware) {
		if (linux && !overridden && icds.hardware.length === 0) {
			return {
				mode,
				hardware,
				expect: "hardware",
				problem: `${hardware.model} found, but no Vulkan driver for it.`,
				hint:
					hardware.vendor === "nvidia"
						? "Run with the NVIDIA container runtime and NVIDIA_DRIVER_CAPABILITIES including graphics (the image sets graphics,utility,video,compute)."
						: "Install the GPU's Vulkan driver (mesa-vulkan-drivers covers AMD and Intel).",
			};
		}
		return {
			mode,
			hardware,
			expect: "hardware",
			icds: limit(icds.hardware),
		};
	}

	if (mode === "require") {
		return {
			mode,
			hardware,
			expect: "hardware",
			problem: "FF_GPU=require but this machine has no GPU.",
			hint: "Run on a GPU machine, or set FF_GPU=auto to allow CPU rendering.",
		};
	}
	return { mode, hardware, expect: "software" };
}

let active: GpuPlan | undefined;
let adapter: GpuAdapter | undefined;
let adapterProblem: string | undefined;

/** Limits Vulkan to the planned drivers. Must run before the engine loads. */
export function applyGpuPlan(plan: GpuPlan): void {
	active = plan;
	adapter = undefined;
	adapterProblem = undefined;
	if (plan.icds) {
		const files = plan.icds.join(path.delimiter);
		process.env.VK_DRIVER_FILES = files;
		process.env.VK_ICD_FILENAMES = files; // Vulkan loaders before 1.3.207
	}
}

export function classifyAdapter(info: {
	vendor?: unknown;
	architecture?: unknown;
	device?: unknown;
	description?: unknown;
	isFallbackAdapter?: unknown;
}): GpuAdapter {
	const out = {
		vendor: String(info.vendor ?? ""),
		architecture: String(info.architecture ?? ""),
		device: String(info.device ?? ""),
		description: String(info.description ?? ""),
	};
	return {
		...out,
		software:
			info.isFallbackAdapter === true ||
			SOFTWARE_ADAPTER.test(
				`${out.vendor} ${out.architecture} ${out.device} ${out.description}`,
			),
	};
}

/**
 * The adapter the engine renders on: framefields' describeGpu() where the
 * project's version has it, else the adapter WebGPU picks with the same
 * options framefields uses.
 */
export async function describeAdapter(mod: {
	describeGpu?: () => Promise<GpuAdapter>;
}): Promise<GpuAdapter | undefined> {
	if (typeof mod.describeGpu === "function") return mod.describeGpu();
	const gpu = (
		globalThis as {
			navigator?: { gpu?: { requestAdapter(o?: object): Promise<unknown> } };
		}
	).navigator?.gpu;
	if (!gpu) return undefined;
	const found = (await gpu.requestAdapter({
		powerPreference: "high-performance",
	})) as { info?: Record<string, unknown>; isFallbackAdapter?: unknown } | null;
	if (!found) return undefined;
	return classifyAdapter({
		isFallbackAdapter: found.isFallbackAdapter,
		...found.info,
	});
}

function adapterName(a: GpuAdapter): string {
	return a.description || a.device || a.architecture || a.vendor || "unknown";
}

/**
 * Checks the engine's adapter against the plan. A GPU machine that ended up
 * on the CPU driver fails with GPU_UNAVAILABLE and the worker reports itself
 * unhealthy, so a scheduler (RunPod) replaces it.
 */
export function verifyAdapter(found: GpuAdapter | undefined): void {
	adapter = found;
	const plan = active;
	if (!plan || !found) return;
	if (plan.expect === "hardware" && found.software) {
		adapterProblem = `${plan.hardware?.model ?? "A GPU"} is present but WebGPU picked the CPU driver (${adapterName(found)}).`;
		throw new RenderError("GPU_UNAVAILABLE", adapterProblem, {
			phase: "render",
			hint: "Check the GPU's Vulkan driver (vulkaninfo --summary). FF_GPU=cpu renders on the CPU on purpose.",
		});
	}
}

/** Boot or adapter problem that makes this worker unable to render. */
export function gpuFailure(): string | undefined {
	return active?.problem ?? adapterProblem;
}

/** GPU state for /health. */
export function gpuStatus() {
	return {
		mode: active?.mode ?? null,
		hardware: active?.hardware?.model ?? null,
		renderer: gpuFailure()
			? null
			: (adapter ? adapter.software : active?.expect === "software")
				? "cpu"
				: "gpu",
		adapter: adapter
			? { name: adapterName(adapter), software: adapter.software }
			: null,
	};
}