@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/system-metrics/gpu-devices-linux.ts

@@ -0,0 +1,370 @@
+/**
+ * Whole-GPU figures for Mission Center's GPU page, from `/sys/class/drm/card*`.
+ *
+ * There is no one source: utilisation comes from the DRM fdinfo engine counters
+ * where the driver publishes them (Intel, AMD, and the only unprivileged option
+ * on Intel at all), from amdgpu's own `gpu_busy_percent` where it exists, and
+ * from i915's rc6 idle residency as a last resort. Anything a given driver does
+ * not expose stays ABSENT rather than 0, so the page hides the row.
+ *
+ * NVIDIA keeps its existing `nvidia-smi` collector: the proprietary driver
+ * publishes neither fdinfo engine counters nor the sysfs attributes below.
+ */
+import os from "node:os";
+import type { GpuInfo, GpuMetrics } from "../../types/system-metrics.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+import { readUdevProperties, udevValue } from "./udev-db.ts";
+import type { DrmUsage } from "./gpu-fdinfo-linux.ts";
+
+export const DRM_DIR = "/sys/class/drm";
+const RAPL_DIR = "/sys/class/powercap";
+
+const VENDORS: Record<string, string> = {
+  "0x8086": "Intel",
+  "0x1002": "AMD",
+  "0x1022": "AMD",
+  "0x10de": "NVIDIA",
+};
+
+/** `current_link_speed` reads "8.0 GT/s PCIe"; the rate identifies the generation. */
+const PCIE_GEN_BY_RATE: Record<string, number> = {
+  "2.5": 1, "5.0": 2, "8.0": 3, "16.0": 4, "32.0": 5, "64.0": 6,
+};
+
+export interface GpuCard {
+  /** "card1". */
+  card: string;
+  /** PCI address — the id both `GpuMetrics` and `GpuInfo` are keyed by. */
+  pdev: string;
+  driver: string;
+  vendor?: string;
+}
+
+/** Real render nodes only: `card1-DP-1` is a connector, not a device, and a
+ *  driver with no PCI parent (vkms, a virtio display) has nothing to report. */
+export function listGpuCards(fs: Pick<LinuxFs, "list" | "read" | "readlink" | "realpath">): GpuCard[] {
+  const cards: GpuCard[] = [];
+  for (const entry of (fs.list(DRM_DIR) ?? []).sort()) {
+    if (!/^card\d+$/.test(entry)) continue;
+    const real = fs.realpath(`${DRM_DIR}/${entry}/device`);
+    const pdev = real ? real.slice(real.lastIndexOf("/") + 1) : "";
+    if (!/^[0-9a-f]{4}:/i.test(pdev)) continue;
+    const driver = basename(fs.readlink(`${DRM_DIR}/${entry}/device/driver`) ?? "");
+    const vendorId = readAttr(fs, `${DRM_DIR}/${entry}/device/vendor`);
+    cards.push({
+      card: entry,
+      pdev,
+      driver,
+      ...(vendorId && VENDORS[vendorId] ? { vendor: VENDORS[vendorId] } : {}),
+    });
+  }
+  return cards;
+}
+
+export interface GpuSample {
+  atSec: number;
+  /** i915 cumulative idle residency, ms. */
+  rc6Ms?: number;
+  /** RAPL uncore energy, µJ — the integrated GPU's share of package power. */
+  uncoreUj?: number;
+}
+
+export type GpuSampleState = Map<string, GpuSample>;
+
+export interface GpuDeviceCollection {
+  gpus: GpuMetrics[];
+  next: GpuSampleState;
+}
+
+export function collectLinuxGpus(
+  prev: GpuSampleState,
+  usage: DrmUsage,
+  fs: Pick<LinuxFs, "list" | "read" | "readlink" | "realpath"> = realLinuxFs,
+  now: () => number = Date.now,
+  totalRamBytes: number = os.totalmem(),
+): GpuDeviceCollection {
+  const atSec = now() / 1000;
+  const uncoreUj = readUncoreEnergy(fs);
+  const next: GpuSampleState = new Map();
+  const gpus: GpuMetrics[] = [];
+
+  for (const card of listGpuCards(fs)) {
+    // NVIDIA is covered by the nvidia-smi collector; listing it here too would
+    // publish the same GPU twice with half the figures missing.
+    if (card.driver === "nvidia" || card.driver === "nouveau") continue;
+    const dir = `${DRM_DIR}/${card.card}`;
+    const sample: GpuSample = {
+      atSec,
+      ...defined("rc6Ms", readNumber(fs, `${dir}/power/rc6_residency_ms`)),
+      ...defined("uncoreUj", uncoreUj),
+    };
+    next.set(card.card, sample);
+    gpus.push(buildGpuMetrics(card, dir, prev.get(card.card) ?? null, sample, usage, fs, totalRamBytes));
+  }
+  return { gpus, next };
+}
+
+function buildGpuMetrics(
+  card: GpuCard,
+  dir: string,
+  prev: GpuSample | null,
+  next: GpuSample,
+  usage: DrmUsage,
+  fs: Pick<LinuxFs, "list" | "read">,
+  totalRamBytes: number,
+): GpuMetrics {
+  const engines = usage.perDevice.get(card.pdev);
+  const integrated = card.driver === "i915" || card.driver === "xe";
+  const vram = readVram(dir, fs);
+  const hwmon = findHwmon(dir, fs);
+
+  return {
+    id: card.pdev,
+    name: gpuName(card, fs),
+    utilPercent: utilisation(card, dir, engines, prev, next, fs),
+    vramUsedMB: vram.usedMB,
+    vramTotalMB: vram.totalMB,
+    ...sharedMemory(card, dir, usage, fs, totalRamBytes),
+    ...videoEngines(card, engines),
+    ...defined("clockMHz", currentClockMHz(card, dir, fs)),
+    ...defined("clockMaxMHz", maxClockMHz(card, dir, fs)),
+    ...defined("memClockMHz", pickDpmCurrent(readAttr(fs, `${dir}/device/pp_dpm_mclk`))),
+    ...defined("powerW", integrated ? uncoreWatts(prev, next) : hwmonPowerW(hwmon, fs)),
+    ...defined("tempC", hwmonTempC(hwmon, fs)),
+  };
+}
+
+/**
+ * Engine busy first: it is the only unprivileged per-engine figure Intel has and
+ * it matches what the process rows are built from, so the page and the table
+ * agree. amdgpu's own counter is preferred over rc6 where fdinfo said nothing,
+ * and rc6 is the last resort — it measures IDLE, so busy is its complement.
+ */
+export function utilisation(
+  card: GpuCard,
+  dir: string,
+  engines: ReadonlyMap<string, number> | undefined,
+  prev: GpuSample | null,
+  next: GpuSample,
+  fs: Pick<LinuxFs, "read">,
+): number {
+  const render = (engines?.get("render") ?? 0) + (engines?.get("compute") ?? 0);
+  if (render > 0) return round1(Math.min(100, render));
+
+  const amdBusy = readNumber(fs, `${dir}/device/gpu_busy_percent`);
+  if (amdBusy !== undefined) return round1(Math.min(100, Math.max(0, amdBusy)));
+
+  const rc6 = rc6BusyPercent(prev, next);
+  return rc6 ?? 0;
+}
+
+/** i915's rc6 counter is cumulative time spent in the deepest idle state. */
+export function rc6BusyPercent(prev: GpuSample | null, next: GpuSample): number | undefined {
+  if (!prev || prev.rc6Ms === undefined || next.rc6Ms === undefined) return undefined;
+  const dtMs = (next.atSec - prev.atSec) * 1000;
+  const idle = next.rc6Ms - prev.rc6Ms;
+  if (!(dtMs > 0) || idle < 0) return undefined;
+  return round1(Math.min(100, Math.max(0, 100 - idle / dtMs * 100)));
+}
+
+/** Intel exposes ONE video engine doing both encode and decode, so the page
+ *  labels it "Video encode/decode" rather than inventing a second figure. */
+function videoEngines(card: GpuCard, engines: ReadonlyMap<string, number> | undefined): Partial<GpuMetrics> {
+  if (!engines) return {};
+  const video = engines.get("video");
+  const enhance = engines.get("video-enhance");
+  if (video === undefined && enhance === undefined) return {};
+  if (card.driver === "i915" || card.driver === "xe") {
+    return { encodePercent: round1(Math.min(100, (video ?? 0) + (enhance ?? 0))) };
+  }
+  return {
+    ...defined("encodePercent", video === undefined ? undefined : round1(video)),
+    ...defined("decodePercent", enhance === undefined ? undefined : round1(enhance)),
+  };
+}
+
+/**
+ * System memory the GPU is using — Mission Center's "Memory Usage" on a card
+ * with no VRAM of its own, where it is the page's only memory figure.
+ *
+ * amdgpu's own GTT counters win where they exist: they are the driver's view of
+ * its aperture, and the aperture — not system RAM — is that card's ceiling. An
+ * integrated GPU publishes neither, so the figure is summed out of its clients'
+ * DRM fdinfo against the machine's RAM, which is what Mission Center shows (it
+ * read 2.52 GiB / 62.5 GiB here while this summed 2.54 GiB).
+ *
+ * Both halves must be present or neither is reported: a used figure over an
+ * unknown ceiling is not a reading.
+ */
+export function sharedMemory(
+  card: GpuCard,
+  dir: string,
+  usage: DrmUsage,
+  fs: Pick<LinuxFs, "read">,
+  totalRamBytes: number,
+): Partial<GpuMetrics> {
+  const gttUsed = bytesToMB(readNumber(fs, `${dir}/device/mem_info_gtt_used`));
+  const gttTotal = bytesToMB(readNumber(fs, `${dir}/device/mem_info_gtt_total`));
+  if (gttUsed !== undefined && gttTotal !== undefined) {
+    return { sharedUsedMB: gttUsed, sharedTotalMB: gttTotal };
+  }
+  const fromClients = usage.sharedByDevice.get(card.pdev);
+  const ram = bytesToMB(totalRamBytes > 0 ? totalRamBytes : undefined);
+  if (fromClients === undefined || ram === undefined) return {};
+  return { sharedUsedMB: Math.round(fromClients), sharedTotalMB: ram };
+}
+
+/** amdgpu is the only driver here with dedicated memory counters; an integrated
+ *  GPU reports a 0 total, which the contract defines as "has none to report". */
+function readVram(dir: string, fs: Pick<LinuxFs, "read">): { usedMB: number; totalMB: number } {
+  const used = readNumber(fs, `${dir}/device/mem_info_vram_used`);
+  const total = readNumber(fs, `${dir}/device/mem_info_vram_total`);
+  return { usedMB: bytesToMB(used) ?? 0, totalMB: bytesToMB(total) ?? 0 };
+}
+
+/**
+ * i915's REQUESTED clock, not its actual one.
+ *
+ * `gt_act_freq_mhz` is sampled the instant the file is read, and an idle GPU is
+ * parked in RC6 for most of any 2 s tick — so it returns 0 far more often than
+ * not and the figure flickers between 0 and 1400 MHz beside a fixed maximum,
+ * which reads as a broken number rather than as an idle GPU. `gt_cur_freq_mhz`
+ * is the frequency the driver is holding the card at and moves with load.
+ */
+function currentClockMHz(card: GpuCard, dir: string, fs: Pick<LinuxFs, "read">): number | undefined {
+  return readNumber(fs, `${dir}/gt_cur_freq_mhz`)
+    ?? readNumber(fs, `${dir}/gt_act_freq_mhz`)
+    ?? pickDpmCurrent(readAttr(fs, `${dir}/device/pp_dpm_sclk`));
+}
+
+function maxClockMHz(card: GpuCard, dir: string, fs: Pick<LinuxFs, "read">): number | undefined {
+  return readNumber(fs, `${dir}/gt_RP0_freq_mhz`)
+    ?? readNumber(fs, `${dir}/gt_max_freq_mhz`)
+    ?? pickDpmMax(readAttr(fs, `${dir}/device/pp_dpm_sclk`));
+}
+
+/** amdgpu's DPM tables list one state per line and mark the live one with `*`:
+ *  `1: 500Mhz *`. */
+export function pickDpmCurrent(table: string | undefined): number | undefined {
+  if (!table) return undefined;
+  for (const line of table.split("\n")) {
+    if (!line.includes("*")) continue;
+    const m = /(\d+)\s*Mhz/i.exec(line);
+    if (m) return Number(m[1]);
+  }
+  return undefined;
+}
+
+export function pickDpmMax(table: string | undefined): number | undefined {
+  if (!table) return undefined;
+  let max: number | undefined;
+  for (const line of table.split("\n")) {
+    const m = /(\d+)\s*Mhz/i.exec(line);
+    if (m) max = Math.max(max ?? 0, Number(m[1]));
+  }
+  return max;
+}
+
+/** The card's own hwmon directory, e.g. `.../card0/device/hwmon/hwmon4`. */
+function findHwmon(dir: string, fs: Pick<LinuxFs, "list">): string | undefined {
+  const base = `${dir}/device/hwmon`;
+  const entry = fs.list(base)?.find((n) => n.startsWith("hwmon"));
+  return entry ? `${base}/${entry}` : undefined;
+}
+
+function hwmonTempC(hwmon: string | undefined, fs: Pick<LinuxFs, "read">): number | undefined {
+  if (!hwmon) return undefined;
+  const milli = readNumber(fs, `${hwmon}/temp1_input`);
+  return milli === undefined ? undefined : Math.round(milli / 100) / 10;
+}
+
+/** amdgpu publishes microwatts. */
+function hwmonPowerW(hwmon: string | undefined, fs: Pick<LinuxFs, "read">): number | undefined {
+  if (!hwmon) return undefined;
+  const uw = readNumber(fs, `${hwmon}/power1_average`) ?? readNumber(fs, `${hwmon}/power1_input`);
+  return uw === undefined ? undefined : Math.round(uw / 1000) / 1000;
+}
+
+/** RAPL's uncore domain is the integrated GPU's slice of the package budget —
+ *  the only power figure an Intel iGPU has without root. */
+export function readUncoreEnergy(fs: Pick<LinuxFs, "list" | "read">): number | undefined {
+  for (const pkg of fs.list(RAPL_DIR) ?? []) {
+    if (!/^intel-rapl:\d+$/.test(pkg)) continue;
+    for (const sub of fs.list(`${RAPL_DIR}/${pkg}`) ?? []) {
+      if (!sub.startsWith("intel-rapl:")) continue;
+      if (readAttr(fs, `${RAPL_DIR}/${pkg}/${sub}/name`) !== "uncore") continue;
+      const uj = readNumber(fs, `${RAPL_DIR}/${pkg}/${sub}/energy_uj`);
+      if (uj !== undefined) return uj;
+    }
+  }
+  return undefined;
+}
+
+function uncoreWatts(prev: GpuSample | null, next: GpuSample): number | undefined {
+  if (!prev || prev.uncoreUj === undefined || next.uncoreUj === undefined) return undefined;
+  const dt = next.atSec - prev.atSec;
+  const dj = next.uncoreUj - prev.uncoreUj;
+  if (!(dt > 0) || dj < 0) return undefined;
+  return Math.round(dj / dt / 1000) / 1000;
+}
+
+// ---------------------------------------------------------------- static
+
+export function readGpuInfo(
+  card: GpuCard,
+  api: { opengl?: string; vulkan?: string; mesa?: string },
+  fs: Pick<LinuxFs, "list" | "read">,
+): GpuInfo {
+  const dir = `${DRM_DIR}/${card.card}`;
+  const link = pcieLink(dir, fs);
+  return {
+    id: card.pdev,
+    name: gpuName(card, fs),
+    ...defined("vendor", card.vendor),
+    ...defined("driver", card.driver || undefined),
+    ...defined("driverVersion", readAttr(fs, `/sys/module/${card.driver}/version`) ?? api.mesa),
+    ...defined("openglVersion", api.opengl),
+    ...defined("vulkanVersion", api.vulkan),
+    ...link,
+    ...(card.driver === "i915" || card.driver === "xe" ? { encodeDecodeShared: true } : {}),
+  };
+}
+
+/** The PCI database name udev already resolved, e.g. "Alder Lake-S GT1 [UHD
+ *  Graphics 770]". Falls back to the driver, never to an empty string. */
+export function gpuName(card: GpuCard, fs: Pick<LinuxFs, "read">): string {
+  const props = readUdevProperties(`+pci:${card.pdev}`, fs.read);
+  const fallback = [card.vendor, card.driver].filter(Boolean).join(" ");
+  return udevValue(props, "ID_MODEL_FROM_DATABASE") ?? (fallback || card.pdev);
+}
+
+/** Current and maximum link, with the maximum reported only when it DIFFERS —
+ *  Mission Center hides an equal one, and an integrated GPU has no real link at
+ *  all (its `current_link_speed` reads "Unknown" and its width 0). */
+export function pcieLink(dir: string, fs: Pick<LinuxFs, "read">): Partial<GpuInfo> {
+  const gen = pcieGen(readAttr(fs, `${dir}/device/current_link_speed`));
+  const lanes = positive(readNumber(fs, `${dir}/device/current_link_width`));
+  const maxGen = pcieGen(readAttr(fs, `${dir}/device/max_link_speed`));
+  const maxLanes = positive(readNumber(fs, `${dir}/device/max_link_width`));
+  if (gen === undefined && lanes === undefined) return {};
+  return {
+    ...defined("pcieGen", gen),
+    ...defined("pcieLanes", lanes),
+    ...(maxGen !== undefined && maxGen !== gen ? { pcieMaxGen: maxGen } : {}),
+    ...(maxLanes !== undefined && maxLanes !== lanes ? { pcieMaxLanes: maxLanes } : {}),
+  };
+}
+
+export function pcieGen(speed: string | undefined): number | undefined {
+  const m = /^([\d.]+)\s*GT\/s/i.exec(speed?.trim() ?? "");
+  return m ? PCIE_GEN_BY_RATE[m[1]!] : undefined;
+}
+
+const basename = (p: string) => p.slice(p.lastIndexOf("/") + 1);
+const round1 = (n: number) => Math.round(n * 10) / 10;
+const positive = (n: number | undefined) => (n !== undefined && n > 0 ? n : undefined);
+const bytesToMB = (n: number | undefined) => (n === undefined ? undefined : Math.round(n / 1024 ** 2));
+
+function defined<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
+}

package/src/services/system-metrics/gpu-fdinfo-linux.ts

@@ -0,0 +1,253 @@
+/**
+ * Per-process GPU accounting from DRM fdinfo — the same source nvtop and Mission
+ * Center use, and the only one that works for Intel and AMD without root.
+ *
+ * `/proc/<pid>/fdinfo/<fd>` of a DRM file carries cumulative engine busy time in
+ * nanoseconds. Two things make it trickier than a counter read:
+ *
+ *  - walking every fd of every process costs ~140 ms on a desktop with 3000
+ *    threads, which a 2 s tick cannot pay. Only a handful of processes ever hold
+ *    a DRM fd (15 of 558 here), so the full scan runs on a slow cadence and every
+ *    other tick re-reads just those — measured at ~2 ms, a 70x saving.
+ *  - a client's fds are SHARED across its threads and often dup'd, so the same
+ *    counters appear many times; `drm-client-id` identifies the real client and
+ *    is what deduplicates them. Summing without that multiplies a browser's GPU
+ *    use by its thread count.
+ *  - the counter is per engine, so "GPU %" is engine busy over WALL time, not
+ *    over some total — an engine can only ever be busy for the time that passed.
+ */
+import { realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+
+const PROC = "/proc";
+const DRI_PREFIX = "/dev/dri/";
+
+export interface DrmClient {
+  /** PCI address the client is rendering on, e.g. "0000:00:02.0". */
+  pdev: string;
+  /** Unique per open client on that device; the deduplication key with `pdev`. */
+  clientId: string;
+  driver: string;
+  pid: number;
+  /** Engine name ("render", "copy", "video", "video-enhance", "compute") → ns. */
+  engines: Map<string, number>;
+  /** Dedicated (VRAM) bytes this client holds; 0 on an integrated GPU. */
+  vramBytes: number;
+  /** System/GTT bytes this client holds. */
+  sharedBytes: number;
+}
+
+/** One fdinfo file. Null when it is not a DRM fd (the overwhelming majority). */
+export function parseDrmFdinfo(text: string, pid: number): DrmClient | null {
+  let pdev = "";
+  let clientId = "";
+  let driver = "";
+  let vramBytes = 0;
+  let sharedBytes = 0;
+  const engines = new Map<string, number>();
+
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("drm-")) continue;
+    const sep = line.indexOf(":");
+    if (sep < 0) continue;
+    const key = line.slice(0, sep);
+    const value = line.slice(sep + 1).trim();
+
+    if (key === "drm-pdev") pdev = value;
+    else if (key === "drm-client-id") clientId = value;
+    else if (key === "drm-driver") driver = value;
+    else if (key.startsWith("drm-engine-")) {
+      const ns = Number(value.split(/\s+/)[0]);
+      if (Number.isFinite(ns)) engines.set(key.slice("drm-engine-".length), ns);
+    } else if (key.startsWith("drm-total-")) {
+      // `drm-total-vram0`/`-vram` is dedicated; `-system0`/`-gtt` is shared.
+      const region = key.slice("drm-total-".length);
+      const bytes = parseMemoryValue(value);
+      if (region.startsWith("vram")) vramBytes += bytes;
+      else if (region.startsWith("system") || region.startsWith("gtt")) sharedBytes += bytes;
+    }
+  }
+
+  if (!pdev || !clientId) return null;
+  return { pdev, clientId, driver, pid, engines, vramBytes, sharedBytes };
+}
+
+/** fdinfo writes memory as "74920 KiB" (i915) or a bare byte count (amdgpu). */
+export function parseMemoryValue(value: string): number {
+  const [raw, unit] = value.split(/\s+/);
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 0;
+  switch (unit) {
+    case "KiB": return n * 1024;
+    case "MiB": return n * 1024 ** 2;
+    case "GiB": return n * 1024 ** 3;
+    default: return n;
+  }
+}
+
+/**
+ * Every distinct DRM client on the machine, deduplicated by (pdev, client-id).
+ *
+ * Only fds whose `/proc/<pid>/fd/<n>` link points into `/dev/dri` are read: one
+ * `readlink` beats an `open`+`read`+`close` on every fd of every process, and on
+ * a desktop with ~3000 threads that is the difference between a few ms and a
+ * tick that misses its deadline.
+ */
+export function collectDrmClients(
+  fs: Pick<LinuxFs, "list" | "read" | "readlink"> = realLinuxFs,
+  onlyPids?: readonly number[],
+): DrmClient[] {
+  const byKey = new Map<string, DrmClient>();
+  const candidates = onlyPids ?? (fs.list(PROC) ?? []).map(Number);
+  for (const entry of candidates) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    for (const fd of fs.list(`${PROC}/${pid}/fd`) ?? []) {
+      if (!fs.readlink(`${PROC}/${pid}/fd/${fd}`)?.startsWith(DRI_PREFIX)) continue;
+      const text = fs.read(`${PROC}/${pid}/fdinfo/${fd}`);
+      if (!text) continue;
+      const client = parseDrmFdinfo(text, pid);
+      if (!client) continue;
+      const key = `${client.pdev}/${client.clientId}`;
+      // The lowest pid holding a client is its owner; a dup in a child would
+      // otherwise attribute the parent's rendering to whichever fd came last.
+      const existing = byKey.get(key);
+      if (!existing || client.pid < existing.pid) byKey.set(key, client);
+    }
+  }
+  return [...byKey.values()];
+}
+
+/** Cumulative engine ns per client, plus the clock they were read at. */
+export interface DrmEngineState {
+  atSec: number;
+  /** "<pdev>/<clientId>" → engine → ns. */
+  byClient: Map<string, Map<string, number>>;
+}
+
+export interface DrmUsage {
+  /** pdev → engine → busy percent over the interval (0-100 per engine). */
+  perDevice: Map<string, Map<string, number>>;
+  /** pid → summed engine percent (clamped 0-100) and memory in MB. */
+  perProcess: Map<number, { gpuPct: number; vramMB: number; sharedMB: number }>;
+  /**
+   * pdev → system/GTT memory its clients hold, MB. This is the ONLY whole-device
+   * memory figure an integrated GPU has: i915 publishes no `mem_info_*` sysfs
+   * attribute, so without it the page can say nothing at all.
+   *
+   * A buffer shared between two clients is counted twice, because fdinfo's
+   * `drm-total-*` is per client and the `drm-shared-*` line does not say WHO it
+   * is shared with. Mission Center sums the same way — measured against it live,
+   * 2.54 GiB here against its 2.52 GiB.
+   */
+  sharedByDevice: Map<string, number>;
+}
+
+export function toEngineState(clients: readonly DrmClient[], atSec: number): DrmEngineState {
+  const byClient = new Map<string, Map<string, number>>();
+  for (const c of clients) byClient.set(`${c.pdev}/${c.clientId}`, c.engines);
+  return { atSec, byClient };
+}
+
+/**
+ * Engine busy over the wall interval. A client that did not exist on the previous
+ * sample contributes nothing this tick — measuring its whole lifetime against one
+ * interval is how a freshly launched window reads as 4000 % GPU.
+ */
+export function computeDrmUsage(
+  prev: DrmEngineState | null,
+  clients: readonly DrmClient[],
+  atSec: number,
+): DrmUsage {
+  const perDevice = new Map<string, Map<string, number>>();
+  const perProcess = new Map<number, { gpuPct: number; vramMB: number; sharedMB: number }>();
+  const sharedByDevice = new Map<string, number>();
+  const dtNs = prev ? (atSec - prev.atSec) * 1e9 : 0;
+
+  for (const c of clients) {
+    const MB = 1024 ** 2;
+    const row = perProcess.get(c.pid) ?? { gpuPct: 0, vramMB: 0, sharedMB: 0 };
+    row.vramMB += c.vramBytes / MB;
+    row.sharedMB += c.sharedBytes / MB;
+    // Every device a client was seen on gets an entry, even at 0 bytes: "this
+    // GPU's clients hold nothing" is a reading, and no entry at all is not.
+    sharedByDevice.set(c.pdev, (sharedByDevice.get(c.pdev) ?? 0) + c.sharedBytes / MB);
+
+    if (dtNs > 0) {
+      const before = prev!.byClient.get(`${c.pdev}/${c.clientId}`);
+      if (before) {
+        const engines = perDevice.get(c.pdev) ?? new Map<string, number>();
+        for (const [engine, ns] of c.engines) {
+          const delta = ns - (before.get(engine) ?? 0);
+          if (delta <= 0) continue;
+          const pct = Math.min(100, delta / dtNs * 100);
+          engines.set(engine, (engines.get(engine) ?? 0) + pct);
+          row.gpuPct += pct;
+        }
+        perDevice.set(c.pdev, engines);
+      }
+    }
+    row.gpuPct = Math.min(100, row.gpuPct);
+    perProcess.set(c.pid, row);
+  }
+
+  // A device's engine can only be busy for the interval that passed.
+  for (const engines of perDevice.values()) {
+    for (const [engine, pct] of engines) engines.set(engine, Math.min(100, round1(pct)));
+  }
+  for (const row of perProcess.values()) {
+    row.gpuPct = round1(row.gpuPct);
+    row.vramMB = round1(row.vramMB);
+    row.sharedMB = round1(row.sharedMB);
+  }
+  for (const [pdev, mb] of sharedByDevice) sharedByDevice.set(pdev, round1(mb));
+  return { perDevice, perProcess, sharedByDevice };
+}
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+// ------------------------------------------------------- stateful collector
+
+/** How long one walk's result is reused. Both the whole-GPU figures and the
+ *  process rows are built from the same tick, so whichever asks first pays for
+ *  the walk and the other reads the same numbers — they can never disagree. */
+export const DRM_MEMO_MS = 1000;
+/** Full `/proc` rescans are this far apart; in between, only the pids already
+ *  known to hold a DRM fd are re-read. A window opened now shows GPU use within
+ *  one rescan rather than immediately, which is the cost of not paying 140 ms
+ *  every 2 s forever. */
+export const DRM_RESCAN_MS = 10_000;
+
+export interface DrmGpuCollector {
+  /** This tick's usage, walking `/proc` at most once per `DRM_MEMO_MS`. */
+  usage(): DrmUsage;
+}
+
+export function createDrmGpuCollector(
+  fs: Pick<LinuxFs, "list" | "read" | "readlink"> = realLinuxFs,
+  now: () => number = Date.now,
+): DrmGpuCollector {
+  let state: DrmEngineState | null = null;
+  let knownPids: number[] = [];
+  let lastFullScanAt = 0;
+  let memo: { at: number; usage: DrmUsage } | null = null;
+
+  return {
+    usage(): DrmUsage {
+      const at = now();
+      if (memo && at - memo.at < DRM_MEMO_MS) return memo.usage;
+
+      const full = knownPids.length === 0 || at - lastFullScanAt >= DRM_RESCAN_MS;
+      const clients = collectDrmClients(fs, full ? undefined : knownPids);
+      if (full) {
+        lastFullScanAt = at;
+        knownPids = [...new Set(clients.map((c) => c.pid))];
+      }
+
+      const atSec = at / 1000;
+      const usage = computeDrmUsage(state, clients, atSec);
+      state = toEngineState(clients, atSec);
+      memo = { at, usage };
+      return usage;
+    },
+  };
+}

package/src/services/system-metrics/hardware-inventory.ts

@@ -0,0 +1,50 @@
+/**
+ * Static hardware facts, served by `GET /api/system/hardware` instead of riding
+ * every 2 s snapshot: a drive's model and capacity do not change, and sending
+ * them 1800 times an hour over a tunnel would be the largest part of the frame.
+ *
+ * Async only because the OpenGL/Vulkan versions come from a one-shot tool; that
+ * result is cached for the process lifetime, so every call after the first is
+ * a handful of small sysfs and udev reads with no cache and no subprocess — a
+ * drive plugged in is visible on the client's next refetch rather than after a TTL.
+ */
+import type { HardwareInventory } from "../../types/system-hardware.ts";
+import type { MetricsPlatform } from "../../types/system-metrics.ts";
+import { toMetricsPlatform } from "./system-metrics-platform.ts";
+import { readDiskInventory } from "./disk-inventory-linux.ts";
+import { attachPartitionUsage } from "./partitions-linux.ts";
+import { readNicInventory } from "./net-inventory-linux.ts";
+import { readCpuInfo } from "./cpu-details-linux.ts";
+import { readMemoryInfo } from "./memory-linux.ts";
+import { listGpuCards, readGpuInfo } from "./gpu-devices-linux.ts";
+import { createGpuApiVersionReader, type GpuApiVersionReader } from "./gpu-api-versions.ts";
+import { realLinuxFs } from "./linux-fs.ts";
+
+const apiVersions = createGpuApiVersionReader();
+
+/** Windows and macOS report no devices yet; the client hides the sections rather
+ *  than showing empty ones, exactly as it does for a host with no GPU. */
+export async function readHardwareInventory(
+  platform: MetricsPlatform = toMetricsPlatform(),
+  now: () => number = Date.now,
+  api: GpuApiVersionReader = apiVersions,
+): Promise<HardwareInventory> {
+  const base = { platform, ts: now(), disks: [], nics: [], gpus: [] } satisfies HardwareInventory;
+  if (platform !== "linux") return base;
+
+  const cpu = readCpuInfo();
+  const versions = await api.read();
+  // statfs per mount, off the event loop and in parallel — see partitions-linux.
+  const disks = readDiskInventory();
+  await attachPartitionUsage(disks);
+  return {
+    ...base,
+    disks,
+    nics: readNicInventory(),
+    memory: readMemoryInfo(),
+    // NVIDIA is deliberately included here: the static facts (name, PCIe link)
+    // come from sysfs for every driver, even where the live figures do not.
+    gpus: listGpuCards(realLinuxFs).map((card) => readGpuInfo(card, versions, realLinuxFs)),
+    ...(cpu ? { cpu } : {}),
+  };
+}