@wenathlan/saddle 2.0.154 → 2.0.159

package/dist/virtualgpu.d.ts

@@ -1,344 +0,0 @@
-/**
- * virtualgpu - physical gpu virtualization: passthrough, vgpu slicing, MIG
- * layouts and the verified gpu identity bank.
- *
- * This module owns the physical side of gpu virtualization. It absorbs the
- * gpu-passthrough module in full (vfio bind/unbind through driverctl with
- * the new_id fallback, vbios rom dumping from sysfs, the Looking Glass B7
- * IVshmem recipe, the NVIDIA vGPU profile-size formula, the vendor-reset
- * family list and the Intel SR-IOV DKMS parameters), the v2 stub
- * (nvmlMockEnv and the pciIds table, corrected against the v5 sources) and
- * a TS mirror of the C++ virtualization core data: the vgpu slice profile
- * table (B100-1Q through RX9070XT-4Q), the Blackwell MIG layout catalog
- * with the 7c/192GB density validator, the static spec database (GB100,
- * GB202, GB203, Navi48, Navi44) and the NVENC dual-engine throughput table.
- *
- * The verified bank embeds seven real identities confirmed on 2026-08-22
- * against vendor pages, TechPowerUp and the PCI id databases: RTX 5090
- * (10DE:2B85, 32 GB GDDR7), RTX PRO 6000 Blackwell (10DE:26B5, 96 GB GDDR7
- * ECC, 24064 CUDA cores), B200 (10DE:2665, 192 GB HBM3e at 8 TB/s), H100
- * (10DE:2330, 80 GB HBM3), A100 (10DE:20B0, 40 GB HBM2e), RX 9070 XT
- * (1002:748E, 16 GB GDDR6) and Instinct MI350X (1002:75A0, 288 GB HBM3e).
- * The legacy 10DE:2BB5 spelling for the RTX PRO 6000 found in the v4
- * sources is wrong; the verified id is 26B5 and the divergence is recorded
- * here for traceability.
- *
- * Data for the extra identities discovered in the Meta jsons (B100
- * 10DE:2664, GB200 superchip, RTX 5070, RX 8900 XTX, Arc B770 and the RDNA
- * APU family) stays in the json data files (gpus.json, processors.json);
- * this module only ships the logic: the registry, the fluent builder, the
- * factory and the registergpudata normalizer that turns a json record into
- * a bank entry.
- *
- * Domain split: render.ts keeps the software identity stack (Mesa, the
- * nvidia-smi); virtualmemory.ts keeps the guest MIG slicing profiles
- * (1g.24gb, 2g.48gb, 4g.96gb) which this module imports to compose the
- * complete catalog; virtualization.ts re-exports the passthrough helpers
- * for the QEMU command line.
- *
- * Contexts (25): gpuerror, pciids, nvmlmockenv, virtualgpuspec, gpubank,
- * smidriveranchor, bindvfio, unbindvfio, romdump, lookingglassb7,
- * nvidiavgpuprofiles, vendorresetfamilies, intelsriovdkms, vgpuprofiles,
- * miglayoutblackwell, validatedensity, composemigcatalog, gpustaticspecs,
- * nvencdualengine, nvencsessiontable, nvencCanFit, gpuregistry,
- * virtualgpubuilder, registergpudata, createvirtualgpu.
- *
- * Patterns: registry (gpuregistry), builder (virtualgpubuilder), factory
- * (createvirtualgpu), normalizer (registergpudata).
- * Rules: lowercase identifiers, english jsdoc, third person, no emoji,
- * try/catch catcher on every fallible path, node:* built-ins only, and no
- * hardcoded localhost address anywhere.
- */
-/** Error thrown by every virtualgpu subsystem with an optional cause chain. */
-export declare class gpuerror extends Error {
-    /** Machine readable subsystem tag. */
-    readonly subsystem: string;
-    constructor(message: string, options?: {
-        cause?: Error;
-        subsystem?: string;
-    });
-}
-/**
- * Canonical PCI ids of the verified bank, keyed by registry name. The
- * RTX PRO 6000 entry uses 26B5 as confirmed in the v5 research; the 2BB5
- * value found in the v4 nested_gpu.json is a transcription error and is
- * intentionally not reproduced.
- */
-export declare const pciIds: {
-    readonly rtx5090: '10DE:2B85';
-    readonly rtxpro6000: '10DE:26B5';
-    readonly b200: '10DE:2665';
-    readonly h100: '10DE:2330';
-    readonly a100: '10DE:20B0';
-    readonly rx9070xt: '1002:748E';
-    readonly mi350x: '1002:75A0';
-};
-/**
- * NVIDIA driver and CUDA anchor shared by the smi-adapter header and the nvenc
- * engine description (v2 anchor; supersedes the 560.35.03 and 580.82.07
- * strings found in the older sources).
- */
-export declare const smidriveranchor: {
-    readonly driver: '575.57.08';
-    readonly cuda: '12.9';
-};
-/**
- * Builds the NVML mock environment consumed by the virtual nvidia-smi adapter
- * emulator and the nvml-unified-shim (their documented interface): FAKE_VRAM pins the reported memory in
- * MiB and FAKE_MODEL pins the reported device name.
- */
-export declare function nvmlMockEnv(vrammib: number, model: string): Record<string, string>;
-/** Complete description of one physical gpu identity. */
-export type virtualgpuspec = {
-    readonly id: string;
-    readonly name: string;
-    readonly vendor: 'nvidia' | 'amd' | 'intel';
-    readonly pcivendor: string;
-    readonly pcidevice: string;
-    readonly vrammib: number;
-    readonly smireportedmib: number;
-    readonly memtype: string;
-    readonly busbits: number;
-    readonly bandwidthgbs: number;
-    readonly tdpwatts: number;
-    readonly arch: string;
-    readonly smarch: string;
-    readonly computeunits: number;
-    readonly smcount: number;
-    readonly mig: boolean;
-    readonly sriov: boolean;
-    readonly launch: string;
-};
-/**
- * The verified bank: seven real identities with every field cross-checked
- * on 2026-08-22. vrammib is the physical capacity and smireportedmib is the
- * value nvidia-smi and rocm-smi print after the firmware carveout.
- */
-export declare const GPU_BANK: readonly virtualgpuspec[];
-/** Renders the canonical "vendor:device" pci id of a bank entry. */
-export declare function fullpciid(spec: virtualgpuspec): string;
-/**
- * Binds a gpu to vfio-pci for passthrough. driverctl set-override is the
- * primary path; when it is unavailable the function falls back to the
- * vfio-pci new_id sysfs write. The returned plan carries the quirks the
- * passthrough research mandates: disable_idle_d3, pcie_port_pm off and the
- * lspci alive check that verifies the config header is not 0xFF.
- */
-export declare function bindVfio(bdf: string, vendorDevice: string): {
-    bdf: string;
-    driver: string;
-    disable_idle_d3: number;
-    pcie_port_pm: string;
-    aliveCheck: string;
-};
-/** Releases a gpu from vfio-pci back to its native driver. */
-export declare function unbindVfio(bdf: string): void;
-/**
- * Dumps the gpu vbios from sysfs for romfile passthrough. The rom is
- * enabled with echo 1, copied to the output path and disabled again; the
- * returned path feeds the QEMU romfile= option.
- */
-export declare function romDump(bdf: string, out?: string): string;
-/**
- * Looking Glass B7 guest display recipe: the kvmfr 0.0.12-7 module backs a
- * 128 MB ivshmem-plain device so the D12 host renderer can DMA frames with
- * zero CPU copies (300 UPS class latency), including the libvirt shmem xml.
- */
-export declare function lookingGlassB7(): {
-    version: string;
-    kvmfr: string;
-    ivshmem: string;
-    backend: string;
-    dma: string;
-    indirectCopy: boolean;
-    xml: string;
-};
-/**
- * NVIDIA vGPU profile-size formula as documented by the vgpu-unlock
- * research: profileSize equals X times 0x40000000 (1 GB units), the
- * framebuffer reservation is 0x8000000 plus one sixteenth of the excess
- * over the first gigabyte, and the usable framebuffer never drops below
- * 384 MiB. The example computes the X=2 (2 GB) profile.
- */
-export declare function nvidiaVgpuProfiles(): {
-    formula: string;
-    min: string;
-    example: {
-        profileSize: number;
-        fbReservation: number;
-        fb: number;
-    };
-};
-/**
- * GPU families supported by the vendor-reset module: the reset quirk list
- * covering Polaris through Navi 48 plus the Rembrandt iGPU and the 5600 XT
- * exception, required to recover amdgpu devices stuck in a bad state
- * before rebinding them to vfio-pci.
- */
-export declare function vendorResetFamilies(): readonly string[];
-/**
- * Intel SR-IOV DKMS package and kernel parameters for the Xe and i915
- * stacks: i915-sriov-dkms 2026.02.09 with i915.enable_guc=3 and up to 7
- * VFs, or the xe driver with xe.force_probe=0xa7a0 for Battlemage.
- */
-export declare function intelSriovDkms(): {
-    pkg: string;
-    kernel: string;
-    xe: string;
-    maxVfs: number;
-};
-/** One time-sliced vgpu profile as scheduled by the C++ VgpuScheduler. */
-export type vgpuprofile = {
-    readonly id: string;
-    readonly vrammb: number;
-    readonly maxinstances: number;
-    readonly encodersessions: number;
-    readonly decodersessions: number;
-    readonly weight: number;
-    readonly flavor: 'vgpu' | 'sriov';
-};
-/**
- * vgpu slice catalog: NVIDIA B100 quarter profiles (1Q through 8Q), the
- * GB202 consumer slices for RTX 5090 class boards and the AMD MxGPU
- * SR-IOV slices for RX 9070 XT (Navi 48). Instances attach through the
- * mdev_supported_types sysfs interface.
- */
-export declare const VGPUPROFILES: readonly vgpuprofile[];
-/** Resolves a vgpu slice profile by id, throwing for unknown names. */
-export declare function getvgpuprofile(id: string): vgpuprofile;
-/** One Blackwell MIG layout entry (MIG 2.0, up to 7 compute instances). */
-export type miglayout = {
-    readonly profile: string;
-    readonly computeslices: number;
-    readonly memorymb: number;
-    readonly hbmgb: number;
-    readonly smcount: number;
-    readonly decoders: number;
-    readonly encoders: number;
-    readonly maxinstances: number;
-    readonly mdev: string;
-    readonly c2ccoherent: boolean;
-};
-/**
- * Blackwell B100 MIG layout catalog (192 GB HBM3e, 8 TB/s): eight profiles
- * from 1g.12gb (14 SMs, 7 instances) to the monolithic 7g.192gb (192 SMs),
- * each mapped to its compatible mdev type so vgpu and MIG compose.
- */
-export declare const MIGLAYOUTBLACKWELL: readonly miglayout[];
-/**
- * Validates that a requested MIG instance set does not oversubscribe the
- * Blackwell physical limits: at most 7 compute slices and at most 192 GB of
- * HBM3e in aggregate.
- */
-export declare function validatedensity(requested: readonly miglayout[]): boolean;
-/**
- * Composes the complete MIG catalog visible to planners: the guest-side
- * VRAM slicing profiles owned by virtualmemory.ts (1g.24gb, 2g.48gb and
- * 4g.96gb on the 96 GB virtual device) plus the host-side Blackwell
- * layouts mirrored above.
- */
-export declare function composemigcatalog(): readonly string[];
-/** Static silicon facts of one gpu architecture (mirror of the C++ db). */
-export type gpustaticspec = {
-    readonly arch: string;
-    readonly vendor: 'nvidia' | 'amd';
-    readonly marketingname: string;
-    readonly smorcu: number;
-    readonly busbits: number;
-    readonly bandwidthgbps: number;
-    readonly tdpwatts: number;
-    readonly encoders: number;
-    readonly decoders: number;
-    readonly mig: boolean;
-    readonly sriov: boolean;
-    readonly maxvgpuinstances: number;
-    readonly wgps?: number;
-    readonly aiaccelerators?: number;
-    readonly mediaengine: string;
-};
-/**
- * Static spec database mirrored from the C++ virtualization core. GB100 is
- * the 168 SM datacenter die with 8192-bit HBM3e at 8 TB/s; GB202 is the
- * 170 SM consumer die with 512-bit GDDR7 at 1792 GB/s; Navi 48 carries 64
- * CUs organized as 32 WGPs with 128 AI accelerators on VCN 5.0.
- */
-export declare const GPUSTATICSPECS: readonly gpustaticspec[];
-/** Throughput contract of the B100 dual NVENC engines (SDK 13.0 data). */
-export declare const NVENCDUALENGINE: {
-    readonly totalmpixpersec: 1600;
-    readonly perenginempix: 800;
-    readonly engines: 2;
-};
-/** One codec session limit row of the dual-engine table. */
-export type nvencsession = {
-    readonly codec: 'h264' | 'hevc' | 'av1';
-    readonly maxwidth: number;
-    readonly maxheight: number;
-    readonly maxfps: number;
-    readonly mpixpersec: number;
-    readonly hdr10: boolean;
-    readonly splitframe: boolean;
-};
-/** Session table: 8K60 ceilings per codec with HDR10 and split-frame. */
-export declare function nvencsessiontable(): readonly nvencsession[];
-/**
- * Checks whether a resolution at a frame rate (and session count) fits
- * within the 1600 MPix/s aggregate budget of the dual engines.
- */
-export declare function nvencCanFit(w: number, h: number, fps: number, sessions?: number): boolean;
-/** Human readable engine description pinned to the v2 driver anchor. */
-export declare function nvencdescribe(): string;
-/**
- * Registry of gpu identities. Seeded with the verified GPU_BANK and
- * extensible at runtime; the Meta json identities (B100, GB200, RTX 5070,
- * RX 8900 XTX, Arc B770, RDNA APUs) register here after being loaded from
- * their json data files.
- */
-export declare const gpuregistry: ReadonlyMap<string, virtualgpuspec>;
-/** Lists every registered gpu identity id in registry order. */
-export declare function listgpus(): readonly string[];
-/** Resolves a gpu identity by id, throwing with the known ids on miss. */
-export declare function getgpu(id: string): virtualgpuspec;
-/**
- * Normalizes a loose json record from the data files (gpus.json,
- * processors.json) into a bank-grade virtualgpuspec and registers it. This
- * is the logic half of the Meta identities: the numbers live in the jsons,
- * this function only maps shapes. Accepted key spellings cover both the
- * v5 schema (pciId as "vendor:device", memoryGB, vramGb, memoryBandwidthGBs,
- * tdpW, cudaCores) and the Meta schema (vram_gb, bandwidth_gbs, tdp_w,
- * cuCount, streamProcessors).
- */
-export declare function registergpudata(record: Record<string, unknown>): virtualgpuspec;
-/**
- * Fluent builder for custom gpu identities. The builder starts from the
- * RTX 5090 baseline, collects overrides through chainable with* methods
- * and freezes the result into the registry.
- */
-export declare class virtualgpubuilder {
-    #private;
-    constructor();
-    /** Sets the registry id and display name. */
-    withid(id: string, name: string): this;
-    /** Sets the vendor and the pci vendor id that matches it. */
-    withvendor(vendor: virtualgpuspec['vendor']): this;
-    /** Sets the pci device id; must be exactly 4 hex digits. */
-    withpcidevice(device: string): this;
-    /** Sets the memory geometry: capacity, type, bus width and bandwidth. */
-    withmemory(vrammib: number, memtype: string, busbits: number, bandwidthgbs: number): this;
-    /** Sets power and architecture strings. */
-    withpower(tdpwatts: number, arch: string): this;
-    /** Sets compute topology and the virtualization capabilities. */
-    withcompute(computeunits: number, smcount: number, smarch: string, mig: boolean, sriov: boolean): this;
-    /** Validates the accumulated fields and freezes the identity. */
-    build(): virtualgpuspec;
-}
-/**
- * Factory that materializes a bank identity together with its NVML mock
- * environment: one call resolves the registry entry and pins the FAKE_VRAM
- * and FAKE_MODEL variables the smi adapter emulators read.
- */
-export declare function createvirtualgpu(id: string): {
-    spec: virtualgpuspec;
-    pciid: string;
-    nvmlenv: Record<string, string>;
-};