engine

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 1, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	FailureModeHealthy          = "healthy"
	FailureModeLost             = "lost"
	FailureModeFallenOffBus     = "fallen_off_bus"
	FailureModeECCUncorrectable = "ecc_uncorrectable"
)

Failure mode constants used by FailureInjectionConfig.Mode. Anything else (including the empty string) is treated as "healthy" — i.e. failure injection disabled for the device.

View Source 
const (
	FabricStateNotSupported uint8 = 0
	FabricStateNotStarted   uint8 = 1
	FabricStateInProgress   uint8 = 2
	FabricStateCompleted    uint8 = 3
)

FabricState* values mirror NVML_GPU_FABRIC_STATE_* from the public NVML header. We re-declare them here so the engine layer never has to pull in CGo and so that callers (and tests) can compare against named constants instead of magic numbers.

View Source 
const (
	// EnvFabricStateDir activates fabric-state coupling and locates the
	// fabricmanager readiness marker directory.
	EnvFabricStateDir = "MOCK_FABRICMANAGER_STATE_DIR"

	// FabricReadyMarker is the node-local readiness file the fake
	// fabricmanager daemon writes on startup and removes on shutdown.
	FabricReadyMarker = "fabricmanager.ready"
)

Fabric-state coupling (decision D-a). A GPU whose configured fabric state is "auto" mirrors the fake fabricmanager's readiness:

  • Coupling is OFF unless EnvFabricStateDir is set (fabricmanager enabled, wired by setup.sh / the Helm DaemonSet). With coupling off, "auto" resolves to COMPLETED so single-node and ComputeDomain behavior (#304/#342) is unchanged — there is no regression when fabricmanager is disabled.
  • With coupling on, "auto" is COMPLETED only once the fabricmanager daemon has written its readiness marker, otherwise IN_PROGRESS.

The marker is read through a short-TTL cache so the hot NVML getters never stat() the filesystem per call (the trap BALTHASAR flagged on CASPER's original design).

View Source 
const (
	// DefaultCoresPerNUMA synthesizes a CPU affinity set when a profile
	// declares NUMA nodes but no explicit cpu_affinity range.
	DefaultCoresPerNUMA = 64

	// DefaultNVLinkDutyCycle is the fraction of line rate accrued into the
	// utilization counters when the profile does not set one. A small
	// positive value makes counters visibly grow between samples.
	DefaultNVLinkDutyCycle = 0.05
)
View Source 
const DefaultBAR1SizeMB = 256

DefaultBAR1SizeMB is the default simulated BAR1 aperture size in megabytes.

View Source 
const MaxDevices = 8

MaxDevices is the maximum number of devices supported by the mock server.

Variables

View Source 
var InvalidDeviceInstance nvml.Device = newInvalidDevice()

InvalidDeviceInstance is the singleton returned for failed device lookups

Functions

func ClearConfigCache 

func ClearConfigCache()

ClearConfigCache clears the cached configuration. Use in tests to ensure clean state between test runs.

func CompareDriverVersions 

func CompareDriverVersions(a, b string) int

CompareDriverVersions compares two NVIDIA driver version strings. Returns -1 if a < b, 0 if a == b, 1 if a > b. Supports formats: "550", "550.163", "550.163.01"

func ConfigOverridePathFor added in v0.3.0 

func ConfigOverridePathFor(configPath string) string

ConfigOverridePathFor resolves the runtime overrides file path from the resolved config path. MOCK_NVML_OVERRIDES wins; otherwise overrides.yaml sits next to config.yaml. Returns "" when no config path is known.

func FunctionAvailable 

func FunctionAvailable(funcName, driverVersion string) bool

FunctionAvailable returns true if the named function exists in the given driver version. Unknown functions default to available (backwards compatibility).

func GetFunctionRegistry 

func GetFunctionRegistry() map[string]FunctionVersion

GetFunctionRegistry returns a copy of the function version registry.

func GpmMetricsGet added in v0.3.0 

func GpmMetricsGet(key1, key2 uint64, ids []uint32) ([]float64, []nvml.Return, nvml.Return)

GpmMetricsGet computes the requested metrics from two samples. It returns one value and one per-metric status per requested id; the overall call succeeds as long as the sample handles are valid (per-metric errors mirror real NVML, which reports unknown ids in metrics[i].nvmlReturn).

func GpmSampleAlloc added in v0.3.0 

func GpmSampleAlloc() uint64

GpmSampleAlloc registers a new sample buffer and returns its registry key.

func GpmSampleFree added in v0.3.0 

func GpmSampleFree(key uint64) bool

GpmSampleFree releases a sample buffer. Unknown keys report false so the bridge can return INVALID_ARGUMENT (double free / never allocated).

func ParsePCIBusID 

func ParsePCIBusID(busID string) (domain, bus, device, function uint32, err error)

ParsePCIBusID parses a PCI bus ID string into its components. Accepts formats: "DDDD:BB:DD.F" or "BB:DD.F" where D=domain, B=bus, D=device, F=function. Returns error if format is invalid.

func ResetForTesting 

func ResetForTesting()

ResetForTesting resets the engine singleton for testing purposes. This clears all cached state including config cache. WARNING: Only use in tests! Not thread-safe during concurrent access.

Types

type AccountingConfig 

type AccountingConfig struct {
	Mode       string `json:"mode,omitempty"`
	BufferSize int    `json:"buffer_size,omitempty"`
}

AccountingConfig defines accounting mode settings

type BAR1MemoryConfig 

type BAR1MemoryConfig struct {
	TotalBytes uint64 `json:"total_bytes"`
	FreeBytes  uint64 `json:"free_bytes,omitempty"`
	UsedBytes  uint64 `json:"used_bytes,omitempty"`
}

BAR1MemoryConfig defines BAR1 aperture settings

type ClocksConfig 

type ClocksConfig struct {
	GraphicsCurrent    uint32 `json:"graphics_current,omitempty"`
	GraphicsMax        uint32 `json:"graphics_max,omitempty"`
	GraphicsApp        uint32 `json:"graphics_app,omitempty"`
	GraphicsAppDefault uint32 `json:"graphics_app_default,omitempty"`
	SMCurrent          uint32 `json:"sm_current,omitempty"`
	SMMax              uint32 `json:"sm_max,omitempty"`
	MemoryCurrent      uint32 `json:"memory_current,omitempty"`
	MemoryMax          uint32 `json:"memory_max,omitempty"`
	MemoryApp          uint32 `json:"memory_app,omitempty"`
	MemoryAppDefault   uint32 `json:"memory_app_default,omitempty"`
	VideoCurrent       uint32 `json:"video_current,omitempty"`
	VideoMax           uint32 `json:"video_max,omitempty"`
}

ClocksConfig defines clock speed settings

type ClocksThrottleReasonsConfig 

type ClocksThrottleReasonsConfig struct {
	GPUIdle                   bool `json:"gpu_idle,omitempty"`
	ApplicationsClocksSetting bool `json:"applications_clocks_setting,omitempty"`
	SWPowerCap                bool `json:"sw_power_cap,omitempty"`
	HWSlowdown                bool `json:"hw_slowdown,omitempty"`
	HWThermalSlowdown         bool `json:"hw_thermal_slowdown,omitempty"`
	HWPowerBrakeSlowdown      bool `json:"hw_power_brake_slowdown,omitempty"`
	SyncBoost                 bool `json:"sync_boost,omitempty"`
	SWThermalSlowdown         bool `json:"sw_thermal_slowdown,omitempty"`
	DisplayClocksSetting      bool `json:"display_clocks_setting,omitempty"`
}

ClocksThrottleReasonsConfig defines throttle reason flags

type ComputeCapabilityConfig 

type ComputeCapabilityConfig struct {
	Major int `json:"major"`
	Minor int `json:"minor"`
}

ComputeCapabilityConfig defines CUDA compute capability

type Config 

type Config struct {
	NumDevices    int
	DriverVersion string

	// YAMLConfig holds the parsed YAML configuration (nil if not using YAML)
	YAMLConfig *YAMLConfig
}

Config holds configuration for the mock engine

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the default configuration

func LoadConfig 

func LoadConfig() *Config

LoadConfig loads configuration from YAML file (if specified) or environment variables. Results are cached - subsequent calls with the same config path return cached config.

Config resolution order:

  1. MOCK_NVML_CONFIG env var (explicit path)
  2. Auto-discover from /proc/self/maps (Linux only)
  3. Fall back to env vars / defaults

func (*Config) GetDeviceConfig 

func (c *Config) GetDeviceConfig(index int) *DeviceConfig

GetDeviceConfig returns the device configuration for a specific index, merging defaults with per-device overrides

func (*Config) GetDeviceMinorNumber 

func (c *Config) GetDeviceMinorNumber(index int) int

GetDeviceMinorNumber returns the minor number for a specific device index

func (*Config) GetDevicePCIBusID 

func (c *Config) GetDevicePCIBusID(index int) string

GetDevicePCIBusID returns the PCI bus ID for a specific device index

func (*Config) GetDeviceUUID 

func (c *Config) GetDeviceUUID(index int) string

GetDeviceUUID returns the UUID for a specific device index

type ConfigOverrideDoc added in v0.3.0 

type ConfigOverrideDoc struct {
	Version int                       `json:"version,omitempty"`
	All     map[string]any            `json:"all,omitempty"`
	Devices map[string]map[string]any `json:"devices,omitempty"`
}

ConfigOverrideDoc is the runtime override document written by nvml-mock-ctl and read by the engine. It is intentionally schema-light: All and per-device patches are generic maps deep-merged over the pristine DeviceConfig, so any config field is controllable without per-field plumbing.

func ParseConfigOverride added in v0.3.0 

func ParseConfigOverride(data []byte) (*ConfigOverrideDoc, error)

ParseConfigOverride strictly parses config override bytes. Empty/whitespace input returns (nil, nil) so an absent or empty config override is treated as "no overrides".

func (*ConfigOverrideDoc) DeviceConfigOverride added in v0.3.0 

func (o *ConfigOverrideDoc) DeviceConfigOverride(index int) map[string]any

DeviceConfigOverride returns the deep-merged patch for a device index: All first, then the per-index entry (which wins). Returns nil when neither is present.

type ConfigurableDevice 

type ConfigurableDevice struct {
	*dgxa100.Device
	// contains filtered or unexported fields
}

ConfigurableDevice wraps dgxa100.Device and adds YAML-based configuration support

func NewConfigurableDevice 

func NewConfigurableDevice(index int, baseDevice *mockserver.Device, config *DeviceConfig, uuid string, pciBusID string, minorNumber int, fabric *NodeFabric) *ConfigurableDevice

NewConfigurableDevice creates a device with YAML configuration. The shared, immutable *NodeFabric carries the node-level NVLink / PCIe / affinity topology; this device only needs its own index to derive its per-device view. fabric may be nil (legacy/default mode) in which case the NVLink and topology getters fall back to per-device defaults.

func (*ConfigurableDevice) FreezeNvLinkUtilizationCounter added in v0.3.0 

func (d *ConfigurableDevice) FreezeNvLinkUtilizationCounter(link, counter int, freeze nvml.EnableState) nvml.Return

FreezeNvLinkUtilizationCounter is a no-op success: the counters are a pure function of time, so there is no mutable state to freeze.

func (*ConfigurableDevice) GetAccountingBufferSize 

func (d *ConfigurableDevice) GetAccountingBufferSize() (int, nvml.Return)

GetAccountingBufferSize returns accounting buffer size

func (*ConfigurableDevice) GetAccountingMode 

func (d *ConfigurableDevice) GetAccountingMode() (nvml.EnableState, nvml.Return)

GetAccountingMode returns accounting mode

func (*ConfigurableDevice) GetApplicationsClock 

func (d *ConfigurableDevice) GetApplicationsClock(clockType nvml.ClockType) (uint32, nvml.Return)

GetApplicationsClock returns application clock settings

func (*ConfigurableDevice) GetArchitecture 

func (d *ConfigurableDevice) GetArchitecture() (nvml.DeviceArchitecture, nvml.Return)

GetArchitecture returns GPU architecture

func (*ConfigurableDevice) GetAutoBoostedClocksEnabled 

func (d *ConfigurableDevice) GetAutoBoostedClocksEnabled() (nvml.EnableState, nvml.EnableState, nvml.Return)

GetAutoBoostedClocksEnabled returns auto-boost status. Datacenter GPUs (A100, H100, etc.) don't support auto-boost.

func (*ConfigurableDevice) GetBAR1MemoryInfo 

func (d *ConfigurableDevice) GetBAR1MemoryInfo() (nvml.BAR1Memory, nvml.Return)

GetBAR1MemoryInfo returns BAR1 memory information

func (*ConfigurableDevice) GetBoardId 

func (d *ConfigurableDevice) GetBoardId() (uint32, nvml.Return)

GetBoardId returns the board ID

func (*ConfigurableDevice) GetBoardPartNumber 

func (d *ConfigurableDevice) GetBoardPartNumber() (string, nvml.Return)

GetBoardPartNumber returns the board part number

func (*ConfigurableDevice) GetBrand 

func (d *ConfigurableDevice) GetBrand() (nvml.BrandType, nvml.Return)

GetBrand returns device brand

func (*ConfigurableDevice) GetClockInfo 

func (d *ConfigurableDevice) GetClockInfo(clockType nvml.ClockType) (uint32, nvml.Return)

GetClockInfo returns current clock frequencies

func (*ConfigurableDevice) GetComputeMode 

func (d *ConfigurableDevice) GetComputeMode() (nvml.ComputeMode, nvml.Return)

GetComputeMode returns compute mode

func (*ConfigurableDevice) GetComputeRunningProcesses 

func (d *ConfigurableDevice) GetComputeRunningProcesses() ([]nvml.ProcessInfo, nvml.Return)

GetComputeRunningProcesses returns running compute processes

func (*ConfigurableDevice) GetConfig 

func (d *ConfigurableDevice) GetConfig() *DeviceConfig

GetConfig returns the device configuration

func (*ConfigurableDevice) GetCpuAffinity added in v0.3.0 

func (d *ConfigurableDevice) GetCpuAffinity(cpuSetSize int) ([]uint, nvml.Return)

GetCpuAffinity returns the device's CPU affinity bitmask packed into cpuSetSize machine words. Reports ERROR_NOT_SUPPORTED without topology. The signature matches nvml.Device so it overrides the embedded stub.

func (*ConfigurableDevice) GetCpuAffinityWithinScope added in v0.3.0 

func (d *ConfigurableDevice) GetCpuAffinityWithinScope(cpuSetSize int, scope nvml.AffinityScope) ([]uint, nvml.Return)

GetCpuAffinityWithinScope returns the CPU affinity bitmask for a scope. The mock does not distinguish socket vs node scope, so both return the device's NUMA CPU set.

func (*ConfigurableDevice) GetCudaComputeCapability 

func (d *ConfigurableDevice) GetCudaComputeCapability() (int, int, nvml.Return)

GetCudaComputeCapability returns CUDA compute capability

func (*ConfigurableDevice) GetCurrPcieLinkGeneration 

func (d *ConfigurableDevice) GetCurrPcieLinkGeneration() (int, nvml.Return)

GetCurrPcieLinkGeneration returns current PCIe link generation

func (*ConfigurableDevice) GetCurrPcieLinkWidth 

func (d *ConfigurableDevice) GetCurrPcieLinkWidth() (int, nvml.Return)

GetCurrPcieLinkWidth returns current PCIe link width

func (*ConfigurableDevice) GetCurrentClocksEventReasons 

func (d *ConfigurableDevice) GetCurrentClocksEventReasons() (uint64, nvml.Return)

GetCurrentClocksEventReasons returns clock event reasons bitmask (newer API name for throttle reasons)

func (*ConfigurableDevice) GetCurrentClocksThrottleReasons 

func (d *ConfigurableDevice) GetCurrentClocksThrottleReasons() (uint64, nvml.Return)

GetCurrentClocksThrottleReasons returns clock throttle reasons bitmask

func (*ConfigurableDevice) GetDecoderUtilization 

func (d *ConfigurableDevice) GetDecoderUtilization() (uint32, uint32, nvml.Return)

GetDecoderUtilization returns decoder utilization

func (*ConfigurableDevice) GetDefaultApplicationsClock 

func (d *ConfigurableDevice) GetDefaultApplicationsClock(clockType nvml.ClockType) (uint32, nvml.Return)

GetDefaultApplicationsClock returns default application clock settings

func (*ConfigurableDevice) GetDefaultEccMode 

func (d *ConfigurableDevice) GetDefaultEccMode() (nvml.EnableState, nvml.Return)

GetDefaultEccMode returns the default ECC mode.

func (*ConfigurableDevice) GetDetailedEccErrors 

func (d *ConfigurableDevice) GetDetailedEccErrors(errorType nvml.MemoryErrorType, counterType nvml.EccCounterType) (nvml.EccErrorCounts, nvml.Return)

GetDetailedEccErrors returns per-location ECC error counts.

func (*ConfigurableDevice) GetDisplayActive 

func (d *ConfigurableDevice) GetDisplayActive() (nvml.EnableState, nvml.Return)

GetDisplayActive returns display active status

func (*ConfigurableDevice) GetDisplayMode 

func (d *ConfigurableDevice) GetDisplayMode() (nvml.EnableState, nvml.Return)

GetDisplayMode returns display mode

func (*ConfigurableDevice) GetEccMode 

func (d *ConfigurableDevice) GetEccMode() (nvml.EnableState, nvml.EnableState, nvml.Return)

GetEccMode returns ECC mode status

func (*ConfigurableDevice) GetEncoderCapacity 

func (d *ConfigurableDevice) GetEncoderCapacity(encoderType nvml.EncoderType) (int, nvml.Return)

GetEncoderCapacity returns encoder capacity

func (*ConfigurableDevice) GetEncoderSessions 

func (d *ConfigurableDevice) GetEncoderSessions() ([]nvml.EncoderSessionInfo, nvml.Return)

GetEncoderSessions returns encoder sessions

func (*ConfigurableDevice) GetEncoderStats 

func (d *ConfigurableDevice) GetEncoderStats() (int, uint32, uint32, nvml.Return)

GetEncoderStats returns encoder statistics

func (*ConfigurableDevice) GetEncoderUtilization 

func (d *ConfigurableDevice) GetEncoderUtilization() (uint32, uint32, nvml.Return)

GetEncoderUtilization returns encoder utilization

func (*ConfigurableDevice) GetEnforcedPowerLimit 

func (d *ConfigurableDevice) GetEnforcedPowerLimit() (uint32, nvml.Return)

GetEnforcedPowerLimit returns the enforced power limit

func (*ConfigurableDevice) GetFBCSessions 

func (d *ConfigurableDevice) GetFBCSessions() ([]nvml.FBCSessionInfo, nvml.Return)

GetFBCSessions returns FBC sessions

func (*ConfigurableDevice) GetFBCStats 

func (d *ConfigurableDevice) GetFBCStats() (nvml.FBCStats, nvml.Return)

GetFBCStats returns FBC statistics

func (*ConfigurableDevice) GetFanSpeed 

func (d *ConfigurableDevice) GetFanSpeed() (uint32, nvml.Return)

GetFanSpeed returns fan speed percentage

func (*ConfigurableDevice) GetFanSpeed_v2 

func (d *ConfigurableDevice) GetFanSpeed_v2(fan int) (uint32, nvml.Return)

GetFanSpeed_v2 returns fan speed for a specific fan

func (*ConfigurableDevice) GetFieldValue added in v0.3.0 

func (d *ConfigurableDevice) GetFieldValue(fieldID, scopeID uint32) (FieldValueType, uint64, nvml.Return)

GetFieldValue resolves a single nvmlDeviceGetFieldValues entry: device-scope fields first, then the NVLink field set. Unmodeled field ids yield (FieldValueUnsupported, 0, ERROR_NOT_SUPPORTED) so the bridge can mark just that entry unsupported while succeeding the overall call (matching real NVML semantics — DCGM renders such entries as blank, not as errors).

func (*ConfigurableDevice) GetGpmSupport 

func (d *ConfigurableDevice) GetGpmSupport() (uint32, nvml.Return)

GetGpmSupport returns whether GPM (GPU Performance Monitoring) is supported. Like real NVML, GPM is supported on Hopper and newer; DCGM's profiling module keys its NVML-GPM path (the only mockable profiling path — pre-Hopper profiling goes through driver-internal perfworks) off this answer. The architecture default can be overridden via the gpm.supported config knob.

func (*ConfigurableDevice) GetGpuOperationMode 

func (d *ConfigurableDevice) GetGpuOperationMode() (nvml.GpuOperationMode, nvml.GpuOperationMode, nvml.Return)

GetGpuOperationMode returns GPU operation mode

func (*ConfigurableDevice) GetGraphicsRunningProcesses 

func (d *ConfigurableDevice) GetGraphicsRunningProcesses() ([]nvml.ProcessInfo, nvml.Return)

GetGraphicsRunningProcesses returns running graphics processes

func (*ConfigurableDevice) GetGspFirmwareMode 

func (d *ConfigurableDevice) GetGspFirmwareMode() (bool, bool, nvml.Return)

GetGspFirmwareMode returns GSP firmware mode (isEnabled, defaultMode)

func (*ConfigurableDevice) GetGspFirmwareVersion 

func (d *ConfigurableDevice) GetGspFirmwareVersion() (string, nvml.Return)

GetGspFirmwareVersion returns the GSP firmware version string.

func (*ConfigurableDevice) GetIndex 

func (d *ConfigurableDevice) GetIndex() (int, nvml.Return)

GetIndex returns the device index

func (*ConfigurableDevice) GetInforomImageVersion 

func (d *ConfigurableDevice) GetInforomImageVersion() (string, nvml.Return)

GetInforomImageVersion returns InfoROM image version

func (*ConfigurableDevice) GetInforomVersion 

func (d *ConfigurableDevice) GetInforomVersion(object nvml.InforomObject) (string, nvml.Return)

GetInforomVersion returns InfoROM version

func (*ConfigurableDevice) GetMarginTemperature added in v0.3.0 

func (d *ConfigurableDevice) GetMarginTemperature() (nvml.MarginTemperature, nvml.Return)

GetMarginTemperature returns the GPU's headroom to its thermal limit in degrees C — the value nvidia-smi renders as "GPU T.Limit Temp" (via nvmlDeviceGetMarginTemperature). It is the slowdown threshold (falling back to shutdown, then max-operating) minus the current temperature. The margin is SIGNED and goes negative once the current temperature passes the limit, mirroring real T.Limit hardware; consumers such as NVSentinel's GpuThermalMarginWatch key on that sign crossing (it FAILs when the margin drops below the per-GPU slowdown offset), so the value is deliberately not clamped at 0. A thermal config is required; a lost/failing device propagates its error through GetTemperature so the margin reports N/A too. The signature matches the go-nvml Device interface so it overrides the embedded default.

func (*ConfigurableDevice) GetMaxClockInfo 

func (d *ConfigurableDevice) GetMaxClockInfo(clockType nvml.ClockType) (uint32, nvml.Return)

GetMaxClockInfo returns maximum clock frequencies

func (*ConfigurableDevice) GetMaxMigDeviceCount 

func (d *ConfigurableDevice) GetMaxMigDeviceCount() (int, nvml.Return)

GetMaxMigDeviceCount returns the maximum number of MIG devices

func (*ConfigurableDevice) GetMaxPcieLinkGeneration 

func (d *ConfigurableDevice) GetMaxPcieLinkGeneration() (int, nvml.Return)

GetMaxPcieLinkGeneration returns max PCIe link generation

func (*ConfigurableDevice) GetMaxPcieLinkWidth 

func (d *ConfigurableDevice) GetMaxPcieLinkWidth() (int, nvml.Return)

GetMaxPcieLinkWidth returns max PCIe link width

func (*ConfigurableDevice) GetMemoryAffinity added in v0.3.0 

func (d *ConfigurableDevice) GetMemoryAffinity(nodeSetSize int, scope nvml.AffinityScope) ([]uint, nvml.Return)

GetMemoryAffinity returns the device's memory (NUMA) affinity bitmask packed into nodeSetSize machine words.

func (*ConfigurableDevice) GetMemoryBusWidth 

func (d *ConfigurableDevice) GetMemoryBusWidth() (uint32, nvml.Return)

GetMemoryBusWidth returns the memory bus width in bits.

func (*ConfigurableDevice) GetMemoryErrorCounter 

func (d *ConfigurableDevice) GetMemoryErrorCounter(errorType nvml.MemoryErrorType, counterType nvml.EccCounterType, locationType nvml.MemoryLocation) (uint64, nvml.Return)

GetMemoryErrorCounter returns the per-location memory-error counter. Healthy devices report zero. ecc_uncorrectable mode reports the running call count for the uncorrected counter on device memory, mirroring the total error count so callers correlating the two queries see a consistent view.

func (*ConfigurableDevice) GetMemoryInfo 

func (d *ConfigurableDevice) GetMemoryInfo() (nvml.Memory, nvml.Return)

GetMemoryInfo returns GPU memory information

func (*ConfigurableDevice) GetMemoryInfo_v2 

func (d *ConfigurableDevice) GetMemoryInfo_v2() (nvml.Memory_v2, nvml.Return)

GetMemoryInfo_v2 returns GPU memory information (v2 API)

func (*ConfigurableDevice) GetMigDeviceHandleByIndex 

func (d *ConfigurableDevice) GetMigDeviceHandleByIndex(index int) (nvml.Device, nvml.Return)

GetMigDeviceHandleByIndex returns a MIG device handle by index. Returns NOT_FOUND when no MIG devices exist (MIG disabled or no instances). NOT_FOUND (vs NOT_SUPPORTED) signals "no device at this index" which callers like nvidia-device-plugin treat as end-of-iteration, not as a fatal error.

func (*ConfigurableDevice) GetMigMode 

func (d *ConfigurableDevice) GetMigMode() (int, int, nvml.Return)

GetMigMode returns MIG mode (current, pending)

func (*ConfigurableDevice) GetMinorNumber 

func (d *ConfigurableDevice) GetMinorNumber() (int, nvml.Return)

GetMinorNumber returns the device minor number

func (*ConfigurableDevice) GetMockFabricInfo added in v0.2.0 

func (d *ConfigurableDevice) GetMockFabricInfo() (FabricInfo, nvml.Return)

GetMockFabricInfo returns the v1 fabric information for this device. Returns ERROR_NOT_SUPPORTED when no FabricConfig is attached, matching real NVML behaviour on non-fabric-attached GPUs.

Named to avoid shadowing the embedded dgxa100.Device's interface method `GetGpuFabricInfo() (nvml.GpuFabricInfo, nvml.Return)` while still giving the bridge a single typed entry point.

func (*ConfigurableDevice) GetMockFabricInfoV added in v0.2.0 

func (d *ConfigurableDevice) GetMockFabricInfoV() (FabricInfo, nvml.Return)

GetMockFabricInfoV returns the versioned (v2/v3) fabric information for this device. The struct version selection happens in the bridge — the engine returns every field and lets the bridge zero out what the caller's selected version cannot represent.

Named to avoid shadowing the embedded dgxa100.Device's interface method `GetGpuFabricInfoV() GpuFabricInfoHandler`.

func (*ConfigurableDevice) GetMultiGpuBoard 

func (d *ConfigurableDevice) GetMultiGpuBoard() (int, nvml.Return)

GetMultiGpuBoard returns whether the device is on a multi-GPU board

func (*ConfigurableDevice) GetName added in v0.2.0 

func (d *ConfigurableDevice) GetName() (string, nvml.Return)

GetName returns the device name. Overrides the embedded dgxa100.Device implementation for the same reason as GetUUID — lost GPUs must propagate ERROR_GPU_IS_LOST from every device method.

func (*ConfigurableDevice) GetNumFans 

func (d *ConfigurableDevice) GetNumFans() (int, nvml.Return)

GetNumFans returns the number of fans

func (*ConfigurableDevice) GetNumaNodeId added in v0.3.0 

func (d *ConfigurableDevice) GetNumaNodeId() (int, nvml.Return)

GetNumaNodeId returns the device's NUMA node from the fabric. Reports ERROR_NOT_SUPPORTED when no pcie_topology facts are available.

func (*ConfigurableDevice) GetNvLinkCapability 

func (d *ConfigurableDevice) GetNvLinkCapability(link int, capability nvml.NvLinkCapability) (uint32, nvml.Return)

GetNvLinkCapability returns whether a capability bit is set for a link.

func (*ConfigurableDevice) GetNvLinkErrorCounter 

func (d *ConfigurableDevice) GetNvLinkErrorCounter(link int, counter nvml.NvLinkErrorCounter) (uint64, nvml.Return)

GetNvLinkErrorCounter returns the deterministic error counter for a link. Healthy links accrue at rate 0 (always 0); a configured error rate accrues monotonically against the shared epoch.

func (*ConfigurableDevice) GetNvLinkFieldValue added in v0.3.0 

func (d *ConfigurableDevice) GetNvLinkFieldValue(fieldID, scopeID uint32) (FieldValueType, uint64, nvml.Return)

GetNvLinkFieldValue resolves a single nvmlDeviceGetFieldValues entry for the NVLink field set off the immutable NodeFabric. It returns the union member the value occupies, the value (as raw bits in a uint64), and the per-field NVML return. Unmodeled field ids yield (FieldValueUnsupported, 0, ERROR_NOT_SUPPORTED) so the bridge can mark just that entry unsupported while still succeeding the overall call (matching real NVML semantics).

func (*ConfigurableDevice) GetNvLinkRemoteDeviceType added in v0.3.0 

func (d *ConfigurableDevice) GetNvLinkRemoteDeviceType(link int) (nvml.IntNvLinkDeviceType, nvml.Return)

GetNvLinkRemoteDeviceType returns the kind of device on the far end of a link (GPU, SWITCH for NVSwitch endpoints, or IBMNPU/UNKNOWN otherwise).

func (*ConfigurableDevice) GetNvLinkRemotePciInfo 

func (d *ConfigurableDevice) GetNvLinkRemotePciInfo(link int) (nvml.PciInfo, nvml.Return)

GetNvLinkRemotePciInfo returns PCI info for the remote device connected via NVLink, derived from the fabric's resolved per-device links.

func (*ConfigurableDevice) GetNvLinkState 

func (d *ConfigurableDevice) GetNvLinkState(link int) (nvml.EnableState, nvml.Return)

GetNvLinkState returns NvLink state for a specific link, derived from the node fabric's resolved per-device links.

func (*ConfigurableDevice) GetNvLinkUtilizationCounter added in v0.3.0 

func (d *ConfigurableDevice) GetNvLinkUtilizationCounter(link, counter int) (uint64, uint64, nvml.Return)

GetNvLinkUtilizationCounter returns the deterministic (rx, tx) utilization counters for a link. The values grow monotonically with wall-clock time and across separate processes (shared epoch).

func (*ConfigurableDevice) GetNvLinkVersion 

func (d *ConfigurableDevice) GetNvLinkVersion(link int) (uint32, nvml.Return)

GetNvLinkVersion returns the NvLink version for a link from the fabric.

func (*ConfigurableDevice) GetP2PStatus added in v0.3.0 

func (d *ConfigurableDevice) GetP2PStatus(other nvml.Device, _ nvml.GpuP2PCapsIndex) (nvml.GpuP2PStatus, nvml.Return)

GetP2PStatus reports the peer-to-peer status between this device and another for a given capability index.

On NVSwitch fabrics the per-link remote PCI is an opaque switch endpoint (a real GB200 reports FFFFFFFF:FF:FF.0 for every link), so a pair's NVLink connectivity cannot be matched via nvmlDeviceGetNvLinkRemotePciInfo. This getter answers whether P2P over NVLink is OK between the pair instead.

NOTE: the 580 nvidia-smi `topo -m` no longer calls this; it derives the NV# matrix from NVML_FI_DEV_NVSWITCH_CONNECTED_LINK_COUNT (field 147, see nvlink_fields.go). This remains implemented for the older binaries and any CUDA/NVML caller that probes P2P capability directly.

P2P is OK when the two devices are NVLink-connected in the immutable fabric model (NVLinkCount > 0), which already encodes the switch-fanned all-to-all connectivity (a100 -> NV12, h100/gb200/gb300 -> NV18). A device is trivially OK with itself. Otherwise the pair is not NVLink P2P capable.

func (*ConfigurableDevice) GetPciInfo 

func (d *ConfigurableDevice) GetPciInfo() (nvml.PciInfo, nvml.Return)

GetPciInfo returns PCI information for the device

func (*ConfigurableDevice) GetPcieReplayCounter 

func (d *ConfigurableDevice) GetPcieReplayCounter() (int, nvml.Return)

GetPcieReplayCounter returns PCIe replay counter

func (*ConfigurableDevice) GetPcieThroughput 

func (d *ConfigurableDevice) GetPcieThroughput(counter nvml.PcieUtilCounter) (uint32, nvml.Return)

GetPcieThroughput returns PCIe throughput

func (*ConfigurableDevice) GetPerformanceState 

func (d *ConfigurableDevice) GetPerformanceState() (nvml.Pstates, nvml.Return)

GetPerformanceState returns the current performance state

func (*ConfigurableDevice) GetPersistenceMode 

func (d *ConfigurableDevice) GetPersistenceMode() (nvml.EnableState, nvml.Return)

GetPersistenceMode returns persistence mode status

func (*ConfigurableDevice) GetPowerManagementDefaultLimit 

func (d *ConfigurableDevice) GetPowerManagementDefaultLimit() (uint32, nvml.Return)

GetPowerManagementDefaultLimit returns the default power limit

func (*ConfigurableDevice) GetPowerManagementLimit 

func (d *ConfigurableDevice) GetPowerManagementLimit() (uint32, nvml.Return)

GetPowerManagementLimit returns the power management limit in milliwatts

func (*ConfigurableDevice) GetPowerManagementLimitConstraints 

func (d *ConfigurableDevice) GetPowerManagementLimitConstraints() (uint32, uint32, nvml.Return)

GetPowerManagementLimitConstraints returns min/max power limits

func (*ConfigurableDevice) GetPowerManagementMode 

func (d *ConfigurableDevice) GetPowerManagementMode() (nvml.EnableState, nvml.Return)

GetPowerManagementMode returns whether power management is enabled.

func (*ConfigurableDevice) GetPowerState 

func (d *ConfigurableDevice) GetPowerState() (nvml.Pstates, nvml.Return)

GetPowerState returns power state (same as performance state)

func (*ConfigurableDevice) GetPowerUsage 

func (d *ConfigurableDevice) GetPowerUsage() (uint32, nvml.Return)

GetPowerUsage returns current power draw in milliwatts. Either a static `power:` block or a `dynamic_metrics.power` block is sufficient; only when neither is configured do we report ERROR_NOT_SUPPORTED. When both are present the dynamic simulator overrides the static value.

func (*ConfigurableDevice) GetProcessUtilization 

func (d *ConfigurableDevice) GetProcessUtilization(lastSeenTimestamp uint64) ([]nvml.ProcessUtilizationSample, nvml.Return)

GetProcessUtilization returns one sample per configured process, compute and graphics/video alike (real NVML reports both; GetComputeRunningProcesses is the compute-only call), so it does not filter by type. lastSeenTimestamp is not used as a filter: each sample is stamped with time.Now() (always newer than the caller's lastSeen) so the common lastSeen=0 polling pattern keeps observing the configured values.

func (*ConfigurableDevice) GetRemappedRows 

func (d *ConfigurableDevice) GetRemappedRows() (int, int, bool, bool, nvml.Return)

GetRemappedRows returns remapped row information

func (*ConfigurableDevice) GetRetiredPages 

func (d *ConfigurableDevice) GetRetiredPages(cause nvml.PageRetirementCause) ([]uint64, nvml.Return)

GetRetiredPages returns retired pages

func (*ConfigurableDevice) GetRetiredPagesPendingStatus 

func (d *ConfigurableDevice) GetRetiredPagesPendingStatus() (nvml.EnableState, nvml.Return)

GetRetiredPagesPendingStatus returns whether there are pending retired pages

func (*ConfigurableDevice) GetRetiredPages_v2 

func (d *ConfigurableDevice) GetRetiredPages_v2(cause nvml.PageRetirementCause) ([]uint64, []uint64, nvml.Return)

GetRetiredPages_v2 returns retired pages with timestamps

func (*ConfigurableDevice) GetSerial 

func (d *ConfigurableDevice) GetSerial() (string, nvml.Return)

GetSerial returns the device serial number

func (*ConfigurableDevice) GetSupportedClocksThrottleReasons 

func (d *ConfigurableDevice) GetSupportedClocksThrottleReasons() (uint64, nvml.Return)

GetSupportedClocksThrottleReasons returns bitmask of all supported throttle reasons.

func (*ConfigurableDevice) GetTemperature 

func (d *ConfigurableDevice) GetTemperature(sensor nvml.TemperatureSensors) (uint32, nvml.Return)

GetTemperature returns the GPU temperature. Either a static `thermal:` block or a `dynamic_metrics.temperature` block is sufficient; only when neither is configured do we report ERROR_NOT_SUPPORTED. When both are present the dynamic simulator overrides the static value.

func (*ConfigurableDevice) GetTemperatureThreshold 

func (d *ConfigurableDevice) GetTemperatureThreshold(thresholdType nvml.TemperatureThresholds) (uint32, nvml.Return)

GetTemperatureThreshold returns temperature thresholds

func (*ConfigurableDevice) GetThermalSettings 

func (d *ConfigurableDevice) GetThermalSettings(sensorIndex uint32) (nvml.GpuThermalSettings, nvml.Return)

GetThermalSettings returns thermal sensor settings.

func (*ConfigurableDevice) GetTopologyCommonAncestor 

func (d *ConfigurableDevice) GetTopologyCommonAncestor(other nvml.Device) (nvml.GpuTopologyLevel, nvml.Return)

GetTopologyCommonAncestor returns the pairwise PCIe topology level between this device and another. When the fabric carries pcie_topology facts the level is computed pairwise; otherwise it falls back to the per-device topology.default_level (preserving legacy behavior).

func (*ConfigurableDevice) GetTotalEccErrors 

func (d *ConfigurableDevice) GetTotalEccErrors(errorType nvml.MemoryErrorType, counterType nvml.EccCounterType) (uint64, nvml.Return)

GetTotalEccErrors returns total ECC errors. Healthy devices report zero. When failure injection has tripped into ecc_uncorrectable mode the running call counter is surfaced as the uncorrectable count so each subsequent NVML poll sees a strictly increasing value (matching real hardware accumulating ECC events).

func (*ConfigurableDevice) GetTotalEnergyConsumption 

func (d *ConfigurableDevice) GetTotalEnergyConsumption() (uint64, nvml.Return)

GetTotalEnergyConsumption returns cumulative energy in millijoules.

func (*ConfigurableDevice) GetUUID added in v0.2.0 

func (d *ConfigurableDevice) GetUUID() (string, nvml.Return)

GetUUID returns the device UUID. Overrides the embedded dgxa100.Device implementation so the lost / fallen_off_bus failure modes can surface ERROR_GPU_IS_LOST from this getter — real NVML returns the same error code from every device method once the kernel driver has marked the GPU gone, including identity queries that don't touch hardware.

func (*ConfigurableDevice) GetUtilizationRates 

func (d *ConfigurableDevice) GetUtilizationRates() (nvml.Utilization, nvml.Return)

GetUtilizationRates returns GPU utilization. When dynamic_metrics.utilization is configured the returned values vary according to the selected pattern (idle / busy / burst / steady); otherwise the static UtilizationConfig values are returned unchanged.

func (*ConfigurableDevice) GetVbiosVersion 

func (d *ConfigurableDevice) GetVbiosVersion() (string, nvml.Return)

GetVbiosVersion returns the VBIOS version

func (*ConfigurableDevice) GetViolationStatus added in v0.2.0 

func (d *ConfigurableDevice) GetViolationStatus(perfPolicyType nvml.PerfPolicyType) (nvml.ViolationTime, nvml.Return)

GetViolationStatus returns the active violation time information for a performance policy. The returned struct stays semantically faithful to the NVML spec — both ReferenceTime and ViolationTime are reported in nanoseconds for power/thermal violations. Failure injection does NOT overload these fields with the configured Xid code; instead the Xid is surfaced via the NVML event set (NVML_EVENT_TYPE_XID_CRITICAL_ERROR) so consumers like dcgm-exporter or the device plugin's health monitor see it through the API designed for it. We still return ERROR_GPU_IS_LOST for tripped lost / fallen_off_bus devices, matching every other guarded getter.

func (*ConfigurableDevice) GpmSnapshotInto added in v0.3.0 

func (d *ConfigurableDevice) GpmSnapshotInto(key uint64) nvml.Return

GpmSnapshotInto snapshots the device's current activity into the sample buffer.

func (*ConfigurableDevice) ResetNvLinkErrorCounters added in v0.3.0 

func (d *ConfigurableDevice) ResetNvLinkErrorCounters(link int) nvml.Return

ResetNvLinkErrorCounters is a no-op success.

func (*ConfigurableDevice) ResetNvLinkUtilizationCounter added in v0.3.0 

func (d *ConfigurableDevice) ResetNvLinkUtilizationCounter(link, counter int) nvml.Return

ResetNvLinkUtilizationCounter is a no-op success (see Freeze).

func (*ConfigurableDevice) SetPersistenceMode 

func (d *ConfigurableDevice) SetPersistenceMode(mode nvml.EnableState) nvml.Return

SetPersistenceMode sets persistence mode in-memory (not persisted across restarts)

type DeviceConfig 

type DeviceConfig struct {
	// Basic identification
	Name            string `json:"name,omitempty"`
	Brand           string `json:"brand,omitempty"`
	Serial          string `json:"serial,omitempty"`
	BoardPartNumber string `json:"board_part_number,omitempty"`
	VBIOSVersion    string `json:"vbios_version,omitempty"`

	// Architecture
	Architecture      string                   `json:"architecture,omitempty"`
	ComputeCapability *ComputeCapabilityConfig `json:"compute_capability,omitempty"`
	NumGPUCores       int                      `json:"num_gpu_cores,omitempty"`

	// InfoROM
	InfoROM *InfoROMConfig `json:"inforom,omitempty"`

	// Memory
	Memory     *MemoryConfig     `json:"memory,omitempty"`
	BAR1Memory *BAR1MemoryConfig `json:"bar1_memory,omitempty"`

	// PCI
	PCI  *PCIConfig  `json:"pci,omitempty"`
	PCIe *PCIeConfig `json:"pcie,omitempty"`

	// Power
	Power *PowerConfig `json:"power,omitempty"`

	// Thermal
	Thermal *ThermalConfig `json:"thermal,omitempty"`

	// Fan
	Fan *FanConfig `json:"fan,omitempty"`

	// Clocks
	Clocks                *ClocksConfig                `json:"clocks,omitempty"`
	ClocksThrottleReasons *ClocksThrottleReasonsConfig `json:"clocks_throttle_reasons,omitempty"`
	SupportedClocks       *SupportedClocksConfig       `json:"supported_clocks,omitempty"`

	// Performance
	PerformanceState string `json:"performance_state,omitempty"`

	// Utilization
	Utilization *UtilizationConfig `json:"utilization,omitempty"`

	// Encoder/Decoder
	EncoderStats *EncoderStatsConfig `json:"encoder_stats,omitempty"`
	FBCStats     *FBCStatsConfig     `json:"fbc_stats,omitempty"`

	// ECC
	ECC *ECCConfig `json:"ecc,omitempty"`

	// Retired pages
	RetiredPages *RetiredPagesConfig `json:"retired_pages,omitempty"`

	// Remapped rows
	RemappedRows *RemappedRowsConfig `json:"remapped_rows,omitempty"`

	// Display
	Display *DisplayConfig `json:"display,omitempty"`

	// Modes
	PersistenceMode string `json:"persistence_mode,omitempty"`
	ComputeMode     string `json:"compute_mode,omitempty"`

	// MIG
	MIG *MIGConfig `json:"mig,omitempty"`

	// GPU Operation Mode
	GPUOperationMode *GPUOperationModeConfig `json:"gpu_operation_mode,omitempty"`

	// Driver Model
	DriverModel *DriverModelConfig `json:"driver_model,omitempty"`

	// Accounting
	Accounting *AccountingConfig `json:"accounting,omitempty"`

	// Virtualization
	Virtualization *VirtualizationConfig `json:"virtualization,omitempty"`

	// GSP Firmware
	GSPFirmware *GSPFirmwareConfig `json:"gsp_firmware,omitempty"`

	// Blackwell-specific features (GB200)
	Features *FeaturesConfig `json:"features,omitempty"`

	// Grace Superchip (GB200)
	GraceSuperchip *GraceSuperchipConfig `json:"grace_superchip,omitempty"`

	// Topology
	Topology *TopologyConfig `json:"topology,omitempty"`

	// Processes
	Processes []ProcessConfig `json:"processes,omitempty"`

	// DynamicMetrics enables time-varying values for temperature, power, and
	// utilization. When nil (default), static values from the other config
	// sections are returned as-is.
	DynamicMetrics *DynamicMetricsConfig `json:"dynamic_metrics,omitempty"`

	// GPM tunes the GPU Performance Monitoring surface DCGM's profiling
	// module reads (DCGM_FI_PROF_*). When nil, GPM support follows the
	// device architecture (Hopper and newer, matching real NVML).
	GPM *GPMConfig `json:"gpm,omitempty"`

	// Failure enables GPU failure injection (lost device, fallen-off-bus,
	// uncorrectable ECC, Xid). When nil (default) the device behaves as
	// healthy hardware.
	Failure *FailureInjectionConfig `json:"failure,omitempty"`

	// Fabric enables the GB200/GB300 NVLink fabric API surface. When nil
	// (default) GetGpuFabricInfo / GetGpuFabricInfoV report
	// ERROR_NOT_SUPPORTED — matching every non-fabric-attached GPU.
	Fabric *FabricConfig `json:"fabric,omitempty"`

	// NVLinkError injects per-link NVLink DL error accrual on this device's
	// links to its NVSwitch. When nil (default) the links report the healthy
	// baseline. See NVLinkErrorInjectionConfig.
	NVLinkError *NVLinkErrorInjectionConfig `json:"nvlink_error,omitempty"`
}

DeviceConfig represents the full device configuration. Used for both defaults and per-device overrides.

func MergeDeviceConfig added in v0.3.0 

func MergeDeviceConfig(base *DeviceConfig, patch map[string]any) (*DeviceConfig, error)

MergeDeviceConfig deep-merges patch over a JSON view of base and unmarshals the result into a new *DeviceConfig. Unknown fields are rejected so typos in configOverrides fail loudly. base is never mutated.

type DeviceLinksConfig added in v0.3.0 

type DeviceLinksConfig struct {
	Index int                `json:"index"`
	Links []NVLinkLinkConfig `json:"links,omitempty"`
}

DeviceLinksConfig is the per-device NVLink link set.

type DeviceOverride 

type DeviceOverride struct {
	Index        int              `json:"index"`
	UUID         string           `json:"uuid,omitempty"`
	MinorNumber  int              `json:"minor_number,omitempty"`
	GraceCPUPair int              `json:"grace_cpu_pair,omitempty"`
	DeviceConfig `json:",inline"` // Embed all device config fields
}

DeviceOverride contains per-device settings that override defaults

type DisplayConfig 

type DisplayConfig struct {
	Mode   string `json:"mode,omitempty"`
	Active string `json:"active,omitempty"`
}

DisplayConfig defines display output settings

type DriverModelConfig 

type DriverModelConfig struct {
	Current string `json:"current,omitempty"`
	Pending string `json:"pending,omitempty"`
}

DriverModelConfig defines driver model (Windows)

type DynamicMetricsConfig added in v0.2.0 

type DynamicMetricsConfig struct {
	// Seed seeds the per-device PRNG. Zero means use a time-based seed so
	// each process sees different but repeatable-within-run values.
	Seed int64 `json:"seed,omitempty"`

	// Temperature, Power, Utilization are each independently opt-in. Any
	// sub-config left nil keeps the corresponding metric static.
	Temperature *DynamicTemperatureConfig `json:"temperature,omitempty"`
	Power       *DynamicPowerConfig       `json:"power,omitempty"`
	Utilization *DynamicUtilizationConfig `json:"utilization,omitempty"`
}

DynamicMetricsConfig enables opt-in time-varying simulation for GPU metrics that, on real hardware, change between calls (temperature, power, utilization). When this config is absent, static values from the Thermal, Power, and Utilization sections are returned unchanged.

type DynamicPowerConfig added in v0.2.0 

type DynamicPowerConfig struct {
	BaseMW     uint32 `json:"base_mw"`
	VarianceMW uint32 `json:"variance_mw,omitempty"`
}

DynamicPowerConfig produces power draw values (milliwatts) that fluctuate around base_mw by at most variance_mw. The result is clamped to [min_limit_mw, max_limit_mw] from PowerConfig when those bounds are set.

type DynamicTemperatureConfig added in v0.2.0 

type DynamicTemperatureConfig struct {
	BaseC         int `json:"base_c"`
	VarianceC     int `json:"variance_c,omitempty"`
	RampC         int `json:"ramp_c,omitempty"`
	RampPeriodSec int `json:"ramp_period_sec,omitempty"`
}

DynamicTemperatureConfig produces GPU temperatures that fluctuate over time.

Returned value (clamped to the thermal shutdown threshold if known): 

base_c + ramp_offset(t) + noise

where ramp_offset oscillates in [0, ramp_c] with period ramp_period_sec (a sine wave shifted to be non-negative), and noise is uniform in [-variance_c, +variance_c].

type DynamicUtilizationConfig added in v0.2.0 

type DynamicUtilizationConfig struct {
	Pattern        string `json:"pattern,omitempty"`
	GPUMin         uint32 `json:"gpu_min,omitempty"`
	GPUMax         uint32 `json:"gpu_max,omitempty"`
	MemoryMin      uint32 `json:"memory_min,omitempty"`
	MemoryMax      uint32 `json:"memory_max,omitempty"`
	BurstPeriodSec int    `json:"burst_period_sec,omitempty"`
}

DynamicUtilizationConfig drives GPU / memory utilization percentages.

Pattern semantics (all values clamped to 0..100):

  • "idle": random in [gpu_min, gpu_min + (gpu_max-gpu_min)/4]
  • "busy": random in [gpu_max - (gpu_max-gpu_min)/4, gpu_max]
  • "burst": alternates "idle" and "busy" phases every burst_period_sec
  • "steady" or empty: random in [gpu_min, gpu_max]

Memory utilization follows the same rule using memory_min / memory_max.

type ECCConfig 

type ECCConfig struct {
	ModeCurrent string           `json:"mode_current,omitempty"`
	ModePending string           `json:"mode_pending,omitempty"`
	DefaultMode string           `json:"default_mode,omitempty"`
	Errors      *ECCErrorsConfig `json:"errors,omitempty"`
}

ECCConfig defines ECC memory configuration

type ECCErrorCountsConfig 

type ECCErrorCountsConfig struct {
	SingleBit *ECCMemoryErrorsConfig `json:"single_bit,omitempty"`
	DoubleBit *ECCMemoryErrorsConfig `json:"double_bit,omitempty"`
}

ECCErrorCountsConfig defines single/double bit error counts

type ECCErrorsConfig 

type ECCErrorsConfig struct {
	Volatile  *ECCErrorCountsConfig `json:"volatile,omitempty"`
	Aggregate *ECCErrorCountsConfig `json:"aggregate,omitempty"`
}

ECCErrorsConfig defines ECC error counts

type ECCMemoryErrorsConfig 

type ECCMemoryErrorsConfig struct {
	DeviceMemory  uint64 `json:"device_memory,omitempty"`
	L1Cache       uint64 `json:"l1_cache,omitempty"`
	L2Cache       uint64 `json:"l2_cache,omitempty"`
	RegisterFile  uint64 `json:"register_file,omitempty"`
	TextureMemory uint64 `json:"texture_memory,omitempty"`
	Total         uint64 `json:"total,omitempty"`
}

ECCMemoryErrorsConfig defines per-memory-location error counts

type EncoderStatsConfig 

type EncoderStatsConfig struct {
	SessionCount     uint32 `json:"session_count,omitempty"`
	AverageFPS       uint32 `json:"average_fps,omitempty"`
	AverageLatencyUS uint32 `json:"average_latency_us,omitempty"`
}

EncoderStatsConfig defines encoder statistics

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine manages the mock NVML lifecycle and handle mapping. It does NOT implement nvml.Interface - it delegates to MockServer which wraps dgxa100.Server (the actual nvml.Interface implementation).

func GetEngine 

func GetEngine() *Engine

GetEngine returns the singleton Engine instance.

func NewEngine 

func NewEngine(config *Config) *Engine

NewEngine creates a new Engine with optional configuration. If config is nil, it loads from environment. The server is created lazily on first Init() call.

func (*Engine) DeviceGetCount 

func (e *Engine) DeviceGetCount() (int, nvml.Return)

DeviceGetCount returns the number of compute devices.

func (*Engine) DeviceGetHandleByIndex 

func (e *Engine) DeviceGetHandleByIndex(index int) (unsafe.Pointer, nvml.Return)

DeviceGetHandleByIndex returns a handle for the device at the given index. The handle is a pointer to a C-allocated block owned by the HandleTable; see HandleTable's documentation for why this is unsafe.Pointer and not uintptr.

func (*Engine) DeviceGetHandleByPciBusId 

func (e *Engine) DeviceGetHandleByPciBusId(pciBusId string) (unsafe.Pointer, nvml.Return)

DeviceGetHandleByPciBusId returns a handle for the device with the given PCI Bus ID.

func (*Engine) DeviceGetHandleByUUID 

func (e *Engine) DeviceGetHandleByUUID(uuid string) (unsafe.Pointer, nvml.Return)

DeviceGetHandleByUUID returns a handle for the device with the given UUID.

func (*Engine) GetConfig 

func (e *Engine) GetConfig() *Config

GetConfig returns the engine configuration (for testing)

func (*Engine) Init 

func (e *Engine) Init() nvml.Return

Init initializes the NVML library. On first call, creates and configures the mock server.

func (*Engine) LookupConfigurableDevice 

func (e *Engine) LookupConfigurableDevice(handle unsafe.Pointer) *ConfigurableDevice

LookupConfigurableDevice returns the ConfigurableDevice for a given handle. This is useful when we need access to ConfigurableDevice-specific methods.

func (*Engine) LookupDevice 

func (e *Engine) LookupDevice(handle unsafe.Pointer) nvml.Device

LookupDevice returns the device object for a given handle. Returns InvalidDeviceInstance if the engine is not initialized or the handle is invalid.

func (*Engine) PendingXidEvent added in v0.2.0 

func (e *Engine) PendingXidEvent() (unsafe.Pointer, uint64, bool)

PendingXidEvent claims the next undelivered Xid critical-error event from any device that has tripped failure injection with a `xid:` block configured. It returns the device handle (auto-registering one if the caller hasn't resolved a handle for that device yet), the Xid code, and true on success. When no event is pending it returns (nil, 0, false) and the bridge layer reports NVML_ERROR_TIMEOUT to the nvmlEventSetWait caller.

Each tripped Xid is delivered at most once for the lifetime of the engine, matching real NVML semantics where a single Xid critical error fires exactly once per occurrence.

func (*Engine) SetVisibleDevicesForTesting added in v0.2.0 

func (e *Engine) SetVisibleDevicesForTesting(visible []int)

SetVisibleDevicesForTesting sets the visible device mapping on an initialized engine's server. Pass nil to disable filtering. Only use in tests.

func (*Engine) Shutdown 

func (e *Engine) Shutdown() nvml.Return

Shutdown shuts down the NVML library.

func (*Engine) SystemGetCudaDriverVersion 

func (e *Engine) SystemGetCudaDriverVersion() (int, nvml.Return)

SystemGetCudaDriverVersion returns the CUDA driver version. This function can be called before initialization (returns config version).

func (*Engine) SystemGetDriverVersion 

func (e *Engine) SystemGetDriverVersion() (string, nvml.Return)

SystemGetDriverVersion returns the NVIDIA driver version. This function can be called before initialization (returns config version).

func (*Engine) SystemGetNVMLVersion 

func (e *Engine) SystemGetNVMLVersion() (string, nvml.Return)

SystemGetNVMLVersion returns the NVML version string. This function can be called before initialization (returns config version).

func (*Engine) TopologyGpuSet added in v0.3.0 

func (e *Engine) TopologyGpuSet(cpuNumber int) ([]unsafe.Pointer, nvml.Return)

TopologyGpuSet returns handles for the GPUs that have CPU affinity with the given CPU number, derived from the NodeFabric's per-device CPU sets. This backs nvmlSystemGetTopologyGpuSet, which nvidia-smi topo -m uses to group GPUs by their affined CPU. When no pcie_topology is configured the affinity sets are empty and the result is an empty set (SUCCESS), matching a node whose CPU affinity is unknown rather than an error.

func (*Engine) TopologyNearestGpus added in v0.3.0 

func (e *Engine) TopologyNearestGpus(handle unsafe.Pointer, level nvml.GpuTopologyLevel) ([]unsafe.Pointer, nvml.Return)

TopologyNearestGpus returns handles for the GPUs whose topology path to the given device is at or below (i.e. closer than or equal to) the requested level. The bridge marshals these into the caller's device array. Handles are registered on demand so the C caller gets valid references.

type FBCStatsConfig 

type FBCStatsConfig struct {
	SessionCount     uint32 `json:"session_count,omitempty"`
	AverageFPS       uint32 `json:"average_fps,omitempty"`
	AverageLatencyUS uint32 `json:"average_latency_us,omitempty"`
}

FBCStatsConfig defines frame buffer capture statistics

type FabricConfig added in v0.2.0 

type FabricConfig struct {
	// ClusterUUID identifies the NVLink fabric (16-byte UUID). Accepts
	// dashed form ("00000000-0000-0000-0000-000000000001") or bare hex.
	ClusterUUID string `json:"cluster_uuid,omitempty"`
	// CliqueID is the clique within the cluster this GPU belongs to.
	CliqueID uint32 `json:"clique_id,omitempty"`
	// State is the GPU registration state with the fabric manager.
	// Defaults to "completed" (the healthy steady-state value). The
	// special value "auto" couples the state to the fake fabricmanager's
	// readiness marker when fabricmanager is enabled, and resolves to
	// "completed" when it is disabled (see engine/fabric_readiness.go).
	State string `json:"state,omitempty"`
	// HealthMask is the v2 health bitmask. Defaults to 0 (healthy).
	HealthMask uint32 `json:"health_mask,omitempty"`
}

FabricConfig models the per-GPU NVLink fabric attributes that nvmlDeviceGetGpuFabricInfo / nvmlDeviceGetGpuFabricInfoV expose for fabric-attached GPUs (Hopper+ / GB200 / GB300). All GPUs on the same physical node share the same fabric config — the NVLink domain is a node-level property.

State strings map to the NVML_GPU_FABRIC_STATE_* enum (see fabric.go FabricState* constants and parseFabricState):

  • "not_supported" -> 0
  • "not_started" -> 1
  • "in_progress" -> 2
  • "completed" -> 3
  • "auto" -> coupled to the fabricmanager readiness marker (resolves to in_progress/completed; see resolveFabricState)

ClusterUUID is parsed as RFC-4122-style hex; non-hex characters are dropped and the buffer is zero-padded to 16 bytes so the YAML can carry either bare hex or dashed UUID form.

type FabricInfo added in v0.2.0 

type FabricInfo struct {
	ClusterUUID   [16]byte
	Status        uint32 // NVML return code embedded inside the struct (SUCCESS by default)
	CliqueID      uint32
	State         uint8
	HealthMask    uint32
	HealthSummary uint8
}

FabricInfo is the engine-internal shape of a GPU's fabric attributes (the union of v1, v2, v3 NVML structs). The CGo bridge converts this to the appropriate C struct version selected by the caller.

No PartitionID: nvml_types.h does not carry a partition_id field on any of v1/v2/v3, so plumbing one through the engine would only be dead weight. Reintroduce when there is a real NVML struct version that exposes it.

type FailureInjectionConfig added in v0.2.0 

type FailureInjectionConfig struct {
	// Mode selects the failure flavour. See FailureMode* constants.
	Mode string `json:"mode,omitempty"`

	// Probability of activating per guarded call, in [0, 1].
	Probability float64 `json:"probability,omitempty"`

	// AfterCalls activates the failure once this many guarded calls have
	// been observed (deterministic). Combine with Probability if you want
	// "may fail before, will fail by".
	AfterCalls int64 `json:"after_calls,omitempty"`

	// Seed seeds the per-device PRNG used for Probability rolls. Zero
	// means "derive from time" (similar to DynamicMetricsConfig.Seed).
	Seed int64 `json:"seed,omitempty"`

	// Xid optionally injects a Xid error code visible via
	// Device.GetViolationStatus once the failure has tripped.
	Xid *XidErrorConfig `json:"xid,omitempty"`
}

FailureInjectionConfig models GPU failure injection for a device. It is disabled by default. When Mode is one of FailureMode* constants the device starts (or transitions to) the failed state subject to the stochastic and deterministic triggers below.

Trigger semantics:

  • When AfterCalls > 0 the failure activates as soon as the device has received that many guarded NVML calls. This makes failure timing reproducible in CI without depending on wall-clock time.
  • When Probability > 0 every guarded call rolls a uniform sample in [0, 1); if it lands below Probability the failure activates.
  • When neither AfterCalls nor Probability are set, the failure is active immediately (so consumers can pin a "permanently lost" device just by setting Mode).

Once a device has tripped it stays tripped — real lost / fallen-off-bus GPUs do not recover until the box is rebooted, and ECC errors only accumulate. Use the Xid sub-config to pair the failure with a Xid code returned via Device.GetViolationStatus.

type FanConfig 

type FanConfig struct {
	Count              int    `json:"count,omitempty"`
	SpeedPercent       string `json:"speed_percent,omitempty"`
	TargetSpeedPercent string `json:"target_speed_percent,omitempty"`
}

FanConfig defines fan settings

type FeaturesConfig 

type FeaturesConfig struct {
	TransformerEngine   bool `json:"transformer_engine,omitempty"`
	FP4Support          bool `json:"fp4_support,omitempty"`
	FP8Support          bool `json:"fp8_support,omitempty"`
	ConfidentialCompute bool `json:"confidential_compute,omitempty"`
	NVLinkC2C           bool `json:"nvlink_c2c,omitempty"`
	DecompressionEngine bool `json:"decompression_engine,omitempty"`
	FifthGenTensorCores bool `json:"fifth_gen_tensor_cores,omitempty"`
}

FeaturesConfig defines GPU-specific features (like Blackwell features)

type FieldValueType added in v0.3.0 

type FieldValueType uint8

FieldValueType identifies which nvmlValue_t union member the bridge must populate for a resolved field value. 

const (
	// FieldValueUnsupported means the field id is not modeled; the bridge
	// should set the per-field nvmlReturn to NOT_SUPPORTED.
	FieldValueUnsupported FieldValueType = iota
	// FieldValueUint maps to nvmlValue_t.uiVal (NVML_VALUE_TYPE_UNSIGNED_INT).
	FieldValueUint
	// FieldValueUint64 maps to nvmlValue_t.ullVal
	// (NVML_VALUE_TYPE_UNSIGNED_LONG_LONG).
	FieldValueUint64
	// FieldValueDouble maps to nvmlValue_t.dVal (NVML_VALUE_TYPE_DOUBLE); the
	// returned value carries math.Float64bits of the double (the bridge writes
	// the raw 8 bytes into the shared union).
	FieldValueDouble
	// FieldValueInt maps to nvmlValue_t.siVal (NVML_VALUE_TYPE_SIGNED_INT).
	// The returned uint64 carries the value's low 32 bits in two's-complement
	// form (uint64(uint32(int32(v)))) so the bridge can reinterpret it as a
	// signed int; used by the T.Limit thresholds, whose offsets go negative.
	FieldValueInt
)

type FunctionVersion 

type FunctionVersion struct {
	Added   string // Driver version where function was introduced (e.g., "470.0")
	Removed string // Driver version where function was removed (empty = still present)
}

FunctionVersion describes the driver version range where an NVML function exists.

type GPMConfig added in v0.3.0 

type GPMConfig struct {
	// Supported overrides architecture-based GPM support detection
	// (default: supported on Hopper and newer, matching real NVML).
	Supported *bool `json:"supported,omitempty"`
	// Full-utilization PCIe rates for the PCIE_TX/RX_PER_SEC metrics, in
	// MiB/s. The reported rate is scaled by current GPU utilization.
	// Default: 2048 MiB/s each direction.
	PcieTxMiBPerSec uint64 `json:"pcie_tx_mib_per_sec,omitempty"`
	PcieRxMiBPerSec uint64 `json:"pcie_rx_mib_per_sec,omitempty"`
}

GPMConfig tunes the GPM (GPU Performance Monitoring) profiling surface DCGM's profiling module reads (DCGM_FI_PROF_*, dcgmi dmon -e 1001..).

type GPUOperationModeConfig 

type GPUOperationModeConfig struct {
	Current string `json:"current,omitempty"`
	Pending string `json:"pending,omitempty"`
}

GPUOperationModeConfig defines GOM settings

type GSPFirmwareConfig 

type GSPFirmwareConfig struct {
	Mode    string `json:"mode,omitempty"`
	Version string `json:"version,omitempty"`
}

GSPFirmwareConfig defines GSP firmware settings

type GraceSuperchipConfig 

type GraceSuperchipConfig struct {
	Enabled        bool `json:"enabled,omitempty"`
	CPUCores       int  `json:"cpu_cores,omitempty"`
	CPUMemoryGB    int  `json:"cpu_memory_gb,omitempty"`
	CoherentMemory bool `json:"coherent_memory,omitempty"`
}

GraceSuperchipConfig defines Grace CPU pairing for GB200

type HandleTable 

type HandleTable struct {
	// contains filtered or unexported fields
}

HandleTable manages the mapping between C handles and Go device objects. This is necessary because CGo doesn't allow passing Go pointers with nested Go pointers to C code.

Handles are C-allocated memory blocks (see allocHandle above) that nvidia-smi can safely dereference. They are typed unsafe.Pointer rather than uintptr on purpose: a handle IS a pointer, it is dereferenced by isValidHandle and by the C caller, and uintptr is documented as an integer that does not hold a reference. Keeping the pointer type end to end means no code path ever has to convert an integer back into a pointer, which is both the honest model and what lets `go vet`'s unsafeptr check pass without suppression.

The memory these handles point at is libc heap, not Go heap, so the Go garbage collector never scans, moves or frees it; the C block outlives any Go reference and is released only by Clear().

LIFECYCLE:

  • Handles are allocated via Register() when devices are first accessed
  • Handles persist until Clear() is called (typically on Shutdown)
  • Individual handle deallocation is NOT supported (matches NVML behavior)
  • Maximum of MaxDevices handles can be registered

THREAD SAFETY:

  • All methods are thread-safe via RWMutex
  • Lookup() validates handle magic number to detect use-after-free

func NewHandleTable 

func NewHandleTable() *HandleTable

NewHandleTable creates a new HandleTable.

func (*HandleTable) Clear 

func (ht *HandleTable) Clear()

Clear removes all entries from the handle table and frees allocated memory.

func (*HandleTable) Count 

func (ht *HandleTable) Count() int

Count returns the number of registered handles.

func (*HandleTable) HandleFor added in v0.2.0 

func (ht *HandleTable) HandleFor(dev nvml.Device) unsafe.Pointer

HandleFor returns the registered handle for the given device, or nil when the device has not yet been registered. Used by event-set wiring that needs to translate a tripped device back to a handle the caller already holds (e.g. the Xid critical-error event delivery path). Real NVML accepts events for devices the caller has resolved a handle for; returning nil here lets the caller treat that case as "no event yet".

func (*HandleTable) Lookup 

func (ht *HandleTable) Lookup(handle unsafe.Pointer) nvml.Device

Lookup returns the device for the given handle. Returns InvalidDeviceInstance if the handle is invalid (null-object pattern). This eliminates nil checks in the bridge layer - callers can safely call methods on the returned device; invalid devices return ERROR_INVALID_ARGUMENT.

func (*HandleTable) Register 

func (ht *HandleTable) Register(dev nvml.Device) unsafe.Pointer

Register adds a device to the handle table and returns its handle. If the device is already registered, returns the existing handle. The handle is a pointer to C-allocated memory.

type InfoROMConfig 

type InfoROMConfig struct {
	ImageVersion string `json:"image_version,omitempty"`
	OEMObject    string `json:"oem_object,omitempty"`
	ECCObject    string `json:"ecc_object,omitempty"`
	PWRObject    string `json:"pwr_object,omitempty"`
}

InfoROMConfig defines InfoROM version information

type MIGConfig 

type MIGConfig struct {
	ModeCurrent     string `json:"mode_current,omitempty"`
	ModePending     string `json:"mode_pending,omitempty"`
	MaxGPUInstances int    `json:"max_gpu_instances,omitempty"`
}

MIGConfig defines MIG configuration

type MemoryClockConfig 

type MemoryClockConfig struct {
	FreqMHz        uint32   `json:"freq_mhz"`
	GraphicsClocks []uint32 `json:"graphics_clocks"`
}

MemoryClockConfig defines a memory clock with associated graphics clocks

type MemoryConfig 

type MemoryConfig struct {
	TotalBytes     uint64 `json:"total_bytes"`
	ReservedBytes  uint64 `json:"reserved_bytes,omitempty"`
	FreeBytes      uint64 `json:"free_bytes,omitempty"`
	UsedBytes      uint64 `json:"used_bytes,omitempty"`
	MemoryBusWidth uint32 `json:"memory_bus_width,omitempty"` // bits (e.g., 5120 for A100)
}

MemoryConfig defines GPU memory settings

type MockServer 

type MockServer struct {
	*dgxa100.Server
	// contains filtered or unexported fields
}

MockServer wraps dgxa100.Server and uses configurable devices

func (*MockServer) DeviceGetHandleByIndex 

func (s *MockServer) DeviceGetHandleByIndex(index int) (nvml.Device, nvml.Return)

DeviceGetHandleByIndex returns a configurable device by visible index. When device visibility filtering is active (container has only a subset of /dev/nvidia* nodes), the index maps through the visibility table.

If the resolved device has tripped failure injection into a "lost" or "fallen_off_bus" mode, the lookup returns ERROR_GPU_IS_LOST instead of a usable handle, matching real NVML behaviour for hardware that has dropped off the PCI bus.

func (*MockServer) DeviceGetHandleByPciBusId 

func (s *MockServer) DeviceGetHandleByPciBusId(pciBusId string) (nvml.Device, nvml.Return)

DeviceGetHandleByPciBusId returns a configurable device by PCI bus ID. When device visibility filtering is active, only visible devices are returned. Lost devices behave the same as in DeviceGetHandleByIndex.

func (*MockServer) DeviceGetHandleByUUID 

func (s *MockServer) DeviceGetHandleByUUID(uuid string) (nvml.Device, nvml.Return)

DeviceGetHandleByUUID returns a configurable device by UUID. When device visibility filtering is active, only visible devices are returned. Lost devices behave the same as in DeviceGetHandleByIndex.

type NVLinkConfig 

type NVLinkConfig struct {
	Version     int `json:"version,omitempty"`
	LinksPerGPU int `json:"links_per_gpu,omitempty"`
	// BandwidthPerLinkMbps sets the per-link speed in Mbps (what
	// NVML/`nvidia-smi nvlink -s` reports, GB/s = Mbps/1000). Mbps lets
	// non-integer GB/s rates render exactly — e.g. NVLink5 is 53.125 GB/s,
	// i.e. 53125 Mbps.
	BandwidthPerLinkMbps int  `json:"bandwidth_per_link_mbps,omitempty"`
	C2CEnabled           bool `json:"c2c_enabled,omitempty"`
	// Links is the legacy flat link list. It is kept for backward
	// compatibility and is mapped to device index 0 when no DeviceLinks
	// entry exists for that device.
	Links []NVLinkLinkConfig `json:"links,omitempty"`

	// Switches lists the NVSwitch remote endpoints on the node. NVSwitches
	// are modeled purely as NVLink remote endpoints (remote device type
	// SWITCH); the nvmlUnit* chassis API stays stubbed, matching real
	// DGX/HGX GPU nodes.
	Switches []NVSwitchConfig `json:"switches,omitempty"`

	// Defaults carries per-link defaults applied to every resolved link
	// (state, counter accrual). Absent fields fall back to built-in
	// defaults.
	Defaults *NVLinkDefaults `json:"defaults,omitempty"`

	// DeviceLinks holds per-device link sets keyed by device index. When a
	// device has no entry here the legacy flat Links list is used for
	// device 0 only.
	DeviceLinks []DeviceLinksConfig `json:"device_links,omitempty"`
}

NVLinkConfig defines NVLink topology

type NVLinkDefaults added in v0.3.0 

type NVLinkDefaults struct {
	// State is the default link state (active/up/enabled vs anything else).
	State string `json:"state,omitempty"`
	// DutyCycle is the fraction of line rate accrued into the utilization
	// counters (0..1). A small positive value makes counters visibly grow
	// across separate nvidia-smi invocations.
	DutyCycle float64 `json:"duty_cycle,omitempty"`
	// CounterSeed is the baseline value added to every utilization counter.
	CounterSeed uint64 `json:"counter_seed,omitempty"`
	// ErrorRate is the per-second accrual rate for NVLink error counters.
	// Defaults to 0 (healthy links report no errors).
	ErrorRate float64 `json:"error_rate,omitempty"`
}

NVLinkDefaults carries per-link defaults expanded across all links so the NV# matrix can be populated without hand-authoring every entry.

type NVLinkErrorInjectionConfig added in v0.3.0 

type NVLinkErrorInjectionConfig struct {
	// Rate is the injected error accrual in errors/second, added on top of
	// each affected link's baseline. The counter climbs monotonically off the
	// shared epoch (the same accrual model as NVLinkDefaults.ErrorRate), so
	// DCGM's delta-based NVLink health watch observes a rising error rate
	// rather than a one-shot step it would treat as stale after the first
	// sample. 0 (default) disables injection — the healthy baseline.
	Rate float64 `json:"rate,omitempty"`

	// Links restricts injection to specific link ids. Empty (default) injects
	// on every active link on the device — the "GPU lost its switch uplinks"
	// fault. Ids that don't map to an active link are ignored.
	Links []int `json:"links,omitempty"`
}

NVLinkErrorInjectionConfig injects NVLink data-link error accrual on a device's links so the GPU's uplinks to its NVSwitch report climbing DL errors — the closest an NVML-only mock can get to an NVSwitch-side fault.

It exists because DCGM's NVSwitch entity health (DCGM_HEALTH_WATCH_NVSWITCH_*) is sourced from NSCQ, not NVML, so a libnvidia-ml mock cannot drive it. What the mock CAN drive is the GPU-side NVLink error surface DCGM's DCGM_HEALTH_WATCH_NVLINK reads: the per-link/per-counter direct API (nvmlDeviceGetNvLinkErrorCounter) and the DL error field values (NVML_FI_DEV_NVLINK_ERROR_DL_{REPLAY,RECOVERY,CRC}, field ids 161-163). A rising error rate there surfaces as DCGM_FR_NVLINK_* and is detected and remediated by NVSentinel's gpu-health-monitor.

type NVLinkLinkConfig 

type NVLinkLinkConfig struct {
	Link             int    `json:"link"`
	State            string `json:"state,omitempty"`
	RemoteDeviceType string `json:"remote_device_type,omitempty"`
	RemotePCIBusID   string `json:"remote_pci_bus_id,omitempty"`
	// RemoteIndex optionally identifies the peer GPU directly by device
	// index. When set it takes precedence over RemotePCIBusID for peer
	// resolution.
	RemoteIndex *int `json:"remote_index,omitempty"`
}

NVLinkLinkConfig defines a single NVLink connection

type NVSwitch added in v0.3.0 

type NVSwitch struct {
	Index int
	BDF   string
	UUID  string
}

NVSwitch is an NVLink remote endpoint. NVSwitches exist in the model (they are what fake-fabricmanager manages) but are intentionally not surfaced through the nvmlUnit* API, matching real GPU nodes.

type NVSwitchConfig added in v0.3.0 

type NVSwitchConfig struct {
	BDF  string `json:"bdf,omitempty"`
	UUID string `json:"uuid,omitempty"`
}

NVSwitchConfig describes a single NVSwitch remote endpoint.

type NodeFabric added in v0.3.0 

type NodeFabric struct {
	// contains filtered or unexported fields
}

NodeFabric is the single, immutable node-level topology model. It is built once at config load and shared (read-only) by every ConfigurableDevice, which holds only its own device index. Every NVLink, topology, and affinity surface is *derived* from this model so the matrix nvidia-smi prints cannot drift between getters.

NodeFabric is safe for concurrent reads: after BuildNodeFabric returns, nothing mutates it, and the NVLink counters are computed as a pure function of the immutable per-link rate and an injectable clock.

func BuildNodeFabric added in v0.3.0 

func BuildNodeFabric(cfg *Config) *NodeFabric

BuildNodeFabric constructs the immutable node fabric from the loaded configuration. It never fails: misconfiguration is recorded as warnings (see Validate) rather than blocking startup, matching the project's tolerant style.

func (*NodeFabric) ActiveLinkCount added in v0.3.0 

func (f *NodeFabric) ActiveLinkCount(dev int) int

ActiveLinkCount returns the number of active NVLinks on a device. This backs NVML_FI_DEV_NVLINK_LINK_COUNT, which nvidia-smi queries first to decide how many links to enumerate for `nvlink -s/-c/-e`.

func (*NodeFabric) CPUAffinityMask added in v0.3.0 

func (f *NodeFabric) CPUAffinityMask(dev, words int) []uint64

CPUAffinityMask packs the device's CPU set into a little-endian bitmask of `words` 64-bit words (the layout nvmlDeviceGetCpuAffinity expects).

func (*NodeFabric) CPUs added in v0.3.0 

func (f *NodeFabric) CPUs(dev int) []int

CPUs returns the CPU id list affined to a device. 

func (f *NodeFabric) FirstActiveLink(dev int) (int, bool)

FirstActiveLink returns the index of the lowest-numbered active link on a device and whether one exists. Used for the "common" speed field.

func (*NodeFabric) HasPCIeTopology added in v0.3.0 

func (f *NodeFabric) HasPCIeTopology() bool

HasPCIeTopology reports whether root-complex / NUMA facts were supplied. 

func (f *NodeFabric) Link(dev, link int) (ResolvedLink, bool)

Link returns the resolved link for (dev, link) and whether it exists.

func (*NodeFabric) LinkVersion added in v0.3.0 

func (f *NodeFabric) LinkVersion(dev, link int) uint32

LinkVersion returns the NVLink version for a link, falling back to the fabric-wide version when the link carries none.

func (*NodeFabric) MemoryAffinityMask added in v0.3.0 

func (f *NodeFabric) MemoryAffinityMask(dev, words int) []uint64

MemoryAffinityMask packs the device's NUMA node into a little-endian bitmask of `words` 64-bit words.

func (*NodeFabric) NVLinkCount added in v0.3.0 

func (f *NodeFabric) NVLinkCount(a, b int) int

NVLinkCount returns the number of NVLinks between GPU a and GPU b.

func (*NodeFabric) NVSwitchConnectedLinkCount added in v0.3.0 

func (f *NodeFabric) NVSwitchConnectedLinkCount(dev int) int

NVSwitchConnectedLinkCount returns the number of a device's active NVLinks whose remote endpoint is an NVSwitch. This backs NVML_FI_DEV_NVSWITCH_CONNECTED_LINK_COUNT (field 147), which the 580 nvidia-smi reads per GPU in `topo -m` to detect an NVSwitch fabric and draw NV<count> between every switch-connected GPU pair. Returns 0 for direct or non-NVLink topologies (no switch endpoints), so those render no NV#.

func (*NodeFabric) NumDevices added in v0.3.0 

func (f *NodeFabric) NumDevices() int

NumDevices returns the number of devices modeled by the fabric. 

func (f *NodeFabric) NumLinks(dev int) int

NumLinks returns the number of resolved links for a device.

func (*NodeFabric) NumaNode added in v0.3.0 

func (f *NodeFabric) NumaNode(dev int) int

NumaNode returns the NUMA node for a device (-1 when unknown).

func (*NodeFabric) NvLinkCounters added in v0.3.0 

func (f *NodeFabric) NvLinkCounters(dev, link int, now time.Time) (uint64, uint64)

NvLinkCounters returns the deterministic (rx, tx) utilization counters for a link at the given time. Pure function of immutable config + clock.

func (*NodeFabric) NvLinkErrorCount added in v0.3.0 

func (f *NodeFabric) NvLinkErrorCount(dev, link int, now time.Time) uint64

NvLinkErrorCount returns the deterministic error counter for a link.

func (*NodeFabric) NvLinkSpeedMbps added in v0.3.0 

func (f *NodeFabric) NvLinkSpeedMbps(dev, link int) (uint64, bool)

NvLinkSpeedMbps returns the per-link speed in MB/s (NVML reports NVLink speed in MBps) and whether the link is active. Derived from the configured per-link bandwidth.

func (*NodeFabric) Switches added in v0.3.0 

func (f *NodeFabric) Switches() []NVSwitch

Switches returns the NVSwitch endpoint list.

func (*NodeFabric) TopoLevel added in v0.3.0 

func (f *NodeFabric) TopoLevel(a, b int) nvml.GpuTopologyLevel

TopoLevel returns the pairwise PCIe topology level between a and b.

func (*NodeFabric) Validate added in v0.3.0 

func (f *NodeFabric) Validate() []string

Validate returns human-readable warnings for unresolved NVLink endpoints. Runtime callers warn-and-continue; the built-in profile test asserts this is empty for shipped profiles (decision D-b).

type PCIConfig 

type PCIConfig struct {
	DeviceID    uint32 `json:"device_id,omitempty"`
	SubsystemID uint32 `json:"subsystem_id,omitempty"`
	BusID       string `json:"bus_id,omitempty"`
}

PCIConfig defines PCI device information

type PCIeConfig 

type PCIeConfig struct {
	MaxLinkGen       int    `json:"max_link_gen,omitempty"`
	CurrentLinkGen   int    `json:"current_link_gen,omitempty"`
	MaxLinkWidth     int    `json:"max_link_width,omitempty"`
	CurrentLinkWidth int    `json:"current_link_width,omitempty"`
	ReplayCounter    uint64 `json:"replay_counter,omitempty"`
	TxThroughputKBPS uint64 `json:"tx_throughput_kbps,omitempty"`
	RxThroughputKBPS uint64 `json:"rx_throughput_kbps,omitempty"`
}

PCIeConfig defines PCIe link information

type PCIeTopologyConfig added in v0.3.0 

type PCIeTopologyConfig struct {
	RootComplexes []RootComplexConfig `json:"root_complexes,omitempty"`
	CoresPerNUMA  int                 `json:"cores_per_numa,omitempty"`
}

PCIeTopologyConfig describes the root-complex / NUMA layout shared with render-pci-sysfs. CoresPerNUMA synthesizes a CPU affinity set per NUMA node when a root complex does not declare an explicit cpu_affinity range.

type PowerConfig 

type PowerConfig struct {
	ManagementSupported      bool   `json:"management_supported,omitempty"`
	ManagementMode           string `json:"management_mode,omitempty"`
	DefaultLimitMW           uint32 `json:"default_limit_mw,omitempty"`
	EnforcedLimitMW          uint32 `json:"enforced_limit_mw,omitempty"`
	MinLimitMW               uint32 `json:"min_limit_mw,omitempty"`
	MaxLimitMW               uint32 `json:"max_limit_mw,omitempty"`
	CurrentDrawMW            uint32 `json:"current_draw_mw,omitempty"`
	PowerState               string `json:"power_state,omitempty"`
	TotalEnergyConsumptionMJ uint64 `json:"total_energy_consumption_mj,omitempty"` // millijoules since boot
}

PowerConfig defines power management settings

type ProcessConfig 

type ProcessConfig struct {
	PID           uint32 `json:"pid"`
	Type          string `json:"type,omitempty"` // "C" for compute, "G" for graphics
	Name          string `json:"name,omitempty"`
	UsedMemoryMiB uint64 `json:"used_memory_mib,omitempty"`
	SmUtil        uint32 `json:"sm_util,omitempty"`  // SM utilization %
	MemUtil       uint32 `json:"mem_util,omitempty"` // memory-bandwidth utilization %
	EncUtil       uint32 `json:"enc_util,omitempty"` // encoder utilization %
	DecUtil       uint32 `json:"dec_util,omitempty"` // decoder utilization %
}

ProcessConfig defines a running process

type RemappedRowsConfig 

type RemappedRowsConfig struct {
	Correctable     int  `json:"correctable,omitempty"`
	Uncorrectable   int  `json:"uncorrectable,omitempty"`
	Pending         bool `json:"pending,omitempty"`
	FailureOccurred bool `json:"failure_occurred,omitempty"`
}

RemappedRowsConfig defines remapped rows information

type RemoteKind added in v0.3.0 

type RemoteKind uint8

RemoteKind classifies the far end of an NVLink. 

const (
	RemoteNone RemoteKind = iota
	RemoteGPU
	RemoteSwitch
	RemoteCPU
)
type ResolvedLink struct {
	Link       int
	Active     bool
	RemoteKind RemoteKind
	RemoteBDF  string
	RemotePeer int // device index when RemoteKind==RemoteGPU, else -1
	Version    uint32
	Caps       uint32 // bitmap indexed by nvml.NvLinkCapability
	// contains filtered or unexported fields
}

ResolvedLink is the derived per-(device,link) view used by all NVLink getters. It is computed once from the adjacency configuration.

type RetiredPagesConfig 

type RetiredPagesConfig struct {
	SingleBitRetirement *RetirementInfoConfig `json:"single_bit_retirement,omitempty"`
	DoubleBitRetirement *RetirementInfoConfig `json:"double_bit_retirement,omitempty"`
	PendingBlacklist    bool                  `json:"pending_blacklist,omitempty"`
	PendingRetirement   bool                  `json:"pending_retirement,omitempty"`
}

RetiredPagesConfig defines retired pages information

type RetirementInfoConfig 

type RetirementInfoConfig struct {
	Count     int      `json:"count,omitempty"`
	Addresses []string `json:"addresses,omitempty"`
}

RetirementInfoConfig defines retirement count and addresses

type RootComplexConfig added in v0.3.0 

type RootComplexConfig struct {
	ID       string   `json:"id,omitempty"`
	NUMANode int      `json:"numa_node,omitempty"`
	Devices  []string `json:"devices,omitempty"`
	// CPUAffinity is an optional inclusive CPU range ("0-71") or comma
	// list ("0,2,4"). When empty the affinity set is synthesized from the
	// NUMA node index and CoresPerNUMA.
	CPUAffinity string `json:"cpu_affinity,omitempty"`
}

RootComplexConfig is one PCI host bridge with its NUMA node, attached device BDFs, and an optional explicit CPU affinity range.

type SupportedClocksConfig 

type SupportedClocksConfig struct {
	MemoryClocks []MemoryClockConfig `json:"memory_clocks,omitempty"`
}

SupportedClocksConfig defines supported clock frequencies

type SystemConfig 

type SystemConfig struct {
	DriverVersion    string `json:"driver_version"`
	NVMLVersion      string `json:"nvml_version"`
	CUDAVersion      string `json:"cuda_version"`
	CUDAVersionMajor int    `json:"cuda_version_major"`
	CUDAVersionMinor int    `json:"cuda_version_minor"`
	NumDevices       int    `json:"num_devices,omitempty"`
}

SystemConfig contains system-level NVML settings

type ThermalConfig 

type ThermalConfig struct {
	TemperatureGPU_C    int `json:"temperature_gpu_c,omitempty"`
	TemperatureMemory_C int `json:"temperature_memory_c,omitempty"`
	ShutdownThreshold_C int `json:"shutdown_threshold_c,omitempty"`
	SlowdownThreshold_C int `json:"slowdown_threshold_c,omitempty"`
	MaxOperating_C      int `json:"max_operating_c,omitempty"`
	TargetTemperature_C int `json:"target_temperature_c,omitempty"`
}

ThermalConfig defines thermal settings

type TopologyClique added in v0.2.0 

type TopologyClique struct {
	ID    uint32   `json:"id"`
	Nodes []string `json:"nodes"`
}

TopologyClique groups the Kubernetes node names that share a clique inside a fabric domain.

type TopologyConfig 

type TopologyConfig struct {
	DefaultLevel string `json:"default_level,omitempty"` // internal, single, multiple, hostbridge, node, system
}

TopologyConfig defines GPU topology settings

type TopologyDocument added in v0.2.0 

type TopologyDocument struct {
	Version int              `json:"version"`
	Domains []TopologyDomain `json:"domains"`
}

TopologyDocument is the cluster-level ConfigMap that maps individual nodes (by Kubernetes node name) to fabric clusters and cliques. It is the single source of truth for ComputeDomain topology in the mock.

At LoadConfig() time the engine looks up the current node (via NODE_NAME) and, if found in the topology, overrides the per-device FabricConfig.ClusterUUID / CliqueID. Nodes absent from the topology keep their default fabric config (or report NOT_SUPPORTED when no FabricConfig is present).

type TopologyDomain added in v0.2.0 

type TopologyDomain struct {
	Name    string           `json:"name,omitempty"`
	UUID    string           `json:"uuid"`
	Cliques []TopologyClique `json:"cliques"`
}

TopologyDomain represents one NVLink fabric domain (cluster UUID).

type UtilizationConfig 

type UtilizationConfig struct {
	GPU     uint32 `json:"gpu,omitempty"`
	Memory  uint32 `json:"memory,omitempty"`
	Encoder uint32 `json:"encoder,omitempty"`
	Decoder uint32 `json:"decoder,omitempty"`
	JPEG    uint32 `json:"jpeg,omitempty"`
	OFA     uint32 `json:"ofa,omitempty"`
}

UtilizationConfig defines utilization percentages

type VirtualizationConfig 

type VirtualizationConfig struct {
	Mode         string `json:"mode,omitempty"`
	HostVGPUMode string `json:"host_vgpu_mode,omitempty"`
}

VirtualizationConfig defines virtualization settings

type XidErrorConfig added in v0.2.0 

type XidErrorConfig struct {
	Code uint64 `json:"code,omitempty"`
}

XidErrorConfig models a Xid critical error to surface when a failure trips. Code matches the kernel-driver Xid number (e.g. 79 = "GPU has fallen off the bus", 64 = "ECC double-bit error").

type YAMLConfig 

type YAMLConfig struct {
	Version        string           `json:"version"`
	System         SystemConfig     `json:"system"`
	DeviceDefaults DeviceConfig     `json:"device_defaults"`
	Devices        []DeviceOverride `json:"devices"`
	NVLink         *NVLinkConfig    `json:"nvlink,omitempty"`

	// PCIeTopology promotes the root-complex / NUMA layout (previously
	// consumed only by cmd/render-pci-sysfs) into the engine so NVLink
	// topology, pairwise PCIe levels, and CPU/NUMA affinity all derive
	// from the same facts. Optional; absent on PCIe-only profiles.
	PCIeTopology *PCIeTopologyConfig `json:"pcie_topology,omitempty"`
}

YAMLConfig represents the top-level YAML configuration for mock NVML. Use MOCK_NVML_CONFIG environment variable to specify the config file path.

func LoadYAMLConfig 

func LoadYAMLConfig(path string) (*YAMLConfig, error)

LoadYAMLConfig loads and parses a YAML configuration file

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.