Help us shape the future of Go! Take the 2026 Go Developer Survey

engine

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package engine is the pure-Go mock NVML runtime driving the mocknvml bridge.

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 (
	FabricHealthSummaryNotSupported    uint8 = 0
	FabricHealthSummaryHealthy         uint8 = 1
	FabricHealthSummaryUnhealthy       uint8 = 2
	FabricHealthSummaryLimitedCapacity uint8 = 3
)

FabricHealthSummary* values mirror NVML_GPU_FABRIC_HEALTH_SUMMARY_* from the public NVML header, re-declared here for the same reason as FabricState*: the engine layer stays free of CGo and callers compare against named constants. fabric_health_test.go pins them against go-nvml.

A zero summary means "the driver did not report health", which nvidia-smi renders as N/A for every row of the Fabric.Health block — including the per-condition rows it would otherwise decode out of the health mask. That is why the mock defaults to Healthy rather than to the Go zero value.

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 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 (
	PeerTypeDirectConnected uint8 = 0
	PeerTypeSwitchConnected uint8 = 1
)

PeerType* are the platform-indicated NVLink peer types NVML reports in nvmlPlatformInfo_t.peerType ("switch present or not"), which `nvidia-smi -q` renders as "Direct Connected" / "Switch Connected". The numeric encoding is not published in nvml.h; it is pinned here by the rendering an NVL72 profile produces, where a GPU reaching its peers through an NVSwitch tray is "Switch Connected".

View Source 
const (
	SystemEventTypeGpuDriverUnbind uint64 = 0x1
	SystemEventTypeGpuDriverBind   uint64 = 0x2
)

The two event types NVML's system event set carries. Unlike the per-device mask, which enumerates Xid classes, the system set reports only whether a GPU is bound to the driver.

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 (

	// VirtualizationModeHostVGPU makes a GPU a vGPU host: a hypervisor's
	// physical GPU running the vGPU manager and the declared instances.
	VirtualizationModeHostVGPU = "host_vgpu"
	// VirtualizationModeVGPU makes a GPU the vGPU a VM sees.
	VirtualizationModeVGPU = "vgpu"
)
View Source 
const CPERAccessTypeGPU uint32 = 1 << 0

CPERAccessTypeGPU mirrors NVML_CPER_ACCESS_TYPE_GPU. It is the only record source NVML defines, so a query whose mask omits it matches nothing.

View Source 
const DefaultBAR1SizeMB = 256

DefaultBAR1SizeMB is the default simulated BAR1 aperture size in megabytes.

View Source 
const EnvMIGProfilesConfig = "MOCK_MIG_PROFILES_CONFIG"

EnvMIGProfilesConfig names the board's MIG profile table explicitly. The chart sets it because the table mounts from a ConfigMap of its own, at a path the config's directory does not predict.

View Source 
const HICFirmwareVersionMaxLen = 31

HICFirmwareVersionMaxLen mirrors the firmwareVersion array in nvmlHwbcEntry_t. A longer configured string is truncated rather than rejected: a profile typo should not fail the whole query.

View Source 
const HostnameMaxLen = 63

HostnameMaxLen is the longest hostname that fits NVML_DEVICE_HOSTNAME_BUFFER_SIZE (64) alongside its NUL terminator.

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 ApplyMIGProfilesOverlay added in v0.5.0 

func ApplyMIGProfilesOverlay(yamlConfig *YAMLConfig, configPath string) error

ApplyMIGProfilesOverlay attaches a board's MIG profile table to yamlConfig.DeviceDefaults.MIG from a document of its own, so the profile describing the board does not have to carry several hundred rows of partition geometry.

It is exported because the node agent has to reach the same table: it stages the capability nodes for the partitions NVML enumerates, so resolving the table differently there would leave a board that partitions under NVML with no cap device to reach a partition through.

It mirrors applyTopologyOverlay: resolve a path, and return quietly when nothing is mounted there. A board with no resolvable table is simply not MIG-capable, which is already what a board declaring no profiles means, so an absent file is logged at debug level — enough to diagnose a mount that did not arrive — and not an error.

A table that *is* there and cannot be used is the opposite case: the operator authored something wrong and needs telling, so it fails the load rather than leaving a broken board looking deliberately non-MIG.

Resolution order for the table path:

  1. EnvMIGProfilesConfig (explicit path, what the chart sets because the table mounts from its own ConfigMap at its own path)
  2. A sibling of the config: config.yaml -> config.mig.yaml, which is what makes a local run and the standalone configs work with no environment set at all.

func BaseDevicePCIBusID added in v0.4.0 

func BaseDevicePCIBusID(index int) string

BaseDevicePCIBusID returns the address a device index serves when its profile declares no pci.bus_id: the one it inherits from the base mock. It is "" for an index the base does not cover — the engine creates no device there.

Exported for callers outside the engine that must name a device the way the running mock names it, such as the node agent announcing an Xid on the kernel log for a profile that leaves addresses to the mock.

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 ConfigOverridePath added in v0.4.0 

func ConfigOverridePath() string

ConfigOverridePath is the overrides file the engine reads, for callers that need to mutate it rather than observe it — the GPU reset path writes through the same resolution the reader uses so the two can never disagree on which file is authoritative.

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 DeviceMinorNumber added in v0.4.0 

func DeviceMinorNumber(config *YAMLConfig, index int) int

DeviceMinorNumber returns the /dev/nvidia<N> a device is staged under, defaulting to the index for devices that do not declare one — the numbering a driver produces when it probes in PCI enumeration order.

The agent and the engine both resolve minors through here so the nodes that get staged and the nodes the visibility filter looks for cannot drift apart.

func EccClearPatch added in v0.6.0 

func EccClearPatch(scope EccCounterScope) map[string]any

EccClearPatch is the override a counter clear writes. The zeros are explicit because the counters may come from the profile, and only a written zero outranks them in the merge.

func FabricIncorrectConfigNames added in v0.4.0 

func FabricIncorrectConfigNames() []string

FabricIncorrectConfigNames lists the accepted fabric.health incorrect_configuration values, so the CLI and its help text cannot drift from what the engine parses.

func FieldAvailable added in v0.6.0 

func FieldAvailable(fieldID uint32, driverVersion string) bool

FieldAvailable reports whether the given driver version knows a field id. Power smoothing arrived in 570 as a unit, the field ids that read it with the setters that write it, so a driver without the setters reports none of the fields rather than a feature nothing can control. Other ids default to available, as unknown functions do.

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 MIGProfilesPathFor added in v0.5.0 

func MIGProfilesPathFor(configPath string) string

MIGProfilesPathFor resolves the MIG profile table path, or "" when neither source names one. See ApplyMIGProfilesOverlay for why the order is this way.

Exported alongside it so a caller that has to watch the table for changes names the same file the overlay will read, rather than guessing at it.

func MIGProfilesSiblingPath added in v0.5.0 

func MIGProfilesSiblingPath(configPath string) string

MIGProfilesSiblingPath returns the table path that sits beside configPath: config.yaml -> config.mig.yaml, and "" for an empty path.

It is the naming rule on its own, without the environment MIGProfilesPathFor consults, for a caller that has to *write* a table a later reader will resolve by this rule — the node agent staging a config for consumer processes, which carry no environment naming a table of their own.

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 PowerSmoothingProfilePatch added in v0.6.0 

func PowerSmoothingProfilePatch(profileID uint32, param PowerSmoothingParam, value float64) map[string]any

PowerSmoothingProfilePatch builds the override patch recording one preset parameter. It lives here, beside ConfigKey, so the writer and the config type cannot disagree on the shape.

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.

func SetOverrideWriter added in v0.5.0 

func SetOverrideWriter(w OverrideWriter)

SetOverrideWriter installs the writer the setters persist through. A nil writer uninstalls, which is what a test restoring the previous one passes.

func ValidateConfig added in v0.5.0 

func ValidateConfig(config *YAMLConfig) error

ValidateConfig checks a profile by the rules LoadYAMLConfig applies, for callers that hold a decoded config rather than a path.

The node agent is why this is exported: it stages the document this library later loads, and a profile it accepts that LoadYAMLConfig then rejects does not surface as an error, because LoadConfig answers a rejected profile with DefaultConfig. The node would simulate eight A100s while the devices, capability nodes and CDI entries staged beside the config describe the board the profile named.

func ValidateMinorNumbers added in v0.4.0 

func ValidateMinorNumbers(config *YAMLConfig) error

ValidateMinorNumbers rejects minors that no device node can carry and minors two devices would end up sharing. Defaulted devices take part: one that never declares a minor still occupies its index, so an explicit value elsewhere can collide with it.

func ValidateUniqueBDFs added in v0.5.0 

func ValidateUniqueBDFs(config *YAMLConfig) error

ValidateUniqueBDFs rejects a PCI address that more than one function claims.

A BDF is a hardware address, so two functions cannot share one, and a consumer holding an address has no way to tell which of them it reached. The rendered PCI tree is where a collision does its damage silently: it holds one entry per address, so a switch landing on a GPU's BDF takes over the GPU's node and gives it the bridge class, and GPU Feature Discovery then derives nvidia.com/gpu.mode for a GPU it is inspecting as fabric silicon.

Switches count whether or not they are PCIe-visible. An address is no more shareable for being absent from the tree today, and adding device_id to a switch should not be the edit that turns a latent collision into a GPU with the wrong class.

Types

type AccountedProcessConfig added in v0.6.0 

type AccountedProcessConfig struct {
	PID          uint32 `json:"pid"`
	GPUUtil      uint32 `json:"gpu_util,omitzero"` // lifetime SM utilization %
	MemUtil      uint32 `json:"mem_util,omitzero"` // lifetime memory-bandwidth utilization %
	MaxMemoryMiB uint64 `json:"max_memory_mib,omitzero"`
	TimeMS       uint64 `json:"time_ms,omitzero"` // how long the process ran
}

AccountedProcessConfig is the accounting record of a process that has exited.

type AccountingConfig 

type AccountingConfig struct {
	Mode       string `json:"mode,omitempty"`
	BufferSize int    `json:"buffer_size,omitzero"`
	// Terminated runs oldest to newest, so a full buffer drops from the front.
	Terminated []AccountedProcessConfig `json:"terminated,omitempty"`
}

AccountingConfig defines accounting mode settings. Running processes are accounted from Processes; Terminated holds the records of processes that have already exited, which the driver keeps until they are cleared or overwritten.

type BAR1MemoryConfig 

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

BAR1MemoryConfig defines BAR1 aperture settings

type CPERQuery added in v0.6.0 

type CPERQuery struct {
	TypeMask uint32
	// UUID filters to one GPU. Empty matches every GPU, which is what NVML
	// documents for an empty uuid string.
	UUID   string
	Handle uint64
}

CPERQuery is the engine-side view of nvmlCPERCursor_v1_t.

type CPERResult added in v0.6.0 

type CPERResult struct {
	// Payload holds whole records only; a record is never split across calls.
	Payload []byte
	// NextHandle is the cursor the caller must pass on the following call.
	NextHandle uint64
	// Required is the buffer size the caller needs. It is set both for a size
	// query and when the supplied buffer could not hold the next record.
	Required uint32
}

CPERResult is what the bridge copies back into nvmlGetCPER_v1_t.

type CPUConfig added in v0.4.0 

type CPUConfig struct {
	Type           string `json:"type,omitempty"`
	Cores          int    `json:"cores,omitzero"`
	MemoryGB       int    `json:"memory_gb,omitzero"`
	CoherentMemory bool   `json:"coherent_memory,omitzero"`
}

CPUConfig describes the host CPU the board is attached to. Type is free-form and names the CPU family — "grace" on the superchip profiles. An absent block means the profile makes no claim about its host, which is the honest reading for a PCIe or SXM part that can ship behind any CPU.

Descriptive metadata that no getter reads, on the same terms as FeaturesConfig.

type ClockDomain added in v0.5.0 

type ClockDomain string

ClockDomain names a clock domain the locked-clock and offset setters write under: the key of its locked_<domain> range and of its offsets.<domain> entry. 

const (
	ClockDomainGraphics ClockDomain = "graphics"
	ClockDomainMemory   ClockDomain = "memory"
)

The clock domains a setter can write. Graphics covers the SM clock too, which is derived from the GPC clock it names.

type ClockOffsetConfig added in v0.5.0 

type ClockOffsetConfig struct {
	MinMHz    int32 `json:"min_mhz"`
	MaxMHz    int32 `json:"max_mhz"`
	OffsetMHz int32 `json:"offset_mhz,omitzero"`
}

ClockOffsetConfig is one domain's offset range and the offset currently applied, all in MHz. OffsetMHz is what nvmlDeviceSetClockOffsets records.

type ClockOffsetsConfig added in v0.5.0 

type ClockOffsetsConfig struct {
	Graphics *ClockOffsetConfig `json:"graphics,omitempty"`
	Memory   *ClockOffsetConfig `json:"memory,omitempty"`
}

ClockOffsetsConfig declares the per-domain clock offsets of a board.

type ClockRangeConfig added in v0.5.0 

type ClockRangeConfig struct {
	MinMHz uint32 `json:"min_mhz"`
	MaxMHz uint32 `json:"max_mhz"`
}

ClockRangeConfig is an inclusive clock range in MHz.

type ClocksConfig 

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

	// LockedGraphics and LockedMemory are the ranges `nvidia-smi -lgc` and
	// `-lmc` pin the clocks to. Unset means unlocked. They are runtime state
	// recorded in the override document, though a profile may declare them to
	// model a node that boots with clocks already locked.
	LockedGraphics *ClockRangeConfig `json:"locked_graphics,omitempty"`
	LockedMemory   *ClockRangeConfig `json:"locked_memory,omitempty"`

	// Offsets declares the clock offsets the board accepts. A domain left unset
	// answers NOT_SUPPORTED, which is what the offset getters report on boards
	// that do not expose overclocking.
	Offsets *ClockOffsetsConfig `json:"offsets,omitempty"`

	// AdaptiveClocking is "enabled" or "disabled"; unset answers NOT_SUPPORTED.
	AdaptiveClocking string `json:"adaptive_clocking,omitempty"`
}

ClocksConfig defines clock speed settings

type ClocksThrottleReasonsConfig 

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

	// Counters seeds the cumulative time each cause has already cost the GPU.
	// The flags above answer "is it throttled now"; the counters answer "how
	// long has it been", which is what a slow workload is diagnosed from.
	Counters *ThrottleCountersConfig `json:"counters,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 ComputeInstanceTable added in v0.5.0 

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

ComputeInstanceTable maps C handles to MIG compute instances, playing the same role for nvmlComputeInstance_t that GpuInstanceTable does for GPU instances.

func NewComputeInstanceTable added in v0.5.0 

func NewComputeInstanceTable() *ComputeInstanceTable

NewComputeInstanceTable creates an empty compute instance handle table.

func (*ComputeInstanceTable) Clear added in v0.5.0 

func (s *ComputeInstanceTable) Clear()

Clear invalidates every registered handle. The C blocks are retired, not freed (see handleStore.retired), so handles issued before the Clear stay invalid for the lifetime of the table even after new registrations.

func (*ComputeInstanceTable) Count added in v0.5.0 

func (s *ComputeInstanceTable) Count() int

Count returns the number of registered handles.

func (*ComputeInstanceTable) Free added in v0.5.0 

func (s *ComputeInstanceTable) Free()

Free releases every block, live and retired. Only for tests and teardown; any handle a client still holds becomes a dangling pointer afterwards.

func (*ComputeInstanceTable) HandleFor added in v0.5.0 

func (s *ComputeInstanceTable) HandleFor(item T) unsafe.Pointer

HandleFor returns the registered handle for an object, or nil when it has not been registered. Used by wiring that needs to translate an object back into 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 lets the caller treat that case as "no event yet".

func (*ComputeInstanceTable) Lookup added in v0.5.0 

func (t *ComputeInstanceTable) Lookup(handle unsafe.Pointer) (nvml.ComputeInstance, bool)

Lookup returns the compute instance for a handle, or false when the handle is not one this table issued or has since been retired.

func (*ComputeInstanceTable) Register added in v0.5.0 

func (s *ComputeInstanceTable) Register(item T) unsafe.Pointer

Register adds an object to the table and returns its handle, reusing the existing handle when the object is already registered. The handle is a pointer to C-allocated memory.

func (*ComputeInstanceTable) Retire added in v0.5.0 

func (s *ComputeInstanceTable) Retire(item T)

Retire invalidates the handle for a single object, for the MIG instances that are destroyed while the library stays loaded. The block is retired rather than freed, so the caller's now-stale handle keeps failing lookup instead of aliasing a later instance that reused the address.

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.

The config path comes from resolveConfigPath; without one, env vars and defaults apply.

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,omitzero"`
	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) ClearAccountingPids added in v0.6.0 

func (d *ConfigurableDevice) ClearAccountingPids() nvml.Return

ClearAccountingPids drops the records of processes that have exited. Running processes stay queryable.

func (*ConfigurableDevice) ClearEccErrorCounts added in v0.6.0 

func (d *ConfigurableDevice) ClearEccErrorCounts(counterType nvml.EccCounterType) nvml.Return

ClearEccErrorCounts zeroes one scope of ECC counters. The SRAM counters go with the DRAM ones because both are error counters of the same scope. Clearing the aggregate scope also drops the unit attribution and the SRAM threshold flag: both are derived from the counters, so they cannot outlive them.

func (*ConfigurableDevice) ClearFieldValues added in v0.5.0 

func (d *ConfigurableDevice) ClearFieldValues(values []nvml.FieldValue) nvml.Return

ClearFieldValues declines each field on its own while the call succeeds, the per-value contract nvml.h documents. The mock derives its counters from the profile and the shared epoch instead of accumulating them, so none has state a caller could reset.

func (*ConfigurableDevice) ClockOffset added in v0.5.0 

func (d *ConfigurableDevice) ClockOffset(clockType nvml.ClockType, pstate nvml.Pstates) (nvml.ClockOffset, nvml.Return)

ClockOffset returns the offset applied to one domain at one P-state, with the range the board accepts. Offsets exist only for the modelled P-state and for the domains clocks.offsets declares. They are recorded and reported, but do not shift the simulated clocks: no capture shows how a real board's readings move under an offset.

func (*ConfigurableDevice) CoolerInfo added in v0.5.0 

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

CoolerInfo describes what one cooler drives and how, backing nvmlDeviceGetCoolerInfo. Every discrete board with dedicated fans reports a variable signal cooling the GPU, so that is what a fanned profile reports; there is no config for it because nothing in the Kubernetes GPU stack distinguishes a toggle cooler from a variable one. Version is left for the bridge to stamp, since the tag belongs to the C struct rather than to the reading.

Like FanSpeedRPM the index crosses the C ABI inside the caller's struct, so this rather than GetCoolerInfo is what the bridge calls.

func (*ConfigurableDevice) CreateGpuInstance added in v0.5.0 

func (d *ConfigurableDevice) CreateGpuInstance(
	info *nvml.GpuInstanceProfileInfo,
) (nvml.GpuInstance, nvml.Return)

CreateGpuInstance partitions the GPU, choosing the first placement that still fits. Real NVML picks a placement for the caller in the same way.

func (*ConfigurableDevice) CreateGpuInstanceWithPlacement added in v0.5.0 

func (d *ConfigurableDevice) CreateGpuInstanceWithPlacement(
	info *nvml.GpuInstanceProfileInfo, placement *nvml.GpuInstancePlacement,
) (nvml.GpuInstance, nvml.Return)

CreateGpuInstanceWithPlacement partitions the GPU at a caller-chosen offset.

func (*ConfigurableDevice) CurrentClockFreqs added in v0.5.0 

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

CurrentClockFreqs renders the nvmlDeviceGetCurrentClockFreqs string: the clocks in effect now against the envelope they may move within.

func (*ConfigurableDevice) FanSpeedRPM added in v0.5.0 

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

FanSpeedRPM reports one fan's tachometer reading, backing nvmlDeviceGetFanSpeedRPM. The RPM is scaled from the duty cycle by the profile's ceiling, and a profile that declares no ceiling reports no RPM: driving a fan and measuring it are separate capabilities on real hardware, so the percentage can answer where this does not.

The fan index is a parameter here but rides in the caller's struct across the C ABI, which is why GetFanSpeedRPM below cannot take it and this is the entry point the bridge uses.

func (*ConfigurableDevice) FreezeNvLinkUtilizationCounter added in v0.3.0 

func (d *ConfigurableDevice) FreezeNvLinkUtilizationCounter(link, _ int, _ 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 how many records the circular buffer holds.

func (*ConfigurableDevice) GetAccountingMode 

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

GetAccountingMode reports whether per-process accounting is on. A MIG-enabled GPU reports it off whatever the profile says, as the NVML header documents.

func (*ConfigurableDevice) GetAccountingPids added in v0.6.0 

func (d *ConfigurableDevice) GetAccountingPids() ([]int, nvml.Return)

GetAccountingPids lists the processes with an accounting record, oldest first.

func (*ConfigurableDevice) GetAccountingStats added in v0.6.0 

func (d *ConfigurableDevice) GetAccountingStats(pid uint32) (nvml.AccountingStats, nvml.Return)

GetAccountingStats returns one process's accounting record.

func (*ConfigurableDevice) GetAccountingStats_v2 added in v0.6.0 

func (d *ConfigurableDevice) GetAccountingStats_v2(pid uint32) (nvml.AccountingStats_v2, nvml.Return)

GetAccountingStats_v2 returns one process's accounting record with the per-sample sums the v2 struct adds.

func (*ConfigurableDevice) GetAdaptiveClockInfoStatus added in v0.5.0 

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

GetAdaptiveClockInfoStatus reports clocks.adaptive_clocking. No capture records it, so a profile that does not declare it answers NOT_SUPPORTED.

func (*ConfigurableDevice) GetAddressingMode added in v0.5.0 

func (d *ConfigurableDevice) GetAddressingMode() (nvml.DeviceAddressingMode, nvml.Return)

GetAddressingMode reports the profile's addressing_mode. A profile that does not declare one answers NOT_SUPPORTED, which nvidia-smi renders as N/A, rather than claiming a mode the modelled host may not run.

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) GetAttributes added in v0.5.0 

func (d *ConfigurableDevice) GetAttributes() (nvml.DeviceAttributes, nvml.Return)

GetAttributes returns a MIG device's engine and memory allocation. This is a MIG-only query, and the one the device plugin compares across devices before it will accept a node with migStrategy=single.

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) GetBBXTimeData_v1 added in v0.5.0 

func (d *ConfigurableDevice) GetBBXTimeData_v1() (nvml.BBXTimeData_v1, nvml.Return)

GetBBXTimeData_v1 reports how long the driver has been loaded, read off the shared epoch NVLink counters accrue from, so every process agrees on it and it grows between invocations. Real hardware accumulates this over the board's whole life; the mock's board was new when the driver loaded.

func (*ConfigurableDevice) GetBoardId 

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

GetBoardId returns the board ID derived from the device's PCI address.

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) GetBridgeChipInfo added in v0.5.0 

func (d *ConfigurableDevice) GetBridgeChipInfo() (nvml.BridgeChipHierarchy, nvml.Return)

GetBridgeChipInfo declines: bridge chips sit on multi-GPU boards, nvml.h answers NOT_SUPPORTED everywhere else, and no mocked board is one.

func (*ConfigurableDevice) GetBusType added in v0.5.0 

func (d *ConfigurableDevice) GetBusType() (nvml.BusType, nvml.Return)

GetBusType reports how the GPU attaches to the host. Every mocked board is a PCIe device — the simulated sysfs tree and /proc/driver/nvidia both say so — including Grace boards, whose GPUs enumerate over PCIe alongside C2C.

func (*ConfigurableDevice) GetCapabilities added in v0.5.0 

func (d *ConfigurableDevice) GetCapabilities() (nvml.DeviceCapabilities, nvml.Return)

GetCapabilities reports an empty capability mask. EGM (Extended GPU Memory) is the only capability NVML defines, and it is disabled on every captured board, Grace hosts included: it has to be turned on in the kernel module.

func (*ConfigurableDevice) GetClkMonStatus added in v0.5.0 

func (d *ConfigurableDevice) GetClkMonStatus() (nvml.ClkMonStatus, nvml.Return)

GetClkMonStatus reports a healthy clock monitor: no global fault and no faulted clock domain. Clock monitors arrived with Ampere, so earlier GPUs decline.

func (*ConfigurableDevice) GetClock added in v0.4.0 

func (d *ConfigurableDevice) GetClock(clockType nvml.ClockType, clockID nvml.ClockId) (uint32, nvml.Return)

GetClock is NVML's two-dimensional clock lookup, clock domain x clock id. It routes to the getter that owns each value instead of re-reading the clocks: block, so this generic entry point and the dedicated ones cannot disagree — including about which combinations are unsupported.

func (*ConfigurableDevice) GetClockInfo 

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

GetClockInfo returns current clock frequencies

func (*ConfigurableDevice) GetComputeInstanceId added in v0.5.0 

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

GetComputeInstanceId returns the ID of the compute instance backing a MIG device.

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) GetConfComputeMemSizeInfo added in v0.4.0 

func (d *ConfigurableDevice) GetConfComputeMemSizeInfo() (nvml.ConfComputeMemSizeInfo, nvml.Return)

GetConfComputeMemSizeInfo reports how device memory is split between the protected and unprotected halves of a Confidential Compute partition, backing nvmlDeviceGetConfComputeMemSizeInfo. Both halves are zero while CC mode is off, which is every profile.

func (*ConfigurableDevice) GetConfComputeProtectedMemoryUsage added in v0.4.0 

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

GetConfComputeProtectedMemoryUsage reports occupancy of the protected memory region, backing nvmlDeviceGetConfComputeProtectedMemoryUsage and the "Conf Compute Protected Memory Usage" block of `nvidia-smi -q`. With CC mode off there is no protected region, so total, used and free are all zero.

func (*ConfigurableDevice) GetConfig 

func (d *ConfigurableDevice) GetConfig() *DeviceConfig

GetConfig returns the device configuration

func (*ConfigurableDevice) GetCoolerInfo added in v0.5.0 

func (d *ConfigurableDevice) GetCoolerInfo() (nvml.CoolerInfo, nvml.Return)

GetCoolerInfo satisfies the go-nvml Device contract, whose binding leaves the cooler index at its zero value and so can only ever ask about the first cooler.

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, _ 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) GetDeviceHandleFromMigDeviceHandle added in v0.5.0 

func (d *ConfigurableDevice) GetDeviceHandleFromMigDeviceHandle() (nvml.Device, nvml.Return)

GetDeviceHandleFromMigDeviceHandle returns the physical GPU behind a MIG device. ERROR_INVALID_ARGUMENT on a full GPU matches real NVML: the handle is simply the wrong kind for this query.

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) GetDramEncryptionMode added in v0.6.0 

func (d *ConfigurableDevice) GetDramEncryptionMode() (nvml.DramEncryptionInfo, nvml.DramEncryptionInfo, nvml.Return)

GetDramEncryptionMode returns the current and pending DRAM encryption modes. Only Blackwell and newer boards have the feature.

func (*ConfigurableDevice) GetDynamicPstatesInfo added in v0.5.0 

func (d *ConfigurableDevice) GetDynamicPstatesInfo() (nvml.GpuDynamicPstatesInfo, nvml.Return)

GetDynamicPstatesInfo reports the utilization the driver's P-state governor samples. Only the graphics and frame-buffer domains are present, from the same readings as nvmlDeviceGetUtilizationRates; the video and bus domains have no simulated load behind them. The governor's thresholds are not modelled and read as 0.

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) GetFanControlPolicy_v2 added in v0.5.0 

func (d *ConfigurableDevice) GetFanControlPolicy_v2(fan int) (nvml.FanControlPolicy, nvml.Return)

GetFanControlPolicy_v2 reports whether one fan follows the driver's temperature curve or a duty cycle a consumer asked for, backing nvmlDeviceGetFanControlPolicy_v2.

func (*ConfigurableDevice) GetFanSpeed 

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

GetFanSpeed returns fan speed percentage.

NVML's unindexed reading is the board's first fan, so it resolves through the same path as GetFanSpeed_v2(0) and reports a manually held duty cycle. That makes this the one place a fan write is visible to nvidia-smi, whose whole fan surface is this getter and `--query-gpu=fan.speed`.

func (*ConfigurableDevice) GetFanSpeedRPM added in v0.5.0 

func (d *ConfigurableDevice) GetFanSpeedRPM() (nvml.FanSpeedInfo, nvml.Return)

GetFanSpeedRPM satisfies the go-nvml Device contract, whose binding leaves the fan index at its zero value and so can only ever ask about the first fan. Version is left for the caller to stamp, as go-nvml's own binding does.

func (*ConfigurableDevice) GetFanSpeed_v2 

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

GetFanSpeed_v2 reports one fan's duty cycle, backing nvmlDeviceGetFanSpeed_v2. Unlike the board-wide GetFanSpeed it addresses a single fan, so it bounds the index and honours a manual duty cycle written for that fan alone.

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: power smoothing, then the other device-scope fields, 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) GetGpcClkMinMaxVfOffset added in v0.5.0 

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

GetGpcClkMinMaxVfOffset returns the graphics clock offset range.

func (*ConfigurableDevice) GetGpcClkVfOffset added in v0.5.0 

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

GetGpcClkVfOffset returns the graphics clock offset.

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) GetGpuInstanceById added in v0.5.0 

func (d *ConfigurableDevice) GetGpuInstanceById(id int) (nvml.GpuInstance, nvml.Return)

GetGpuInstanceById looks a GPU instance up by ID. go-nvml's mock leaves this unset, but it is on go-nvlib's path from a MIG device back to its profile.

func (*ConfigurableDevice) GetGpuInstanceId added in v0.5.0 

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

GetGpuInstanceId returns the ID of the GPU instance backing a MIG device.

func (*ConfigurableDevice) GetGpuInstancePossiblePlacements added in v0.5.0 

func (d *ConfigurableDevice) GetGpuInstancePossiblePlacements(
	info *nvml.GpuInstanceProfileInfo,
) ([]nvml.GpuInstancePlacement, nvml.Return)

GetGpuInstancePossiblePlacements returns the slice offsets a profile can occupy.

func (*ConfigurableDevice) GetGpuInstanceProfileInfo added in v0.5.0 

func (d *ConfigurableDevice) GetGpuInstanceProfileInfo(profileID int) (nvml.GpuInstanceProfileInfo, nvml.Return)

GetGpuInstanceProfileInfo returns a GPU instance profile the board supports.

func (*ConfigurableDevice) GetGpuInstanceRemainingCapacity added in v0.5.0 

func (d *ConfigurableDevice) GetGpuInstanceRemainingCapacity(
	info *nvml.GpuInstanceProfileInfo,
) (int, nvml.Return)

GetGpuInstanceRemainingCapacity reports how many more instances of a profile still fit. nvidia-mig-parted asks this before partitioning.

func (*ConfigurableDevice) GetGpuInstances added in v0.5.0 

func (d *ConfigurableDevice) GetGpuInstances(
	info *nvml.GpuInstanceProfileInfo,
) ([]nvml.GpuInstance, nvml.Return)

GetGpuInstances returns the live GPU instances matching a profile.

func (*ConfigurableDevice) GetGpuMaxPcieLinkGeneration added in v0.4.0 

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

GetGpuMaxPcieLinkGeneration returns the maximum PCIe link generation the GPU itself supports, independent of the host. nvidia-smi renders this as the "Device Max" row, which degraded to N/A while this was a generated stub. The mock has no separate host-side limit, so the device maximum is the configured max_link_gen — the same value GetMaxPcieLinkGeneration reports for the system-wide "Max" row.

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) GetGridLicensableFeatures added in v0.6.0 

func (d *ConfigurableDevice) GetGridLicensableFeatures() (nvml.GridLicensableFeatures, nvml.Return)

GetGridLicensableFeatures overrides the embedded mock. A guest reports one licensable feature: the vGPU product its config names.

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) GetHostVgpuMode added in v0.6.0 

func (d *ConfigurableDevice) GetHostVgpuMode() (nvml.HostVgpuMode, nvml.Return)

GetHostVgpuMode overrides the embedded mock.

func (*ConfigurableDevice) GetHostname added in v0.6.0 

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

GetHostname returns the hostname set on the device, falling back to the profile's `hostname` key. A device that has never been given one reports the empty string with SUCCESS: NVML's documented return set has no "unset" error, and the string is what a caller reads back after a successful set.

func (*ConfigurableDevice) GetIndex 

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

GetIndex returns the zero-based ordinal among visible devices. A handle for a hidden device returns ERROR_INVALID_ARGUMENT.

func (*ConfigurableDevice) GetInforomConfigurationChecksum added in v0.6.0 

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

GetInforomConfigurationChecksum returns a checksum of the InfoROM versions the profile declares: stable for one profile, and different for another, which is all a consumer comparing checksums across GPUs or reboots relies on.

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) GetIrqNum added in v0.5.0 

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

GetIrqNum declines: no profile declares an interrupt line, and a consumer that needs one is better served by no answer than by a number that names nothing on the host. The simulated sysfs irq file reads 0 for the same reason.

func (*ConfigurableDevice) GetJpgUtilization added in v0.4.0 

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

GetJpgUtilization returns NVJPG (JPEG engine) utilization from utilization.jpeg. Architectures without an NVJPG engine would answer NOT_SUPPORTED on real hardware; every profile the mock ships has one, so a configured percentage is always reportable.

func (*ConfigurableDevice) GetLastBBXFlushTime added in v0.5.0 

func (d *ConfigurableDevice) GetLastBBXFlushTime() (uint64, uint, nvml.Return)

GetLastBBXFlushTime answers NOT_READY: the black box has not been flushed during this driver run. Real hardware reports the same until its first flush, which is what the freshly booted A100, B200, L40S and T4 captures show; modelling a later flush would mean inventing the driver's schedule.

func (*ConfigurableDevice) GetMPSComputeRunningProcesses added in v0.6.0 

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

GetMPSComputeRunningProcesses returns the MPS clients. Under MPS the compute list shows the MPS server, whose context the clients' work runs in, so the clients are reported here and nowhere else among the running-process lists.

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. Ada and later only, and 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) GetMaxCustomerBoostClock added in v0.4.0 

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

GetMaxCustomerBoostClock returns the OEM-defined boost ceiling, the "Max Customer Boost Clocks" row of nvidia-smi -q.

It resolves from graphics_max rather than a key of its own because every real-hardware capture in tests/e2e/go/assertions/nvidiasmi/testdata/hardware reports max_customer_boost_clocks equal to max_clocks — A100, H100, L40S, T4, B200, GB200 and GB300 alike. nvml.h leaves room for an OEM to set the ceiling below the boost maximum, but no board we have captured does, so inventing a second key would only let a profile drift from the value it already declares.

Only the graphics domain answers: it is the sole child nvidia-smi emits under the element, and no capture shows what the other three would report.

func (*ConfigurableDevice) GetMaxMigDeviceCount 

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

GetMaxMigDeviceCount returns the board's MIG device ceiling. Real NVML reports this as a static capability regardless of whether MIG is on, and consumers use it as the upper bound when walking MIG device indices. Here it is not static: an override can move it, so the read is guarded.

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) GetMemClkMinMaxVfOffset added in v0.5.0 

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

GetMemClkMinMaxVfOffset returns the memory clock offset range.

func (*ConfigurableDevice) GetMemClkVfOffset added in v0.5.0 

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

GetMemClkVfOffset returns the memory clock offset.

func (*ConfigurableDevice) GetMemoryAffinity added in v0.3.0 

func (d *ConfigurableDevice) GetMemoryAffinity(nodeSetSize int, _ 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 ECC error counter for one (error type, counter type, memory location) triple. Every argument is honoured: DRAM and SRAM are backed by separate configuration, so a consumer reading them apart — as fault-handling software does when deciding whether a fault is repairable — sees distinct counts rather than one shared number. ecc_uncorrectable injection accrues 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 the MIG device at the given index.

ERROR_NOT_FOUND (rather than NOT_SUPPORTED) is what consumers treat as end-of-iteration: go-nvlib walks indices up to GetMaxMigDeviceCount and skips the ones that report NOT_FOUND, so a partly-populated board enumerates cleanly.

func (*ConfigurableDevice) GetMigMode 

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

GetMigMode returns the current and pending MIG modes.

ERROR_NOT_SUPPORTED on a board with no MIG tables is load-bearing: it is how go-nvlib's IsMigCapable — and so the device plugin — tells a MIG-capable GPU from a T4.

func (*ConfigurableDevice) GetMinMaxClockOfPState added in v0.5.0 

func (d *ConfigurableDevice) GetMinMaxClockOfPState(clockType nvml.ClockType, pstate nvml.Pstates) (uint32, uint32, nvml.Return)

GetMinMaxClockOfPState returns the clock envelope of the modelled P-state: the lowest and highest supported clock of the domain. Video has no table to derive an envelope from, so it answers NOT_SUPPORTED rather than a guess.

func (*ConfigurableDevice) GetMinMaxFanSpeed added in v0.5.0 

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

GetMinMaxFanSpeed reports the duty-cycle window a manual write may land in, backing nvmlDeviceGetMinMaxFanSpeed. It is board-wide rather than per-fan, so it takes no fan index, and SetFanSpeed_v2 refuses anything outside it.

func (*ConfigurableDevice) GetMinorNumber 

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

GetMinorNumber returns the device minor number

func (*ConfigurableDevice) GetMockC2cMode added in v0.4.0 

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

GetMockC2cMode reports whether this GPU has an NVLink-C2C link to the host CPU, backing nvmlDeviceGetC2cModeInfoV and the "GPU C2C Mode" row of `nvidia-smi -q`.

A disabled or undeclared link yields ERROR_NOT_SUPPORTED, which nvidia-smi renders as N/A — the correct reading on every non-Grace board. Returning SUCCESS with a false reading would render as "Disabled" instead, which no shipped profile wants: a100, h100, and b200 all set c2c_enabled: false explicitly and must stay N/A.

Named GetMockC2cMode to avoid shadowing the embedded dgxa100.Device's GetC2cModeInfoV method, following GetMockFabricInfo.

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) GetMockModuleID added in v0.4.0 

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

GetMockModuleID returns the GPU's module id within its node, backing nvmlDeviceGetModuleId. It answers from the same platform block as GetMockPlatformInfo so the two APIs cannot disagree about one GPU.

func (*ConfigurableDevice) GetMockNvLinkInfo added in v0.5.0 

func (d *ConfigurableDevice) GetMockNvLinkInfo() (NvLinkInfo, nvml.Return)

GetMockNvLinkInfo backs nvmlDeviceGetNvLinkInfo, which feeds the " NVLE:" row of `nvidia-smi nvlink --info` and the "Firmware Version:" rows beneath it. A profile that declares no firmware reports an empty table, which nvidia-smi renders as "N/A".

func (*ConfigurableDevice) GetMockNvlinkBwMode added in v0.5.0 

func (d *ConfigurableDevice) GetMockNvlinkBwMode() (uint8, bool, nvml.Return)

GetMockNvlinkBwMode backs nvmlDeviceGetNvlinkBwMode and `nvidia-smi nvlink -gBwMode`. isBest maps onto the struct's bIsBest field.

func (*ConfigurableDevice) GetMockNvlinkSupportedBwModes added in v0.5.0 

func (d *ConfigurableDevice) GetMockNvlinkSupportedBwModes() ([]uint8, nvml.Return)

GetMockNvlinkSupportedBwModes backs nvmlDeviceGetNvlinkSupportedBwModes and `nvidia-smi nvlink -sBwMode values`.

Named GetMock* to avoid shadowing the embedded mock Device's GetNvlinkSupportedBwModes, following GetMockC2cMode.

func (*ConfigurableDevice) GetMockPlatformInfo added in v0.4.0 

func (d *ConfigurableDevice) GetMockPlatformInfo() (PlatformInfo, nvml.Return)

GetMockPlatformInfo returns this GPU's platform identity, backing nvmlDeviceGetPlatformInfo and the "Platform Info" block of `nvidia-smi -q`.

A device with no platform block yields ERROR_NOT_SUPPORTED, which nvidia-smi renders as N/A — the correct reading on any board whose platform cannot report a physical location, i.e. everything outside a Grace-Blackwell rack. Only the NVL72 profiles declare one.

Named GetMockPlatformInfo to avoid shadowing the embedded dgxa100.Device's GetPlatformInfo method, following GetMockFabricInfo.

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) GetNumGpuCores added in v0.5.0 

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

GetNumGpuCores returns the profile's CUDA core count. nvml.h declines the query on a MIG-enabled GPU and on a MIG device, pointing the caller at the GPU instance profile instead, and the mock does the same.

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) GetOfaUtilization added in v0.4.0 

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

GetOfaUtilization returns optical-flow-accelerator utilization from utilization.ofa. See GetJpgUtilization for the NOT_SUPPORTED caveat.

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) GetPcieLinkMaxSpeed added in v0.5.0 

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

GetPcieLinkMaxSpeed returns the fastest generation the link supports, as an NVML_PCIE_LINK_MAX_SPEED_* code rather than in Mbps despite what nvml.h's prose says: the codes number the generations, so Gen5 reports 5.

func (*ConfigurableDevice) GetPcieReplayCounter 

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

GetPcieReplayCounter returns PCIe replay counter

func (*ConfigurableDevice) GetPcieSpeed added in v0.5.0 

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

GetPcieSpeed returns the current link's per-lane rate in Mbps: a Gen4 link reports 16000. A generation the profile does not configure, a negative one, or one past the last NVML can name is NOT_SUPPORTED rather than a speed of 0.

func (*ConfigurableDevice) GetPcieThroughput 

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

GetPcieThroughput returns PCIe throughput

func (*ConfigurableDevice) GetPdi added in v0.5.0 

func (d *ConfigurableDevice) GetPdi() (nvml.Pdi, nvml.Return)

GetPdi returns the Per Device Identifier, a 64-bit ID fused into the GPU. It is derived from the physical GPU's UUID so that every process loading the mock agrees on it; a MIG device carries its parent's UUID here and so reports the PDI of the GPU it is carved from.

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) GetPowerMizerMode_v1 added in v0.6.0 

func (d *ConfigurableDevice) GetPowerMizerMode_v1() (nvml.DevicePowerMizerModes_v1, nvml.Return)

GetPowerMizerMode_v1 reports the current PowerMizer mode and the modes the device accepts.

func (*ConfigurableDevice) GetPowerSource added in v0.6.0 

func (d *ConfigurableDevice) GetPowerSource() (nvml.PowerSource, nvml.Return)

GetPowerSource reports AC: every board Mokka models is a datacenter part on mains power, so neither battery nor an undersized supply is reachable.

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) GetRepairStatus added in v0.6.0 

func (d *ConfigurableDevice) GetRepairStatus() (nvml.RepairStatus, nvml.Return)

GetRepairStatus reports whether a memory repair is waiting for the next GPU reset. The mock models channel repair through the row remapper; no profile field describes TPC repair, so it is never pending.

func (*ConfigurableDevice) GetRetiredPages 

func (d *ConfigurableDevice) GetRetiredPages(_ 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(_ nvml.PageRetirementCause) ([]uint64, []uint64, nvml.Return)

GetRetiredPages_v2 returns retired pages with timestamps

func (*ConfigurableDevice) GetRowRemapperHistogram added in v0.4.0 

func (d *ConfigurableDevice) GetRowRemapperHistogram() (nvml.RowRemapperHistogramValues, nvml.Return)

GetRowRemapperHistogram returns how many memory banks fall into each row-remap availability bucket, i.e. how much spare capacity is left before the GPU can no longer repair a failing row. Row remapping is Ampere and later and the bank count is hardware-specific, so an unconfigured device reports the feature as unsupported rather than inventing a bank population.

func (*ConfigurableDevice) GetSamples added in v0.6.0 

func (d *ConfigurableDevice) GetSamples(samplingType nvml.SamplingType, lastSeen uint64) (nvml.ValueType, []nvml.Sample, nvml.Return)

GetSamples returns the samples of samplingType taken after lastSeen, oldest first, as the value type of the reading. The mock keeps no history, so every sample carries the current reading of the getter the type mirrors; under dynamic metrics that reading moves between calls, not within one.

func (*ConfigurableDevice) GetSerial 

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

GetSerial returns the device serial number

func (*ConfigurableDevice) GetSramEccErrorStatus added in v0.4.0 

func (d *ConfigurableDevice) GetSramEccErrorStatus() (nvml.EccSramErrorStatus, nvml.Return)

GetSramEccErrorStatus returns the on-die SRAM ECC error state from ecc.sram. SRAM errors are the fault class that row remapping cannot repair, so fault-handling software treats them differently from DRAM errors and reads them through this dedicated API.

The returned struct carries no Version: the caller's ABI is the bridge's concern, not the engine's.

func (*ConfigurableDevice) GetSramUniqueUncorrectedEccErrorCounts added in v0.6.0 

func (d *ConfigurableDevice) GetSramUniqueUncorrectedEccErrorCounts(counts *nvml.EccSramUniqueUncorrectedErrorCounts) nvml.Return

GetSramUniqueUncorrectedEccErrorCounts follows NVML's two-call protocol: a nil Entries asks for the size, and a buffer too small for the current errors gets INSUFFICIENT_SIZE with the size it needs, since errors can arrive between the two calls.

func (*ConfigurableDevice) GetSupportedClocksEventReasons added in v0.5.0 

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

GetSupportedClocksEventReasons is the newer name of GetSupportedClocksThrottleReasons, and answers the same mask so that the current-reasons getter is read against the same set under either name.

func (*ConfigurableDevice) GetSupportedClocksThrottleReasons 

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

GetSupportedClocksThrottleReasons returns bitmask of all supported throttle reasons.

func (*ConfigurableDevice) GetSupportedPerformanceStates added in v0.5.0 

func (d *ConfigurableDevice) GetSupportedPerformanceStates() ([]nvml.Pstates, nvml.Return)

GetSupportedPerformanceStates returns the one P-state the mock models.

func (*ConfigurableDevice) GetTargetFanSpeed added in v0.5.0 

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

GetTargetFanSpeed reports the duty cycle one fan is aiming for, backing nvmlDeviceGetTargetFanSpeed. Under manual control that is what was asked for; otherwise it is the profile's target_speed_percent, which every config in the repo declares and nothing read until this getter existed.

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 the aggregate or volatile ECC error total from ecc.errors, so a profile can present a GPU that has already accumulated errors. When failure injection has tripped into ecc_uncorrectable mode the running call counter is added to 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) GetUnrepairableMemoryFlag added in v0.6.0 

func (d *ConfigurableDevice) GetUnrepairableMemoryFlag() (nvml.UnrepairableMemoryStatus_v1, nvml.Return)

GetUnrepairableMemoryFlag reports whether the memory has a fault only a replacement fixes. The returned struct carries no version: the caller's ABI is the bridge's concern.

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 how long one performance policy has held the GPU below its requested clocks. It is the deprecated getter for the same state the throttle-counter field ids carry, so for the three policies NVML maps onto a clocks-event cause both paths resolve from one accrual and cannot disagree.

The board-limit, low-utilization, reliability and total-base-clocks limiters are not modelled, but they are real policies the header maps onto their own field ids, so they report zero rather than declining: zero is the answer for a limiter that has never fired, where NOT_SUPPORTED says the driver cannot tell — the same distinction that made these counters read N/A in the first place. Only NVML_PERF_POLICY_TOTAL_APP_CLOCKS declines, because the header marks it "DEPRECATED, Do not use" rather than giving it a field id.

Failure injection does not overload these fields with the configured Xid code — that is surfaced through the NVML event set — but a device tripped into a lost state still returns ERROR_GPU_IS_LOST like every guarded getter.

func (*ConfigurableDevice) GetVirtualizationMode added in v0.4.0 

func (d *ConfigurableDevice) GetVirtualizationMode() (nvml.GpuVirtualizationMode, nvml.Return)

GetVirtualizationMode reports whether the device is virtualized. Answering NOT_SUPPORTED here makes nvidia-smi print "N/A", which claims the driver cannot tell — real hardware always knows, and bare metal answers NONE.

func (*ConfigurableDevice) GpmMigSnapshotInto added in v0.6.0 

func (d *ConfigurableDevice) GpmMigSnapshotInto(gpuInstanceID int, key uint64) nvml.Return

GpmMigSnapshotInto snapshots one GPU instance of this physical GPU.

The mock spreads the board's load uniformly across its slices, so an instance is exactly as busy as the board and its activity metrics equal the board's, while its throughput is its slice share of the board's.

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. A MIG device samples its GPU instance, the same partition nvmlGpmMigSampleGet names by ID, so the two entry points agree.

func (*ConfigurableDevice) HostMaxPcieLinkGeneration added in v0.4.0 

func (d *ConfigurableDevice) HostMaxPcieLinkGeneration() int

HostMaxPcieLinkGeneration reports the maximum PCIe link generation the host side of the link supports, which nvidia-smi renders as the "Host Max" row.

This is deliberately not a Get* NVML method: no public NVML API exposes a host-side maximum, and nvidia-smi instead reads it through a slot of the internal export table (see the bridge's internal.go). The mock models a host that keeps up with the GPU, so the host maximum is the configured max_link_gen — keeping nvidia-smi's Max, Device Max and Host Max rows consistent, since the negotiable Max cannot exceed either endpoint.

Returns 0 when the profile configures no PCIe block, which the bridge treats as "unknown" and leaves the reading untouched.

func (*ConfigurableDevice) IsMigDeviceHandle added in v0.5.0 

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

IsMigDeviceHandle reports whether this handle refers to a MIG device.

func (*ConfigurableDevice) IsVgpuHost added in v0.6.0 

func (d *ConfigurableDevice) IsVgpuHost() bool

IsVgpuHost reports whether the GPU runs the vGPU manager. It agrees with the vGPU getters, so a GPU that claims the mode with no vGPU block, as a runtime override can leave it, is not one.

func (*ConfigurableDevice) MIGLayoutRecords added in v0.5.0 

func (d *ConfigurableDevice) MIGLayoutRecords() []MIGGPUInstanceRecord

MIGLayoutRecords reports the board's live partitioning in the form the override document records it, ordered by GPU instance ID so the document a caller writes from it is reproducible.

It is the baseline a runtime mutation needs: the recorded layout is edited by difference, and a board partitioned from declared counts has no layout to take a difference against until one is written down.

A board that cannot be partitioned — MIG off, or not a MIG board at all — has no layout rather than an empty one, and reports nil. An empty list is the distinct state "MIG on with every instance destroyed", and recording that for a board whose partitions are merely switched off would destroy the ones its profile declares.

Every instance comes back with a non-nil compute-instance list, empty included, because an absent list is what asks the create path for the spanning default: a layout written from a board whose instances carry none would otherwise come back with one apiece.

Profiles are recorded by ID rather than by name, because a name goes through a spelling more than one profile pair answers to and the layout would read back as a partition nobody created.

It is the ID the board publishes, not the enum the instance carries, because that is what every reader of profile_id resolves and what the create path records. The two numberings overlap, so recording the wrong one is not an error but a different layout: on an A100 a 1g instance carries enum 0, and 0 is the published ID of the profile that takes the whole board.

func (*ConfigurableDevice) MarkMIGDirty added in v0.5.0 

func (d *ConfigurableDevice) MarkMIGDirty()

MarkMIGDirty asks the next refresh to reconcile MIG state even though the override document has not changed.

It exists for the one way a board can drift from the document without the document moving: a mutation this process applied to the board but could not record. The file is authoritative, so the board has to be pulled back to it, and neither of the two signals a refresh normally acts on — a new generation or a config that differs from the one last applied — has anything to report.

The reconcile is deferred to the next refresh rather than run here because it destroys instances, and the caller is inside the NVML call that failed: a consumer's handles should not be invalidated from under it while it is still being told its own mutation was refused.

func (*ConfigurableDevice) OnSameBoard added in v0.5.0 

func (d *ConfigurableDevice) OnSameBoard(other nvml.Device) (int, nvml.Return)

OnSameBoard reports whether two devices share a physical board. Every mocked GPU is a board of its own, as GetMultiGpuBoard says, so only a GPU and its MIG devices share one; the board ID already encodes exactly that.

func (*ConfigurableDevice) PerformanceModes added in v0.5.0 

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

PerformanceModes renders the nvmlDeviceGetPerformanceModes string: one token set per P-state, in the token order and " ;" terminator of the nvml.h example. With a single modelled P-state there is one set, at perf level 0.

func (*ConfigurableDevice) PhysicalIndex added in v0.4.0 

func (d *ConfigurableDevice) PhysicalIndex() int

PhysicalIndex identifies the device in the shared override configuration. It must not change when a consumer sees only a subset of the devices.

func (*ConfigurableDevice) PowerSmoothingActivatePresetProfile added in v0.6.0 

func (d *ConfigurableDevice) PowerSmoothingActivatePresetProfile(profile *nvml.PowerSmoothingProfile) nvml.Return

PowerSmoothingActivatePresetProfile makes profile.ProfileId the active preset. NVML reads nothing else from the struct, and nvidia-smi leaves the rest uninitialised.

func (*ConfigurableDevice) PowerSmoothingSetState added in v0.6.0 

func (d *ConfigurableDevice) PowerSmoothingSetState(state *nvml.PowerSmoothingState) nvml.Return

PowerSmoothingSetState enables or disables power smoothing. Like every setter in the power family the state is recorded in the override document, so `nvidia-smi power-smoothing -s 1` followed by a separate `nvidia-smi -q` reports it.

func (*ConfigurableDevice) PowerSmoothingUpdatePresetProfileParam added in v0.6.0 

func (d *ConfigurableDevice) PowerSmoothingUpdatePresetProfileParam(profile *nvml.PowerSmoothingProfile) nvml.Return

PowerSmoothingUpdatePresetProfileParam sets one parameter of one preset. Ramp rates are taken in mW/s, the unit nvidia-smi passes through from -rur and -rdr and the one the profile fields report.

func (*ConfigurableDevice) ProcessByPID added in v0.4.0 

func (d *ConfigurableDevice) ProcessByPID(pid uint32) (ProcessConfig, bool)

ProcessByPID returns the configured process with that pid on this device, and whether one was found. nvml.ProcessInfo carries only pid and memory, so callers that need any other configured field alongside a running-process list look it up here rather than searching every device (two GPUs may host the same pid). The whole entry is returned because the views differ in what they read: the name for nvidia-smi's process lists, and the utilization fields for per-process monitoring.

func (*ConfigurableDevice) ReadPRMCounters_v1 added in v0.5.0 

func (d *ConfigurableDevice) ReadPRMCounters_v1([]nvml.PRMCounterId, int) ([]nvml.PRMCounter_v1, nvml.Return)

ReadPRMCounters_v1 declines. PRM registers expose the physical layer of the GPU's NVLink ports (PPCNT and its siblings), which the mock has no model of.

func (*ConfigurableDevice) ReadWritePRM_v1 added in v0.5.0 

func (d *ConfigurableDevice) ReadWritePRM_v1(*nvml.PRMTLV_v1) nvml.Return

ReadWritePRM_v1 declines for the reason ReadPRMCounters_v1 does.

func (*ConfigurableDevice) ResetApplicationsClocks added in v0.5.0 

func (d *ConfigurableDevice) ResetApplicationsClocks() nvml.Return

ResetApplicationsClocks applies `nvidia-smi -rac`: the applications clocks return to the board defaults. The defaults are written rather than the override cleared, because a profile may model a node whose clocks were already set away from them.

func (*ConfigurableDevice) ResetGpuLockedClocks added in v0.5.0 

func (d *ConfigurableDevice) ResetGpuLockedClocks() nvml.Return

ResetGpuLockedClocks applies `nvidia-smi -rgc`.

func (*ConfigurableDevice) ResetMemoryLockedClocks added in v0.5.0 

func (d *ConfigurableDevice) ResetMemoryLockedClocks() nvml.Return

ResetMemoryLockedClocks applies `nvidia-smi -rmc`.

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, _ int) nvml.Return

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

func (*ConfigurableDevice) RunningProcessesByMode added in v0.6.0 

func (d *ConfigurableDevice) RunningProcessesByMode(mode nvml.ProcessMode) ([]nvml.ProcessInfo, nvml.Return)

RunningProcessesByMode returns the processes nvmlDeviceGetRunningProcessDetailList reports for mode: the list the matching per-type getter returns, or all three for PROCESS_MODE_ALL.

func (*ConfigurableDevice) SetAccountingMode added in v0.6.0 

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

SetAccountingMode turns accounting on or off. Turning it off also drops the terminated records, because disabling clears all accounting information. Re-enabling accounts the processes still running again; the driver would only track processes started after that, which the mock has no way to tell.

func (*ConfigurableDevice) SetApplicationsClocks added in v0.5.0 

func (d *ConfigurableDevice) SetApplicationsClocks(memMHz, graphicsMHz uint32) nvml.Return

SetApplicationsClocks applies `nvidia-smi -ac <mem>,<graphics>`. The pair must be one the supported-clock table lists; a board that reports no applications clocks declines the setter as it declines the getter.

func (*ConfigurableDevice) SetAutoBoostedClocksEnabled added in v0.5.0 

func (d *ConfigurableDevice) SetAutoBoostedClocksEnabled(nvml.EnableState) nvml.Return

SetAutoBoostedClocksEnabled declines, as the getter does. nvml.h moves auto boost under the applications clocks from Pascal on, every board the mock models is newer, and every capture reports auto boost as N/A.

func (*ConfigurableDevice) SetClockOffsets added in v0.5.0 

func (d *ConfigurableDevice) SetClockOffsets(info nvml.ClockOffset) nvml.Return

SetClockOffsets records the offset info asks for, within the declared range.

func (*ConfigurableDevice) SetDefaultAutoBoostedClocksEnabled added in v0.5.0 

func (d *ConfigurableDevice) SetDefaultAutoBoostedClocksEnabled(nvml.EnableState, uint32) nvml.Return

SetDefaultAutoBoostedClocksEnabled declines for the same reason.

func (*ConfigurableDevice) SetDefaultFanSpeed_v2 added in v0.5.0 

func (d *ConfigurableDevice) SetDefaultFanSpeed_v2(fan int) nvml.Return

SetDefaultFanSpeed_v2 returns one fan to the driver's temperature curve, backing nvmlDeviceSetDefaultFanSpeed_v2. The recorded duty cycle goes with the policy: a fan no longer being held anywhere must report the board's own reading, not the last value something asked for.

func (*ConfigurableDevice) SetDramEncryptionMode added in v0.6.0 

func (d *ConfigurableDevice) SetDramEncryptionMode(info *nvml.DramEncryptionInfo) nvml.Return

SetDramEncryptionMode records the mode the next reboot applies. The current mode stays what it is.

func (*ConfigurableDevice) SetEccMode added in v0.6.0 

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

SetEccMode records the ECC mode the next GPU reset applies. The current mode stays what it is, as on hardware.

func (*ConfigurableDevice) SetFanControlPolicy added in v0.5.0 

func (d *ConfigurableDevice) SetFanControlPolicy(fan int, policy nvml.FanControlPolicy) nvml.Return

SetFanControlPolicy switches one fan between the driver's curve and manual control, backing nvmlDeviceSetFanControlPolicy. Switching to manual does not invent a duty cycle — the fan keeps running at what it was doing until one is asked for — and switching back to the curve drops any that was.

func (*ConfigurableDevice) SetFanSpeed_v2 added in v0.5.0 

func (d *ConfigurableDevice) SetFanSpeed_v2(fan, speed int) nvml.Return

SetFanSpeed_v2 holds one fan at a duty cycle, backing nvmlDeviceSetFanSpeed_v2. It implies manual control, because a fan the driver is still steering by temperature would not stay where it was put.

The write is refused outside the window GetMinMaxFanSpeed advertises: a board that accepts a duty cycle it just said it could not reach is lying in one of the two places.

func (*ConfigurableDevice) SetGpcClkVfOffset added in v0.5.0 

func (d *ConfigurableDevice) SetGpcClkVfOffset(offset int) nvml.Return

SetGpcClkVfOffset applies a graphics clock offset.

func (*ConfigurableDevice) SetGpuLockedClocks added in v0.5.0 

func (d *ConfigurableDevice) SetGpuLockedClocks(minMHz, maxMHz uint32) nvml.Return

SetGpuLockedClocks applies `nvidia-smi -lgc <min>,<max>`. The current graphics and SM clocks then read inside the range.

func (*ConfigurableDevice) SetHostname added in v0.6.0 

func (d *ConfigurableDevice) SetHostname(name string) nvml.Return

SetHostname records a hostname for the device.

The value is process-local. NVML itself says the hostname does not survive a GPU reset or driver reload, but on real hardware it is driver state that every process on the node reads back; here only the process that set it sees the new value, the same limitation SetPersistenceMode carries (#849).

func (*ConfigurableDevice) SetMemClkVfOffset added in v0.5.0 

func (d *ConfigurableDevice) SetMemClkVfOffset(offset int) nvml.Return

SetMemClkVfOffset applies a memory clock offset.

func (*ConfigurableDevice) SetMemoryLockedClocks added in v0.5.0 

func (d *ConfigurableDevice) SetMemoryLockedClocks(minMHz, maxMHz uint32) nvml.Return

SetMemoryLockedClocks applies `nvidia-smi -lmc <min>,<max>`. The current memory clock then reads inside the range.

func (*ConfigurableDevice) SetMigMode added in v0.5.0 

func (d *ConfigurableDevice) SetMigMode(mode int) (nvml.Return, nvml.Return)

SetMigMode changes MIG mode. The second return is the activation status, which real NVML uses to report that the mode change needs a GPU reset; the mock applies it immediately and reports success.

Disabling MIG tears down the partitioning, as it does on hardware.

func (*ConfigurableDevice) SetMockNvLinkLowPowerThreshold added in v0.5.0 

func (d *ConfigurableDevice) SetMockNvLinkLowPowerThreshold(threshold uint32) nvml.Return

SetMockNvLinkLowPowerThreshold backs nvmlDeviceSetNvLinkDeviceLowPowerThreshold and `nvidia-smi nvlink -sLowPwrThres`. An accepted value is read back through NVML_FI_DEV_NVLINK_GET_POWER_THRESHOLD.

The range is the one the mock already advertises through the _THRESHOLD_MIN / _MAX field values, not the header's deprecated 0x1FFF ceiling; nvidia-smi reads that advertised range and pre-validates against it, so the two must agree.

func (*ConfigurableDevice) SetMockNvlinkBwMode added in v0.5.0 

func (d *ConfigurableDevice) SetMockNvlinkBwMode(mode uint8, setBest bool) nvml.Return

SetMockNvlinkBwMode backs nvmlDeviceSetNvlinkBwMode and `nvidia-smi nvlink -sBwMode`. setBest maps onto the struct's bSetBest field, which selects the best mode and makes the mode argument irrelevant.

The mode is recorded in the override document rather than in process memory, because on real hardware it is driver state the whole node observes: setting it with one `nvidia-smi` and reading it back with another has to report the new value.

func (*ConfigurableDevice) SetPersistenceMode 

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

SetPersistenceMode records the mode in the override document, so a separate process sees it: `nvidia-smi -pm 0` is how an operator clears the way for a drain, which runs as its own invocation and refuses a persistent GPU.

func (*ConfigurableDevice) SetPowerManagementLimit added in v0.5.0 

func (d *ConfigurableDevice) SetPowerManagementLimit(limitMW uint32) nvml.Return

SetPowerManagementLimit applies a new power cap, in milliwatts.

The cap is recorded in the override document rather than written back to the profile, so it outranks the profile's enforced_limit_mw the way a cap applied at runtime outranks the board default, and is cleared by a reset. It has to go somewhere every process can see, because on real hardware the cap is driver state and `nvidia-smi -pl` followed by a separate `nvidia-smi` reports the new value.

func (*ConfigurableDevice) SetPowerManagementLimit_v2 added in v0.5.0 

func (d *ConfigurableDevice) SetPowerManagementLimit_v2(powerValue *nvml.PowerValue_v2) nvml.Return

SetPowerManagementLimit_v2 is the versioned form of the cap setter. Only the GPU-wide budget is modelled, so the other scopes decline rather than fold into the GPU limit: reporting success for a module or memory cap that was never applied is the failure mode this guards against.

func (*ConfigurableDevice) SetPowerMizerMode_v1 added in v0.6.0 

func (d *ConfigurableDevice) SetPowerMizerMode_v1(modes *nvml.DevicePowerMizerModes_v1) nvml.Return

SetPowerMizerMode_v1 applies modes.Mode. Like the power limit it is recorded in the override document, so a separate process reads the new mode back.

func (*ConfigurableDevice) SupportedGraphicsClocks added in v0.5.0 

func (d *ConfigurableDevice) SupportedGraphicsClocks(memMHz uint32) ([]uint32, nvml.Return)

SupportedGraphicsClocks returns the graphics clocks the device supports at one memory clock. A memory clock the table does not list is NOT_FOUND, which is how nvml.h tells a caller the frequency itself is the problem.

func (*ConfigurableDevice) SupportedMemoryClocks added in v0.5.0 

func (d *ConfigurableDevice) SupportedMemoryClocks() ([]uint32, nvml.Return)

SupportedMemoryClocks returns the memory clocks the device supports, in the order the profile lists them — highest first, as NVML returns them.

func (*ConfigurableDevice) ValidateInforom added in v0.6.0 

func (d *ConfigurableDevice) ValidateInforom() nvml.Return

ValidateInforom reports the InfoROM as intact whenever the profile has one. Content beyond that is not modelled, so corruption cannot be injected here.

func (*ConfigurableDevice) VgpuActiveInstanceIDs added in v0.6.0 

func (d *ConfigurableDevice) VgpuActiveInstanceIDs() ([]uint32, nvml.Return)

VgpuActiveInstanceIDs lists the running instances.

func (*ConfigurableDevice) VgpuCreatableTypeIDs added in v0.6.0 

func (d *ConfigurableDevice) VgpuCreatableTypeIDs() ([]uint32, nvml.Return)

VgpuCreatableTypeIDs lists what could still be created. Without heterogeneous mode a GPU runs one type at a time, so once an instance is running only its type is creatable, and only until the GPU is full.

func (*ConfigurableDevice) VgpuGuestLicenseState added in v0.6.0 

func (d *ConfigurableDevice) VgpuGuestLicenseState() (uint32, bool)

VgpuGuestLicenseState reports the guest's license state in nvmlGridLicenseState_t terms, and false for a GPU that is not a vGPU guest.

func (*ConfigurableDevice) VgpuSupportedTypeIDs added in v0.6.0 

func (d *ConfigurableDevice) VgpuSupportedTypeIDs() ([]uint32, nvml.Return)

VgpuSupportedTypeIDs lists the declared types in declaration order.

func (*ConfigurableDevice) VgpuType added in v0.6.0 

func (d *ConfigurableDevice) VgpuType(id uint32) (VgpuType, nvml.Return)

VgpuType resolves a type this GPU declares.

func (*ConfigurableDevice) WorkloadPowerProfileGetCurrentProfiles added in v0.5.0 

func (d *ConfigurableDevice) WorkloadPowerProfileGetCurrentProfiles() (nvml.WorkloadPowerProfileCurrentProfiles, nvml.Return)

WorkloadPowerProfileGetCurrentProfiles reports the supported, requested and enforced masks. Requested and enforced differ because asking for mutually exclusive profiles is allowed; enforced is what survives arbitration.

func (*ConfigurableDevice) WorkloadPowerProfileGetProfilesInfo added in v0.5.0 

func (d *ConfigurableDevice) WorkloadPowerProfileGetProfilesInfo() (nvml.WorkloadPowerProfileProfilesInfo, nvml.Return)

WorkloadPowerProfileGetProfilesInfo reports the profiles the device advertises. perfProfile is indexed by profile id, not densely packed: nvidia-smi takes each profile's name from the set bits of perfProfilesMask but reads its priority and conflicts from perfProfile[id]. Packing the entries instead renders every profile above the first gap with another profile's priority — verified against nvidia-smi 580.65.06 with a deliberately non-contiguous set.

func (*ConfigurableDevice) WorkloadPowerProfileUpdateProfiles added in v0.5.0 

func (d *ConfigurableDevice) WorkloadPowerProfileUpdateProfiles(
	op nvml.PowerProfileOperation, mask nvml.Mask255,
) nvml.Return

WorkloadPowerProfileUpdateProfiles applies op to the requested profile set, backing `nvidia-smi power-profiles -sr` and `-cr`. The result is recorded in the override document rather than written back to the profile, so it outranks the configured request from the first write onwards and is cleared by a reset — and, unlike process memory, a consumer in another process reads back what was written.

The whole mask is validated before any of it is applied: a caller naming one unsupported profile alongside several valid ones gets a clean refusal rather than a partial update it cannot tell apart from success.

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"`

	// Hostname seeds nvmlDeviceGetHostname_v1 before anything calls the setter.
	// Blackwell and newer only, matching NVML's support statement.
	Hostname string `json:"hostname,omitempty"`

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

	// 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"`

	// AddressingMode is how the GPU reaches system-allocated memory: "hmm",
	// "ats" or "none". It is a property of the host as much as the board —
	// HMM needs kernel support, ATS a Grace CPU — so the same GPU on the same
	// driver can report either, and the profile has to say which host it models.
	AddressingMode string `json:"addressing_mode,omitempty"`

	// Draining is the drain state nvmlDeviceModifyDrainState sets. A draining
	// GPU drops out of enumeration for every process that initialises NVML
	// afterwards, but stays addressable by PCI location so it can be undrained.
	Draining bool `json:"draining,omitempty"`

	// Removed is set by nvmlDeviceRemoveGpu and cleared by
	// nvmlDeviceDiscoverGpus. A removed GPU is gone from the driver: no process
	// enumerates it and the drain calls no longer resolve it.
	Removed bool `json:"removed,omitempty"`

	// Excluded models a GPU the kernel module was told to skip
	// (NVreg_ExcludedGpus). It is never enumerated, the driver does not manage
	// it, and nvmlGetExcludedDeviceInfoByIndex lists it.
	Excluded bool `json:"excluded,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"`

	// Host CPU the board is paired with
	CPU *CPUConfig `json:"cpu,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"`

	// NVLinkBwMode records the NVLink Reduced Bandwidth Mode a runtime setter
	// applied. It is per device because that is what the device-level NVML
	// pair takes; the node-wide pair writes the same field into the `all:`
	// bucket, so a node-wide set moves every device the way the driver does.
	//
	// A pointer so an explicit 0 (FULL) is distinguishable from "never set",
	// which falls back to the profile's nvlink.bw_mode.
	NVLinkBwMode *uint8 `json:"nvlink_bw_mode,omitempty"`

	// NVLinkLowPowerThreshold records the threshold
	// nvmlDeviceSetNvLinkDeviceLowPowerThreshold applied, in the 50us units
	// the low-power field values report. Nil is the driver default, which is
	// also what the reset sentinel restores.
	NVLinkLowPowerThreshold *uint32 `json:"nvlink_low_power_threshold,omitempty"`

	// Platform describes where the board physically sits in a rack. When nil
	// (default) nvmlDeviceGetPlatformInfo and nvmlDeviceGetModuleId report
	// ERROR_NOT_SUPPORTED — matching every board outside a Grace-Blackwell
	// rack, whose platform cannot report a location.
	Platform *PlatformConfig `json:"platform,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 is the /dev/nvidia<N> the driver would have created. A
	// pointer because minor 0 is a legal value on a device that is not index
	// 0, so an omitted key has to stay distinguishable from an explicit zero.
	MinorNumber  *int             `json:"minor_number,omitempty"`
	GraceCPUPair int              `json:"grace_cpu_pair,omitzero"`
	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,omitzero"`

	// 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,omitzero"`
}

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,omitzero"`
	RampC         int `json:"ramp_c,omitzero"`
	RampPeriodSec int `json:"ramp_period_sec,omitzero"`
}

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,omitzero"`
	GPUMax         uint32 `json:"gpu_max,omitzero"`
	MemoryMin      uint32 `json:"memory_min,omitzero"`
	MemoryMax      uint32 `json:"memory_max,omitzero"`
	BurstPeriodSec int    `json:"burst_period_sec,omitzero"`
}

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"`
	SRAM        *ECCSramConfig   `json:"sram,omitempty"`
	// DRAMEncryption is the DRAM encryption state of a Blackwell or newer
	// board. Earlier architectures answer NOT_SUPPORTED whatever it holds.
	DRAMEncryption *ECCDRAMEncryptionConfig `json:"dram_encryption,omitempty"`
}

ECCConfig defines ECC memory configuration

type ECCDRAMEncryptionConfig added in v0.6.0 

type ECCDRAMEncryptionConfig struct {
	ModeCurrent string `json:"mode_current,omitempty"`
	ModePending string `json:"mode_pending,omitempty"`
}

ECCDRAMEncryptionConfig defines the DRAM encryption mode. Changing it takes a reboot, so the pending mode is the target the next boot applies while the current mode is what the GPU runs with now.

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,omitzero"`
	L1Cache       uint64 `json:"l1_cache,omitzero"`
	L2Cache       uint64 `json:"l2_cache,omitzero"`
	RegisterFile  uint64 `json:"register_file,omitzero"`
	TextureMemory uint64 `json:"texture_memory,omitzero"`
	Total         uint64 `json:"total,omitzero"`
}

ECCMemoryErrorsConfig defines per-memory-location error counts

type ECCSramConfig added in v0.4.0 

type ECCSramConfig struct {
	Volatile  *ECCSramCountsConfig `json:"volatile,omitempty"`
	Aggregate *ECCSramCountsConfig `json:"aggregate,omitempty"`
	// UncorrectableSources attributes the aggregate uncorrectable errors to the
	// unit that reported them; nvidia-smi renders it as "Aggregate
	// Uncorrectable SRAM Sources".
	UncorrectableSources *ECCSramSourcesConfig `json:"uncorrectable_sources,omitempty"`
	// ThresholdExceeded reports whether the accumulated SRAM errors have passed
	// the driver's threshold — the signal that the GPU needs servicing rather
	// than just a count that went up.
	ThresholdExceeded bool `json:"threshold_exceeded,omitzero"`
}

ECCSramConfig defines the on-die SRAM ECC error state. Hardware counts SRAM errors separately from the DRAM counters in Errors and reports them through their own API (nvmlDeviceGetSramEccErrorStatus), which is why they are a sibling block rather than another memory location under errors.

type ECCSramCountsConfig added in v0.4.0 

type ECCSramCountsConfig struct {
	Correctable         uint64 `json:"correctable,omitzero"`
	UncorrectableParity uint64 `json:"uncorrectable_parity,omitzero"`
	UncorrectableSECDED uint64 `json:"uncorrectable_secded,omitzero"`
}

ECCSramCountsConfig defines the SRAM error counts for one scope (volatile, reset at driver reload, or aggregate, persisted in the InfoROM).

type ECCSramSourcesConfig added in v0.4.0 

type ECCSramSourcesConfig struct {
	L2              uint64 `json:"l2,omitzero"`
	SM              uint64 `json:"sm,omitzero"`
	Microcontroller uint64 `json:"microcontroller,omitzero"`
	PCIe            uint64 `json:"pcie,omitzero"`
	Other           uint64 `json:"other,omitzero"`
}

ECCSramSourcesConfig defines the per-unit breakdown of aggregate uncorrectable SRAM errors.

type EccCounterScope added in v0.6.0 

type EccCounterScope string

EccCounterScope names the ECC counter set a clear applies to: the key it is stored under in ecc.errors and ecc.sram. 

const (
	// EccScopeVolatile counts since the last driver reload.
	EccScopeVolatile EccCounterScope = "volatile"
	// EccScopeAggregate counts for the life of the board, as persisted in the
	// InfoROM.
	EccScopeAggregate EccCounterScope = "aggregate"
)

type EncoderStatsConfig 

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

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) AnyDeviceLost added in v0.4.0 

func (e *Engine) AnyDeviceLost() bool

AnyDeviceLost reports whether any visible device is lost / fallen_off_bus. nvmlEventSetWait consults it so a wait on a set that (in real NVML) contains a lost GPU fails with ERROR_GPU_IS_LOST like every other call against that device. Does not advance any failure injector (no Tick).

It uses failureLostByConfig, so a device the config already declares immediately lost surfaces through the wait even for a client that only loops on nvmlEventSetWait and never calls a guarded getter (the DRA driver's health monitor) — matching real NVML, where a GPU that falls off the bus fails the wait whether or not the client has since called a getter. A device gated by after_calls / probability still stays healthy until it actually trips, so those semantics are unchanged.

The mock does not record event-set membership (nvmlDeviceRegisterEvents is a success stub), so any visible lost device fails every wait.

func (*Engine) ComputeInstanceDestroy added in v0.5.0 

func (e *Engine) ComputeInstanceDestroy(handle unsafe.Pointer) nvml.Return

ComputeInstanceDestroy tears down a compute instance, invalidating its handle and the MIG device it backed.

func (*Engine) ComputeInstanceGetInfo added in v0.5.0 

func (e *Engine) ComputeInstanceGetInfo(
	handle unsafe.Pointer,
) (nvml.ComputeInstanceInfo, unsafe.Pointer, unsafe.Pointer, nvml.Return)

ComputeInstanceGetInfo returns a compute instance's info together with handles for the parent device and GPU instance the C struct carries.

func (*Engine) DeviceCreateGpuInstance added in v0.5.0 

func (e *Engine) DeviceCreateGpuInstance(
	handle unsafe.Pointer, profile int, placement *nvml.GpuInstancePlacement,
) (unsafe.Pointer, nvml.Return)

DeviceCreateGpuInstance partitions the GPU and returns a handle to the new instance. placement is optional: nil lets the mock pick the first offset that still fits, which is what nvmlDeviceCreateGpuInstance does.

func (*Engine) DeviceGetCount 

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

DeviceGetCount returns the number of compute devices.

func (*Engine) DeviceGetDeviceHandleFromMigDeviceHandle added in v0.5.0 

func (e *Engine) DeviceGetDeviceHandleFromMigDeviceHandle(handle unsafe.Pointer) (unsafe.Pointer, nvml.Return)

DeviceGetDeviceHandleFromMigDeviceHandle returns a handle for the physical GPU behind a MIG device.

func (*Engine) DeviceGetGpuInstanceById added in v0.5.0 

func (e *Engine) DeviceGetGpuInstanceById(handle unsafe.Pointer, id int) (unsafe.Pointer, nvml.Return)

DeviceGetGpuInstanceById returns a handle for the instance with the given ID.

func (*Engine) DeviceGetGpuInstancePossiblePlacements added in v0.5.0 

func (e *Engine) DeviceGetGpuInstancePossiblePlacements(
	handle unsafe.Pointer, profile int,
) ([]nvml.GpuInstancePlacement, nvml.Return)

DeviceGetGpuInstancePossiblePlacements returns the slice offsets a profile may occupy on this board.

func (*Engine) DeviceGetGpuInstanceProfileInfo added in v0.5.0 

func (e *Engine) DeviceGetGpuInstanceProfileInfo(
	handle unsafe.Pointer, profile int,
) (nvml.GpuInstanceProfileInfo, nvml.Return)

DeviceGetGpuInstanceProfileInfo returns a GPU instance profile the board supports, for the plain (unversioned) NVML entry point.

func (*Engine) DeviceGetGpuInstanceProfileName added in v0.5.0 

func (e *Engine) DeviceGetGpuInstanceProfileName(handle unsafe.Pointer, profile int) (string, nvml.Return)

DeviceGetGpuInstanceProfileName returns the name real NVML reports for a GPU instance profile, e.g. "MIG 1g.5gb" — the spelling nvidia-smi prints and the one the versioned profile-info structs carry.

func (*Engine) DeviceGetGpuInstanceRemainingCapacity added in v0.5.0 

func (e *Engine) DeviceGetGpuInstanceRemainingCapacity(handle unsafe.Pointer, profile int) (int, nvml.Return)

DeviceGetGpuInstanceRemainingCapacity reports how many more instances of a profile still fit.

func (*Engine) DeviceGetGpuInstances added in v0.5.0 

func (e *Engine) DeviceGetGpuInstances(handle unsafe.Pointer, profile int) ([]unsafe.Pointer, nvml.Return)

DeviceGetGpuInstances returns handles for the live instances of a profile.

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) DeviceGetHandleBySerial added in v0.5.0 

func (e *Engine) DeviceGetHandleBySerial(serial string) (unsafe.Pointer, nvml.Return)

DeviceGetHandleBySerial returns a handle for the device with the given board serial. MIG devices are not searched: they report their parent's serial, so a serial can never name one unambiguously.

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) DeviceGetHandleByUUIDBinary added in v0.5.0 

func (e *Engine) DeviceGetHandleByUUIDBinary(raw [16]byte) (unsafe.Pointer, nvml.Return)

DeviceGetHandleByUUIDBinary returns a handle for the GPU or MIG device whose UUID is the 16 bytes of a binary nvmlUUID_t. Those bytes drop the GPU-/MIG- prefix, so unlike the ASCII lookup they can name either kind of device.

A MIG UUID is derived from its parent's (migDeviceUUID), so a partition can share all 16 bytes with the GPU it is carved from. Such bytes name two devices, and answering with either would hand some caller the wrong one, so the lookup is refused; the ASCII form still tells them apart by prefix.

func (*Engine) DeviceGetMigDeviceHandleByIndex added in v0.5.0 

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

DeviceGetMigDeviceHandleByIndex returns a device handle for the MIG device at the given index on a partitioned GPU.

func (*Engine) DeviceGpuInstanceProfileEnum added in v0.5.0 

func (e *Engine) DeviceGpuInstanceProfileEnum(handle unsafe.Pointer, reportedID int) (int, nvml.Return)

DeviceGpuInstanceProfileEnum resolves an ID the caller supplied to the profile enum. It fails for an ID the board publishes no profile under, which is what refuses `nvidia-smi mig -cgi 3` on an A100 rather than quietly creating the profile whose enum happens to be 3.

func (*Engine) DeviceGpuInstanceReportedProfileID added in v0.5.0 

func (e *Engine) DeviceGpuInstanceReportedProfileID(handle unsafe.Pointer, profileEnum int) (int, nvml.Return)

DeviceGpuInstanceReportedProfileID is DeviceGpuInstanceProfileEnum in reverse, for the profile IDs the bridge writes back out to C.

func (*Engine) DiscoverGpus added in v0.5.0 

func (e *Engine) DiscoverGpus(pci *nvml.PciInfo) nvml.Return

DiscoverGpus brings back removed GPUs under pci: every removed GPU when its domain, bus and device are all zero, otherwise the one at that address. Unlike the calls that act on one GPU, it ignores the busId string: NVML documents that only the numeric fields are read, so a real driver handed a zeroed address with busId filled rescans the whole tree.

func (*Engine) ExcludedDevices added in v0.5.0 

func (e *Engine) ExcludedDevices() ([]nvml.ExcludedDeviceInfo, nvml.Return)

ExcludedDevices lists the GPUs the kernel module was told to skip, in physical order.

func (*Engine) GetConfig 

func (e *Engine) GetConfig() *Config

GetConfig returns the engine configuration (for testing)

func (*Engine) GpuInstanceCreateComputeInstance added in v0.5.0 

func (e *Engine) GpuInstanceCreateComputeInstance(
	handle unsafe.Pointer, profile int, placement *nvml.ComputeInstancePlacement,
) (unsafe.Pointer, nvml.Return)

GpuInstanceCreateComputeInstance partitions a GPU instance further. placement is optional, mirroring the two NVML entry points.

func (*Engine) GpuInstanceDestroy added in v0.5.0 

func (e *Engine) GpuInstanceDestroy(handle unsafe.Pointer) nvml.Return

GpuInstanceDestroy tears down a GPU instance, invalidating its handle and the handles of everything derived from it.

An occupied instance is refused rather than cascaded. NVML reports NVML_ERROR_IN_USE here, so every partitioning tool destroys compute instances first; a mock that tore them down for the caller would let a tool with that order wrong pass against the mock and fail on hardware. The internal paths that legitimately cascade — disabling MIG, applying a declared layout — tear the tree down directly and do not come through this NVML entry point.

func (*Engine) GpuInstanceGetComputeInstanceById added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstanceById(handle unsafe.Pointer, id int) (unsafe.Pointer, nvml.Return)

GpuInstanceGetComputeInstanceById returns a handle for the compute instance with the given ID.

func (*Engine) GpuInstanceGetComputeInstancePossiblePlacements added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstancePossiblePlacements(
	handle unsafe.Pointer, profile int,
) ([]nvml.ComputeInstancePlacement, nvml.Return)

GpuInstanceGetComputeInstancePossiblePlacements returns the compute-slice offsets a profile may occupy within a GPU instance.

func (*Engine) GpuInstanceGetComputeInstanceProfileInfo added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstanceProfileInfo(
	handle unsafe.Pointer, profile, engProfile int,
) (nvml.ComputeInstanceProfileInfo, nvml.Return)

GpuInstanceGetComputeInstanceProfileInfo returns a compute instance profile available within a GPU instance.

func (*Engine) GpuInstanceGetComputeInstanceProfileName added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstanceProfileName(
	handle unsafe.Pointer, profile int,
) (string, nvml.Return)

GpuInstanceGetComputeInstanceProfileName returns the name real NVML reports for a compute instance profile within a GPU instance, e.g. "MIG 1c.3g.20gb".

func (*Engine) GpuInstanceGetComputeInstanceRemainingCapacity added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstanceRemainingCapacity(
	handle unsafe.Pointer, profile int,
) (int, nvml.Return)

GpuInstanceGetComputeInstanceRemainingCapacity reports how many more compute instances of a profile still fit in a GPU instance.

func (*Engine) GpuInstanceGetComputeInstances added in v0.5.0 

func (e *Engine) GpuInstanceGetComputeInstances(
	handle unsafe.Pointer, profile int,
) ([]unsafe.Pointer, nvml.Return)

GpuInstanceGetComputeInstances returns handles for the live compute instances of a profile.

func (*Engine) GpuInstanceGetInfo added in v0.5.0 

func (e *Engine) GpuInstanceGetInfo(handle unsafe.Pointer) (nvml.GpuInstanceInfo, unsafe.Pointer, nvml.Return)

GpuInstanceGetInfo returns a GPU instance's info together with a handle for its parent device, which the C struct carries as a field.

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) ModifyDrainState added in v0.5.0 

func (e *Engine) ModifyDrainState(pci *nvml.PciInfo, state nvml.EnableState) nvml.Return

ModifyDrainState enters or leaves the draining state.

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 visible 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) ProcessByPID added in v0.4.0 

func (e *Engine) ProcessByPID(pid uint32) (ProcessConfig, bool)

ProcessByPID returns the first configured process with that pid, searching every device's process list, and whether one was found. This backs nvmlSystemGetProcessName, whose signature carries a bare pid with no device, so GPU visibility intentionally does not restrict this system-wide lookup. Callers that already know the device should use ConfigurableDevice.ProcessByPID instead.

func (*Engine) QueryDrainState added in v0.5.0 

func (e *Engine) QueryDrainState(pci *nvml.PciInfo) (nvml.EnableState, nvml.Return)

QueryDrainState reports whether the GPU at pci is draining.

func (*Engine) RemoveGpu added in v0.5.0 

func (e *Engine) RemoveGpu(pci *nvml.PciInfo, gpuState nvml.DetachGpuState, linkState nvml.PcieLinkState) nvml.Return

RemoveGpu detaches the GPU at pci from the driver. Every process that enumerates GPUs afterwards — this one included — sees one fewer, with the GPUs after it renumbered. gpuState and linkState describe what happens to the PCI device and its upstream link, which the mock does not model beyond validating them.

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) SystemEventSetCreate added in v0.6.0 

func (e *Engine) SystemEventSetCreate(token unsafe.Pointer) nvml.Return

SystemEventSetCreate registers a system event set keyed by the opaque token the bridge allocated for it.

func (*Engine) SystemEventSetFree added in v0.6.0 

func (e *Engine) SystemEventSetFree(token unsafe.Pointer) nvml.Return

SystemEventSetFree drops a set. An unknown token is ERROR_INVALID_ARGUMENT rather than SUCCESS so a double free surfaces to the caller instead of silently passing.

func (*Engine) SystemEventSetPoll added in v0.6.0 

func (e *Engine) SystemEventSetPoll(token unsafe.Pointer, limit int) ([]SystemEvent, nvml.Return)

SystemEventSetPoll samples the current driver-bound state of every visible device and returns up to limit events queued for the set. It is the non-blocking core of nvmlSystemEventSetWait; the bridge owns the blocking.

func (*Engine) SystemGetCPER added in v0.6.0 

func (e *Engine) SystemGetCPER(q CPERQuery, bufferSize uint32, sizeQuery bool) (CPERResult, nvml.Return)

SystemGetCPER answers nvmlSystemGetCPER_v1. sizeQuery selects the buffer==NULL && bufferSize==0 form, which reports the space needed without advancing the cursor.

Returns match the NVML contract: SUCCESS with an empty payload and Required==0 when there are no (more) records, INSUFFICIENT_SIZE with Required set when records exist but do not fit, otherwise SUCCESS with the records and an advanced cursor.

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) SystemGetDriverBranch added in v0.6.0 

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

SystemGetDriverBranch returns the driver branch string. Callable before Init() for the same reason SystemGetDriverVersion is: nvidia-smi reads system-level strings during startup.

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) SystemGetHicVersion added in v0.6.0 

func (e *Engine) SystemGetHicVersion() ([]HICEntry, nvml.Return)

SystemGetHicVersion returns the configured host interface cards. Nodes without any — every modern DGX/HGX/NVL system, since HICs belong to the retired S-class enclosures — answer with an empty set and SUCCESS, which is what NVML documents: the call has no NOT_SUPPORTED return.

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) SystemGetNvlinkBwMode added in v0.5.0 

func (e *Engine) SystemGetNvlinkBwMode() (uint32, nvml.Return)

SystemGetNvlinkBwMode backs nvmlSystemGetNvlinkBwMode: the node-wide NVLink Reduced Bandwidth Mode.

func (*Engine) SystemRegisterEvents added in v0.6.0 

func (e *Engine) SystemRegisterEvents(token unsafe.Pointer, eventTypes uint64) nvml.Return

SystemRegisterEvents subscribes a set to the given event types. Bits outside the two types NVML defines are rejected, matching a driver that validates the mask rather than silently recording nothing.

func (*Engine) SystemSetNvlinkBwMode added in v0.5.0 

func (e *Engine) SystemSetNvlinkBwMode(mode uint32) nvml.Return

SystemSetNvlinkBwMode backs nvmlSystemSetNvlinkBwMode.

The docs also list NVML_ERROR_NO_PERMISSION for a non-root caller and NVML_ERROR_IN_USE when a P2P object exists. Neither is simulated: the mock models no notion of privilege and has no P2P object lifecycle.

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.

func (*Engine) VgpuInstance added in v0.6.0 

func (e *Engine) VgpuInstance(id uint32) (VgpuInstance, nvml.Return)

VgpuInstance resolves a vGPU instance ID. NVML reserves INVALID_ARGUMENT for ID 0 and answers NOT_FOUND for any other ID that matches no running instance. The ID encodes its GPU, so one on a GPU the caller cannot see is not found either.

func (*Engine) VgpuType added in v0.6.0 

func (e *Engine) VgpuType(id uint32) (VgpuType, nvml.Return)

VgpuType resolves a vGPU type ID against the visible GPUs. A type ID names the same type on every GPU that declares it, so the first match answers.

type FBCStatsConfig 

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

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,omitzero"`
	// 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"`
	// HealthSummary pins the overall fabric health nvidia-smi reports as
	// Fabric.Health.Summary: "healthy", "unhealthy", "limited_capacity"
	// or "not_supported". Empty (or "auto") derives it from the conditions
	// in Health, which is what makes an injected fault move the summary.
	HealthSummary string `json:"health_summary,omitempty"`
	// Health carries the individual fabric health conditions. Absent means
	// an all-clear fabric.
	Health *FabricHealthConfig `json:"health,omitempty"`
	// HealthMask is an escape hatch for the raw v2/v3 health bitmask,
	// for encodings Health cannot express. When set it replaces the mask
	// derived from Health wholesale, and the summary is derived from it.
	// A raw 0 means "the driver reported no health at all", which
	// nvidia-smi renders as N/A for the whole Health block.
	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 FabricHealthConfig added in v0.4.0 

type FabricHealthConfig struct {
	// DegradedBandwidth reports the fabric attachment as running below
	// full bandwidth (nvidia-smi Bandwidth: Degraded rather than Full).
	// On its own it summarises as limited capacity, not unhealthy.
	DegradedBandwidth bool `json:"degraded_bandwidth,omitzero"`
	// RouteRecovery reports a route recovery in progress.
	RouteRecovery bool `json:"route_recovery,omitzero"`
	// RouteUnhealthy reports the GPU's fabric route as unhealthy.
	RouteUnhealthy bool `json:"route_unhealthy,omitzero"`
	// AccessTimeoutRecovery reports an access-timeout recovery in progress.
	AccessTimeoutRecovery bool `json:"access_timeout_recovery,omitzero"`
	// IncorrectConfiguration names a detected fabric misconfiguration
	// ("no_partition", "insufficient_nvlinks", ...; see
	// FabricIncorrectConfigNames). Empty means none detected.
	IncorrectConfiguration string `json:"incorrect_configuration,omitempty"`
}

FabricHealthConfig models the individual NVLink fabric health conditions nvidia-smi renders under Fabric.Health, each mapping to one slot of the NVML health bitmask (see engine/fabric_health.go). Every condition defaults to its healthy value, so an absent block describes a healthy fabric rather than an unknown one.

PartitionAssigned is deliberately absent: real hardware leaves that field unanswered (nvidia-smi renders it as N/A even on a healthy rack), so the mock reports the same. Use HealthMask to encode it.

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,omitzero"`

	// 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,omitzero"`

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

	// 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,omitzero"`
	SpeedPercent       string `json:"speed_percent,omitempty"`
	TargetSpeedPercent string `json:"target_speed_percent,omitempty"`

	// MaxSpeedRPM is the tachometer reading at 100 %, which the RPM getter
	// scales by the current duty cycle. Zero means the board exposes no
	// tachometer, so the RPM reading is refused while the percentage still
	// answers — the split real hardware shows on boards whose fans are
	// driven but not measured.
	MaxSpeedRPM int `json:"max_speed_rpm,omitempty"`

	// MinSpeedPercent and MaxSpeedPercent bound what a manual write may ask
	// for. An unset maximum reads as 100, the envelope a discrete board
	// reports; a floor is left at 0 unless a profile declares one.
	MinSpeedPercent int `json:"min_speed_percent,omitempty"`
	MaxSpeedPercent int `json:"max_speed_percent,omitempty"`

	// Controls is per-fan control state: the policy in force and, under a
	// manual policy, the duty cycle that was asked for. A profile may
	// declare it to model a board that ships under manual control, and the
	// fan setters record their writes here through the override document.
	Controls []FanControlConfig `json:"controls,omitempty"`
}

FanConfig defines fan settings.

Count is the gate for the whole family: a board with no dedicated fans answers NOT_SUPPORTED to every fan query, which is what every profile Mokka ships reports and what the hardware captures confirm. The fields below only come into play on a profile that declares fans.

type FanControlConfig added in v0.5.0 

type FanControlConfig struct {
	Fan    int    `json:"fan"`
	Policy string `json:"policy,omitempty"`

	// SpeedPercent is a pointer so "manual at 0 %" — a real request, and the
	// one a caller makes to stop a fan — stays distinct from "no duty cycle
	// was ever asked for", which falls back to the board's reading.
	SpeedPercent *int `json:"speed_percent,omitempty"`
}

FanControlConfig is one fan's control state. Fan is the index the NVML per-fan entry points address, so an entry naming a fan the board does not have is ignored rather than aliased onto a fan it does.

type FeaturesConfig 

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

FeaturesConfig defines GPU-specific features (like Blackwell features).

Every field here is descriptive metadata that no getter reads. A key only belongs in this block while nothing depends on it: confidential_compute was removed once the Conf Compute memory getters landed, because real NVML answers those on any part and gating them on a capability claim would have made a T4 report N/A where a real one reports 0 MiB. See issue #711.

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,omitzero"`
	PcieRxMiBPerSec uint64 `json:"pcie_rx_mib_per_sec,omitzero"`
}

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 GpuInstanceTable added in v0.5.0 

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

GpuInstanceTable maps C handles to MIG GPU instances.

It is separate from the device table because NVML hands callers an nvmlGpuInstance_t that is distinct from a device handle: a caller creates an instance, keeps its handle, and later partitions or destroys through it.

Unlike devices, instances are destroyed while the library stays loaded, so this table supports Retire — see handleStore.Retire for why a destroyed instance's block is never reused.

func NewGpuInstanceTable added in v0.5.0 

func NewGpuInstanceTable() *GpuInstanceTable

NewGpuInstanceTable creates an empty GPU instance handle table.

func (*GpuInstanceTable) Clear added in v0.5.0 

func (s *GpuInstanceTable) Clear()

Clear invalidates every registered handle. The C blocks are retired, not freed (see handleStore.retired), so handles issued before the Clear stay invalid for the lifetime of the table even after new registrations.

func (*GpuInstanceTable) Count added in v0.5.0 

func (s *GpuInstanceTable) Count() int

Count returns the number of registered handles.

func (*GpuInstanceTable) Free added in v0.5.0 

func (s *GpuInstanceTable) Free()

Free releases every block, live and retired. Only for tests and teardown; any handle a client still holds becomes a dangling pointer afterwards.

func (*GpuInstanceTable) HandleFor added in v0.5.0 

func (s *GpuInstanceTable) HandleFor(item T) unsafe.Pointer

HandleFor returns the registered handle for an object, or nil when it has not been registered. Used by wiring that needs to translate an object back into 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 lets the caller treat that case as "no event yet".

func (*GpuInstanceTable) Lookup added in v0.5.0 

func (t *GpuInstanceTable) Lookup(handle unsafe.Pointer) (nvml.GpuInstance, bool)

Lookup returns the GPU instance for a handle, or false when the handle is not one this table issued or has since been retired.

func (*GpuInstanceTable) Register added in v0.5.0 

func (s *GpuInstanceTable) Register(item T) unsafe.Pointer

Register adds an object to the table and returns its handle, reusing the existing handle when the object is already registered. The handle is a pointer to C-allocated memory.

func (*GpuInstanceTable) Retire added in v0.5.0 

func (s *GpuInstanceTable) Retire(item T)

Retire invalidates the handle for a single object, for the MIG instances that are destroyed while the library stays loaded. The block is retired rather than freed, so the caller's now-stale handle keeps failing lookup instead of aliasing a later instance that reused the address.

type HICConfig added in v0.6.0 

type HICConfig struct {
	ID              uint32 `json:"id,omitzero"`
	FirmwareVersion string `json:"firmware_version,omitempty"`
}

HICConfig describes one host interface card.

type HICEntry added in v0.6.0 

type HICEntry struct {
	ID              uint32
	FirmwareVersion string
}

HICEntry is one host interface card, the engine's view of nvmlHwbcEntry_t.

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 (s *HandleTable) Clear()

Clear invalidates every registered handle. The C blocks are retired, not freed (see handleStore.retired), so handles issued before the Clear stay invalid for the lifetime of the table even after new registrations.

func (*HandleTable) Count 

func (s *HandleTable) Count() int

Count returns the number of registered handles.

func (*HandleTable) Free added in v0.4.0 

func (s *HandleTable) Free()

Free releases every block, live and retired. Only for tests and teardown; any handle a client still holds becomes a dangling pointer afterwards.

func (*HandleTable) HandleFor added in v0.2.0 

func (s *HandleTable) HandleFor(item T) unsafe.Pointer

HandleFor returns the registered handle for an object, or nil when it has not been registered. Used by wiring that needs to translate an object back into 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 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 (s *HandleTable) Register(item T) unsafe.Pointer

Register adds an object to the table and returns its handle, reusing the existing handle when the object is already registered. The handle is a pointer to C-allocated memory.

func (*HandleTable) Retire added in v0.5.0 

func (s *HandleTable) Retire(item T)

Retire invalidates the handle for a single object, for the MIG instances that are destroyed while the library stays loaded. The block is retired rather than freed, so the caller's now-stale handle keeps failing lookup instead of aliasing a later instance that reused the address.

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 MIGComputeInstanceConfig added in v0.5.0 

type MIGComputeInstanceConfig struct {
	Profile   string `json:"profile,omitempty"`
	ProfileID *int   `json:"profile_id,omitempty"`
	Count     int    `json:"count,omitzero"`
}

MIGComputeInstanceConfig declares one or more identical compute instances inside a GPU instance. The profile is the compute-slice spelling NVML uses, e.g. "1c" for a single slice; ProfileID takes a raw NVML profile ID.

type MIGComputeInstanceLayout added in v0.5.0 

type MIGComputeInstanceLayout struct {
	ID uint32
	// UUID is what NVML hands out for this partition. It travels: the device
	// plugin reports it as the allocated device's ID, and the container runtime
	// then resolves that name against the CDI spec the agent writes. Carrying
	// it here is what keeps those two from having to derive it independently.
	UUID string
}

MIGComputeInstanceLayout is one compute instance, which is to say one MIG device: a consumer addresses a partition by the UUID NVML reports for the compute instance, not by the GPU instance containing it.

type MIGComputeInstanceRecord added in v0.5.0 

type MIGComputeInstanceRecord struct {
	ID        uint32 `json:"id"`
	Profile   string `json:"profile,omitempty"`
	ProfileID *int   `json:"profile_id,omitempty"`
}

MIGComputeInstanceRecord is one compute instance that exists inside a GPU instance.

type MIGComputeInstanceSpec added in v0.5.0 

type MIGComputeInstanceSpec struct {
	NVMLProfile string `json:"nvml_profile"`
	// Slices is cross-checked against NVMLProfile the same way
	// MIGProfileSpec.Slices is, and additionally bounded by the width of the
	// GPU instance the row sits in.
	Slices            int `json:"slices,omitzero"`
	Instances         int `json:"instances"`
	Multiprocessors   int `json:"multiprocessors,omitzero"`
	SharedCopyEngines int `json:"shared_copy_engines,omitzero"`
	Decoders          int `json:"decoders,omitzero"`
	Encoders          int `json:"encoders,omitzero"`
	JPEG              int `json:"jpeg,omitzero"`
	OFA               int `json:"ofa,omitzero"`
}

MIGComputeInstanceSpec is one row of a GPU instance's compute-instance listing.

Multiprocessors is this compute instance's own share of the GPU instance's SMs. The fixed-function engines are not divided that way: NVML reports them as Shared* because every compute instance inside a GPU instance sees all of them, so Decoders through OFA repeat the GPU instance's counts.

type MIGConfig 

type MIGConfig struct {
	ModeCurrent     string `json:"mode_current,omitempty"`
	ModePending     string `json:"mode_pending,omitempty"`
	MaxGPUInstances int    `json:"max_gpu_instances,omitzero"`
	// SupportedProfiles is the board's MIG profile table: the rows
	// `nvidia-smi mig -lgip` prints. It is declared here rather than derived
	// in Go so that teaching the mock a new board is a YAML edit. A board
	// declaring none is not MIG-capable, which is how l40s and t4 report
	// ERROR_NOT_SUPPORTED.
	SupportedProfiles []MIGProfileSpec       `json:"supported_profiles,omitempty"`
	GPUInstances      []MIGGPUInstanceConfig `json:"gpu_instances,omitempty"`
	// Instances is the explicit layout: exactly which GPU instances exist,
	// with the IDs and placements they were created under. It is what a
	// runtime mutation through NVML records, because a count cannot express
	// a layout with a hole in it — delete instance 1 of three and the
	// survivors are 0 and 2, which "count: 2" would reload as 0 and 1.
	//
	// A pointer because absent and present-but-empty differ: an empty list is
	// a MIG-enabled board with every instance deleted, and must not fall back
	// to GPUInstances.
	Instances *[]MIGGPUInstanceRecord `json:"instances,omitempty"`
}

MIGConfig defines MIG configuration.

GPUInstances declares the partitioning the device boots with. It is only honoured while mode_current is "enabled", so a profile can carry the layout its board would normally be partitioned into and leave MIG off. The declared layout seeds in-memory state that NVML callers can then add to and destroy, the same way nvidia-mig-parted would on real hardware.

type MIGGPUInstanceConfig added in v0.5.0 

type MIGGPUInstanceConfig struct {
	Profile   string `json:"profile,omitempty"`
	ProfileID *int   `json:"profile_id,omitempty"`
	Count     int    `json:"count,omitzero"`
	// ComputeInstances defaults to a single instance spanning the whole GPU
	// instance, which is the only partitioning most consumers ask for and
	// what nvidia-mig-parted creates when a profile names no compute slices.
	ComputeInstances []MIGComputeInstanceConfig `json:"compute_instances,omitempty"`
}

MIGGPUInstanceConfig declares one or more identical GPU instances.

The profile is named the way the cluster names it — "1g.10gb", "2g.20gb", "1g.5gb+me" — so that what a profile declares reads the same as the nvidia.com/mig-<profile> resource the device plugin ends up publishing. ProfileID is the escape hatch for a raw NVML profile ID; exactly one of the two must be set.

type MIGGPUInstanceRecord added in v0.5.0 

type MIGGPUInstanceRecord struct {
	ID             uint32 `json:"id"`
	Profile        string `json:"profile,omitempty"`
	ProfileID      *int   `json:"profile_id,omitempty"`
	PlacementStart *int   `json:"placement_start,omitempty"`
	// ComputeInstances is a pointer for the same reason MIGConfig.Instances
	// is: a GPU instance with no compute instances is a state hardware has —
	// `nvidia-smi mig -cgi` without -C creates one, and deleting the last
	// compute instance leaves one — so an empty list must not read as
	// unspecified and be handed the spanning default back.
	ComputeInstances *[]MIGComputeInstanceRecord `json:"compute_instances,omitempty"`
}

MIGGPUInstanceRecord is one GPU instance that exists, as opposed to MIGGPUInstanceConfig which declares how many of a shape to create.

PlacementStart pins the instance to a slice offset. It is optional: an omitted placement lets the engine choose the first free slot, which is what a layout hand-written for a test usually wants.

type MIGGpuInstanceLayout added in v0.5.0 

type MIGGpuInstanceLayout struct {
	ID uint32
	// Profile is the canonical name, e.g. "1g.5gb" — the same spelling the
	// device plugin derives its nvidia.com/mig-<profile> resource from.
	Profile          string
	ComputeInstances []MIGComputeInstanceLayout
}

MIGGpuInstanceLayout is one GPU instance and the compute instances inside it.

type MIGLayout added in v0.5.0 

type MIGLayout struct {
	GPUIndex     int
	GPUInstances []MIGGpuInstanceLayout
}

MIGLayout is the MIG partitioning one GPU boots with, described in the terms the driver's capability surface is keyed by: GPU index, GPU instance ID and compute instance ID.

func DeclaredMIGLayout added in v0.5.0 

func DeclaredMIGLayout(config *Config) []MIGLayout

DeclaredMIGLayout reports the partitioning a profile boots with, for callers outside NVML that must agree with it — chiefly the node agent, which stages the /dev/nvidia-caps nodes and the mig-minors table keyed by these IDs.

It exists so those IDs have a single source of truth. The alternative, having the agent re-derive the layout from the same YAML, looks equivalent but is not: instance IDs come from placement allocation, so any drift between the two derivations would hand a consumer cap minors belonging to a different partition — a mismatch that would surface as a mis-scheduled pod rather than an error.

Only devices that boot partitioned appear; a profile that declares a layout with MIG mode off contributes nothing, because nothing is partitioned.

type MIGPlacementSpec added in v0.5.0 

type MIGPlacementSpec struct {
	Start uint32 `json:"start"`
	Size  uint32 `json:"size"`
}

MIGPlacementSpec is one slot a GPU instance profile may occupy on the board.

Start and Size are measured in memory units, not compute slices. A board has as many memory units as the next power of two at or above its compute-slice count — eight for a 7-slice datacenter board — so a 3g partition holding half the memory occupies four of eight units and a 7g partition occupies all eight. Reading Size as a slice count is what makes go-nvml's H100 table report a 7g placement of size 7.

type MIGProfileSpec added in v0.5.0 

type MIGProfileSpec struct {
	Name        string `json:"name"`
	NVMLProfile string `json:"nvml_profile"`
	// Slices is how many compute slices the partition spans. NVMLProfile
	// carries the same fact — gpuInstanceSliceCount answers it for every enum
	// — and validateMIGProfileSpec refuses a row where the two disagree, so
	// neither source is trusted alone. That cross-check is what makes stating
	// the width here a second reading of one fact rather than a second source
	// for it.
	Slices int `json:"slices,omitzero"`
	// ProfileID is the id the board publishes for this profile, which is what
	// nvmlDeviceCreateGpuInstance takes. It is not the NVML profile enum: an
	// A100's 1g.5gb is enum 0 and reports 19.
	//
	// There is no absent state to distinguish, so it is a plain int: 0 is a
	// real reported id — the full-board 7g of an A100 or H100 publishes it —
	// and nothing is derived for a row that omits the key. A row omitting it
	// therefore publishes 0, which validateMIGSupportedProfiles refuses as
	// soon as a second row on the board does the same.
	ProfileID int    `json:"profile_id"`
	Instances int    `json:"instances"`
	MemoryMB  uint64 `json:"memory_mb"`
	// Placements are the slots on the board this profile may occupy.
	Placements []MIGPlacementSpec `json:"placements,omitempty"`
	// ComputeInstances is the profile's `nvidia-smi mig -lcip` listing. A GPU
	// instance does not offer every width that fits inside it — a 7-slice
	// instance offers 3c and 4c and then jumps to 7c — which is why the
	// listing is declared per row rather than enumerated from the width.
	ComputeInstances []MIGComputeInstanceSpec `json:"compute_instances,omitempty"`
	Multiprocessors  int                      `json:"multiprocessors,omitzero"`
	CopyEngines      int                      `json:"copy_engines,omitzero"`
	Decoders         int                      `json:"decoders,omitzero"`
	Encoders         int                      `json:"encoders,omitzero"`
	JPEG             int                      `json:"jpeg,omitzero"`
	OFA              int                      `json:"ofa,omitzero"`
}

MIGProfileSpec is one row of a board's MIG profile table, transcribed from NVIDIA's MIG user guide.

NVMLProfile binds the row to the NVML enum every lookup keys on: the suffix of the NVML_GPU_INSTANCE_PROFILE_* constant that nvmlDeviceGetGpuInstanceProfileInfo takes as its profile argument. ProfileID is the number that call returns, which is why the two are separate keys and why neither name is a synonym for the other.

The suffix vocabulary is shared with NVML_COMPUTE_INSTANCE_PROFILE_*, so MIGComputeInstanceSpec spells its own binding with the same field name and the enclosing block decides which family a value names.

It is named rather than inferred from Name: the +me, +gfx, -me and +me.all families make a display name an unreliable key. What validateMIGSupportedProfiles refuses is an enum it does not recognise or one declared twice; Name stays authoritative for what `nvidia-smi mig -lgip` prints and is not reconciled against the enum's span.

A row describes its partition completely: the slices it spans, the id the board reports for it, where it may sit, and the compute instances it offers. Geometry an algorithm cannot express is geometry the mock cannot mock, so none of it is computed from the rest.

type MIGProfilesDocument added in v0.5.0 

type MIGProfilesDocument struct {
	Version           int              `json:"version"`
	SupportedProfiles []MIGProfileSpec `json:"supported_profiles"`
}

MIGProfilesDocument is a board's MIG profile table, held in its own file rather than inside the profile that describes the board.

SupportedProfiles is the same type the profile declares inline, so a table decodes and validates identically wherever it was authored. See MIGConfig.SupportedProfiles for what the rows mean.

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,omitzero"`
	FreeBytes      uint64 `json:"free_bytes,omitzero"`
	UsedBytes      uint64 `json:"used_bytes,omitzero"`
	MemoryBusWidth uint32 `json:"memory_bus_width,omitzero"` // 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.

Both sides of the comparison are normalized so any spelling of an address resolves, as it does on real NVML: callers arrive with the 8-digit busId they read back from nvmlDeviceGetPciInfo (DCGM), with the 4-digit sysfs BDF, or with either in lower case.

func (*MockServer) DeviceGetHandleBySerial added in v0.5.0 

func (s *MockServer) DeviceGetHandleBySerial(serial string) (nvml.Device, nvml.Return)

DeviceGetHandleBySerial returns the visible device carrying a board serial. A serial names a board rather than a GPU, which is why nvml.h deprecates the call: when more than one visible GPU carries it — the two GPUs of a GB200 superchip — the lookup is ambiguous and fails with INVALID_ARGUMENT.

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 NVLinkBwModeConfig added in v0.5.0 

type NVLinkBwModeConfig struct {
	// Scope selects the one NVML function family that answers; the other
	// answers NOT_SUPPORTED. A real board answers one or the other, never
	// both, so this is a choice rather than two flags.
	Scope NVLinkBwModeScope `json:"scope,omitempty"`

	// Supported is the list of modes the board accepts, and what
	// nvmlDeviceGetNvlinkSupportedBwModes reports. Empty means the five modes
	// the bundled nvidia-smi can name.
	Supported []uint8 `json:"supported,omitempty"`

	// Mode is the initial current mode. A pointer so that an explicit 0
	// (FULL) is distinguishable from "unset".
	Mode *uint8 `json:"mode,omitempty"`
}

NVLinkBwModeConfig declares the NVLink Reduced Bandwidth Mode surface.

Mode values are opaque driver indices; the bundled nvidia-smi names them 0=FULL, 1=OFF, 2=MIN, 3=HALF, 4=3QUARTER, so a value above 4 would index past its name table and render as garbage.

type NVLinkBwModeScope added in v0.5.0 

type NVLinkBwModeScope string

NVLinkBwModeScope names which NVML function family answers for the NVLink Reduced Bandwidth Mode. 

const (
	// NVLinkBwModeScopeSystem is the node-wide pair,
	// nvmlSystemGet/SetNvlinkBwMode, which is what `nvidia-smi nvlink
	// -gBwMode` and -sBwMode call. Hopper boards answer on it.
	NVLinkBwModeScopeSystem NVLinkBwModeScope = "system"
	// NVLinkBwModeScopeDevice is the per-device trio,
	// nvmlDeviceGet/SetNvlinkBwMode and nvmlDeviceGetNvlinkSupportedBwModes,
	// which no nvidia-smi flag reaches. Blackwell boards answer on it and
	// decline the node-wide pair.
	NVLinkBwModeScopeDevice NVLinkBwModeScope = "device"
)

type NVLinkConfig 

type NVLinkConfig struct {
	Version     int `json:"version,omitzero"`
	LinksPerGPU int `json:"links_per_gpu,omitzero"`
	// 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,omitzero"`
	C2CEnabled           bool `json:"c2c_enabled,omitzero"`

	// MultiNode marks a board whose NVLink domain spans nodes (GB200 and GB300
	// NVL72, later Vera Rubin and NVL576), as opposed to an NVLink fabric
	// confined to one baseboard (HGX). Only such boards run IMEX and take part
	// in DRA ComputeDomains.
	MultiNode bool `json:"multi_node,omitempty"`

	// NvleEnabled mirrors nvlink.nvle_enabled: NVLink encryption, reported
	// by nvmlDeviceGetNvLinkInfo and the " NVLE:" row of
	// `nvidia-smi nvlink --info`. Node-level for the same reason C2C is —
	// it is a property of the board, not of one GPU.
	NvleEnabled bool `json:"nvle_enabled,omitempty"`

	// BwMode declares the NVLink Reduced Bandwidth Mode surface. Absent means
	// the board has none, and every bandwidth-mode call answers NOT_SUPPORTED.
	BwMode *NVLinkBwModeConfig `json:"bw_mode,omitempty"`

	// Firmware declares the NVLink firmware versions reported alongside
	// NVLE. Absent reports none, which nvidia-smi renders as "N/A".
	Firmware *NVLinkFirmwareConfig `json:"firmware,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,omitzero"`
	// CounterSeed is the baseline value added to every utilization counter.
	CounterSeed uint64 `json:"counter_seed,omitzero"`
	// ErrorRate is the per-second accrual rate for NVLink error counters.
	// Defaults to 0 (healthy links report no errors).
	ErrorRate float64 `json:"error_rate,omitzero"`
}

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,omitzero"`

	// 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 NVLinkFirmwareConfig added in v0.5.0 

type NVLinkFirmwareConfig struct {
	MSE       string `json:"mse,omitempty"`
	NETIR     string `json:"netir,omitempty"`
	NETIRUPHY string `json:"netir_uphy,omitempty"`
	NETIRCLN  string `json:"netir_cln,omitempty"`
	NETIRDLN  string `json:"netir_dln,omitempty"`
}

NVLinkFirmwareConfig declares the NVLink firmware versions nvmlDeviceGetNvLinkInfo reports, which `nvidia-smi nvlink --info` renders under "Firmware Version:".

Each value is "major:minor:subMinor", the form nvidia-smi prints, so a line read off real hardware transfers to a profile unchanged. An omitted component is left out of the table rather than reported as zero, because the board either carries that microcontroller or it does not.

The fields are named rather than a free list because the label is chosen by the ucodeType index, of which nvml.h defines exactly these five, and nvidia-smi exits non-zero on an index it cannot name — an open-ended list would let a profile break `--info` outright.

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"`

	// DeviceID is the packed PCI identity word, (device<<16)|vendor, as
	// device_defaults.pci.device_id carries for a GPU — 0x22a310de for an
	// H100 NVSwitch. Setting it is what puts the switch in the node's
	// rendered PCI tree, where lspci enumerates it as a bridge next to the
	// GPUs, the way it appears on an HGX baseboard.
	//
	// Leave it unset for a switch the node cannot see over PCIe: on
	// GB200/GB300 NVL the switches are in their own trays, so the compute
	// tray's lspci shows the GPUs and no bridges. Such a switch still serves
	// as an NVLink remote endpoint.
	DeviceID uint32 `json:"device_id,omitzero"`
	// SubsystemID is the packed subsystem word, (subdevice<<16)|subvendor.
	// Only meaningful alongside DeviceID.
	SubsystemID uint32 `json:"subsystem_id,omitzero"`
}

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) C2CEnabled added in v0.4.0 

func (f *NodeFabric) C2CEnabled() bool

C2CEnabled reports whether the node's nvlink block declares an NVLink-C2C link to the host CPU. Nil-safe: legacy/default mode builds no fabric, and a GPU with no declared NVLink topology has no C2C link either.

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 (f *NodeFabric) HasNvlink(dev int) bool

HasNvlink reports whether a device has NVLink at all, either because the profile declares a per-GPU link count or because the fabric resolved links for it. Either is enough: a profile may hand-author links without a count.

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) NvleEnabled added in v0.5.0 

func (f *NodeFabric) NvleEnabled() bool

NvleEnabled reports whether the node's nvlink block declares NVLink encryption. Nil-safe: legacy/default mode builds no fabric.

func (*NodeFabric) NvlinkBwModeScope added in v0.5.0 

func (f *NodeFabric) NvlinkBwModeScope() NVLinkBwModeScope

NvlinkBwModeScope returns which NVML function family answers for the bandwidth mode, or "" when none does. Nil-safe: legacy/default mode builds no fabric.

func (*NodeFabric) NvlinkConfiguredBwMode added in v0.5.0 

func (f *NodeFabric) NvlinkConfiguredBwMode() (uint8, bool)

NvlinkConfiguredBwMode returns the configured initial bandwidth mode and whether the profile declared one at all.

func (*NodeFabric) NvlinkFirmware added in v0.5.0 

func (f *NodeFabric) NvlinkFirmware() []NvlinkFirmwareVersion

NvlinkFirmware returns the configured NVLink firmware table in ucodeType order, or nil when the profile declared none. Nil-safe: legacy/default mode builds no fabric.

func (*NodeFabric) NvlinkSupportedBwModes added in v0.5.0 

func (f *NodeFabric) NvlinkSupportedBwModes() []uint8

NvlinkSupportedBwModes returns the configured supported bandwidth-mode list, or nil when the profile did not declare one.

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 about the nvlink block: unresolved endpoints, and a bandwidth-mode setting that contradicts itself. Runtime callers warn-and-continue; the built-in profile test asserts this is empty for shipped profiles (decision D-b).

type NvLinkInfo added in v0.5.0 

type NvLinkInfo struct {
	NvleEnabled bool
	Firmware    []NvlinkFirmwareVersion
}

NvLinkInfo is what nvmlDeviceGetNvLinkInfo reports: NVLink encryption and the firmware table, the two halves of `nvidia-smi nvlink --info`.

type NvlinkFirmwareVersion added in v0.5.0 

type NvlinkFirmwareVersion struct {
	UcodeType uint8
	Major     uint32
	Minor     uint32
	SubMinor  uint32
}

NvlinkFirmwareVersion is one row of the NVLink firmware table, carrying the ucodeType that selects nvidia-smi's label and the three version components it renders as major:minor:subMinor.

type OverrideWriter added in v0.5.0 

type OverrideWriter interface {
	// SetPowerLimit records a power cap, in milliwatts, for one device.
	SetPowerLimit(index int, milliwatts uint32) error

	// SetPersistenceMode records whether persistence mode is enabled.
	SetPersistenceMode(index int, enabled bool) error

	// SetDrainState records whether the device is draining.
	SetDrainState(index int, draining bool) error

	// SetRemoved records whether the device was removed from the driver.
	SetRemoved(index int, removed bool) error

	// UpdateWorkloadProfiles replaces a device's requested profile list with
	// the one apply computes from the list already recorded.
	//
	// The caller passes apply rather than a finished list because the NVML
	// operations are read-modify-write, and the base has to be read under the
	// same lock as the write or concurrent callers lose an update. present
	// separates "nothing has been written" from "written, then cleared": only
	// the first may fall back to the profile's configured request.
	UpdateWorkloadProfiles(index int, apply func(base []uint32, present bool) ([]uint32, error)) error

	// SetNvlinkBwMode records an NVLink Reduced Bandwidth Mode. allDevices
	// selects the `all:` bucket, which is how the node-wide NVML pair writes
	// a value that is not about one device; otherwise it applies to index.
	SetNvlinkBwMode(index int, mode uint8, allDevices bool) error

	// SetNvlinkLowPowerThreshold records an NVLink low-power threshold for one
	// device. A nil threshold clears the recorded value, which is what the
	// setter's reset sentinel asks for — the field has a driver default to
	// fall back to, so clearing it is meaningful rather than ambiguous.
	SetNvlinkLowPowerThreshold(index int, threshold *uint32) error

	// SetApplicationsClocks records the memory and graphics applications
	// clocks for one device.
	SetApplicationsClocks(index int, memMHz, graphicsMHz uint32) error

	// SetLockedClocks records the range one clock domain is locked to. A nil
	// range clears the lock, which is what the reset setters ask for: unlocked
	// is the absence of a range, not a range of its own.
	SetLockedClocks(index int, domain ClockDomain, r *ClockRangeConfig) error

	// SetClockOffset records the offset applied to one clock domain.
	SetClockOffset(index int, domain ClockDomain, offsetMHz int32) error

	// UpdateFanControl replaces a device's per-fan control state with the one
	// apply computes from the state already recorded.
	//
	// apply is passed the whole list rather than one fan's entry because the
	// fan setters address a single fan while the recorded state covers every
	// one, so the fold has to happen under the write's lock for the same
	// reason UpdateWorkloadProfiles does. present separates "nothing has been
	// written" from "written, then emptied"; only the first falls back to the
	// control state the profile declares.
	UpdateFanControl(index int, apply func(base []FanControlConfig, present bool) ([]FanControlConfig, error)) error

	// SetPowerMizerMode records the PowerMizer mode, by its config name, for
	// one device.
	SetPowerMizerMode(index int, mode string) error

	// SetPowerSmoothingState records whether power smoothing is enabled.
	SetPowerSmoothingState(index int, enabled bool) error

	// SetPowerSmoothingActiveProfile records the preset profile in force.
	SetPowerSmoothingActiveProfile(index int, profileID uint32) error

	// SetPowerSmoothingProfileParam records one parameter of one preset
	// profile. The value has already been validated for param.
	SetPowerSmoothingProfileParam(index int, profileID uint32, param PowerSmoothingParam, value float64) error

	// SetAccountingMode records whether per-process accounting is enabled.
	// Disabling also empties the terminated records, because turning
	// accounting off clears every record the driver held.
	SetAccountingMode(index int, enabled bool) error

	// ClearAccountingPids empties the records of processes that have exited.
	ClearAccountingPids(index int) error

	// SetEccModePending records the ECC mode that applies after the next GPU
	// reset. The current mode is left alone, as it is on hardware.
	SetEccModePending(index int, enabled bool) error

	// ClearEccErrorCounts records the zeroing of one scope of ECC error
	// counters, DRAM and SRAM alike.
	ClearEccErrorCounts(index int, scope EccCounterScope) error

	// SetDramEncryptionPending records the DRAM encryption mode that applies
	// after the next reboot.
	SetDramEncryptionPending(index int, enabled bool) error
}

OverrideWriter records setter writes in the shared override document.

type PCIConfig 

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

PCIConfig defines PCI device information

type PCIeConfig 

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

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,omitzero"`
}

PCIeTopologyConfig describes the root-complex / NUMA layout consumed by the pcibus simulator. CoresPerNUMA synthesizes a CPU affinity set per NUMA node when a root complex does not declare an explicit cpu_affinity range.

type PlatformConfig added in v0.4.0 

type PlatformConfig struct {
	// ChassisSerialNumber identifies the chassis (the rack). Rendered as a
	// string, so real values are the 13-digit serial read from the backplane
	// EEPROM. Truncated to 15 characters plus a terminator.
	ChassisSerialNumber string `json:"chassis_serial_number,omitempty"`
	// SlotNumber is the absolute physical slot in the chassis, counting
	// switch trays as well as compute trays (1-27 on NVL72).
	SlotNumber uint8 `json:"slot_number,omitzero"`
	// TrayIndex is the position of this tray among compute trays only, so it
	// runs below SlotNumber on a rack whose switch trays sit in between
	// (1-18 on NVL72).
	TrayIndex uint8 `json:"tray_index,omitzero"`
	// HostID identifies the OS domain within the tray — this node.
	HostID uint8 `json:"host_id,omitzero"`
	// PeerType is how this GPU reaches its NVLink peers:
	// "switch_connected" through an NVSwitch tray, or "direct_connected".
	// Empty defaults to direct. See PeerType* constants.
	PeerType string `json:"peer_type,omitempty"`
	// ModuleID is the id of this GPU within the node, and the one field a
	// profile is expected to vary per device.
	ModuleID uint8 `json:"module_id,omitzero"`
}

PlatformConfig models the platform identity nvmlDeviceGetPlatformInfo exposes, which `nvidia-smi -q` renders as its "Platform Info" block. It is what turns a GPU fault into an actionable physical location on NVL72: module 2 of the tray in slot 9 of a given chassis.

The fields live on DeviceConfig so a profile can set any of them per device, but only ModuleID varies between the GPUs of a shipped profile. NVML defines the rest as properties of the node — see PlatformInfo — and a node occupies exactly one tray in one slot of one chassis.

type PlatformInfo added in v0.4.0 

type PlatformInfo struct {
	ChassisSerialNumber [chassisSerialLen]byte
	SlotNumber          uint8
	TrayIndex           uint8
	HostID              uint8
	PeerType            uint8
	ModuleID            uint8
}

PlatformInfo is the engine-internal shape of a GPU's platform identity — where the board physically sits in a rack. The CGo bridge converts it to whichever nvmlPlatformInfo_t struct version the caller selected.

Only ModuleID is per-GPU: NVML defines it as "ID of this GPU within the node", while the chassis serial, slot, tray, and host id describe the one node this process runs on and are therefore shared by all of its GPUs. No IbGuid: nvidia-smi sources "GPU Fabric GUID" from nvmlDeviceGetPdi, so carrying an unread GUID through the engine would only be dead weight.

type PowerConfig 

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

	// WorkloadProfiles opts a device into the Blackwell workload power
	// profile feature. Absent means the device declines it, which is what
	// every pre-Blackwell part does.
	WorkloadProfiles *WorkloadPowerProfilesConfig `json:"workload_power_profiles,omitempty"`

	// PowerMizerMode is the PowerMizer mode the device starts in: adaptive,
	// prefer_maximum_performance, auto or prefer_consistent_performance.
	// Empty, or a name NVML does not define, is auto — the driver-controlled
	// mode.
	PowerMizerMode string `json:"power_mizer_mode,omitempty"`

	// Smoothing configures the datacenter power smoothing feature that
	// `nvidia-smi power-smoothing` drives. Absent still models the feature on
	// Blackwell and newer, disabled and with all-zero presets.
	Smoothing *PowerSmoothingConfig `json:"smoothing,omitempty"`
}

PowerConfig defines power management settings

type PowerSmoothingConfig added in v0.6.0 

type PowerSmoothingConfig struct {
	// Supported overrides the architecture default, which is Blackwell and
	// newer.
	Supported *bool `json:"supported,omitempty"`

	// State is "enabled" or "disabled"; anything else is disabled.
	State string `json:"state,omitempty"`

	// ActiveProfile is the preset in force, 0-4.
	ActiveProfile uint32 `json:"active_profile,omitzero"`

	// Profiles holds the preset definitions by profile id. It is a map
	// rather than a list so a setter can record one parameter of one preset
	// without rewriting the others.
	Profiles map[uint32]PowerSmoothingProfileConfig `json:"profiles,omitempty"`
}

PowerSmoothingConfig models power smoothing, which holds the module's power draw between a floor and the power limit while a workload ramps. Only the reported and persisted state is simulated; it does not shape the simulated power draw.

type PowerSmoothingParam added in v0.6.0 

type PowerSmoothingParam uint32

PowerSmoothingParam is an NVML_POWER_SMOOTHING_PROFILE_PARAM_* value. The 580 driver defines four; the four the CUDA 13.3 header adds after them do not exist there. 

const (
	PowerSmoothingParamPercentTMPFloor    PowerSmoothingParam = nvml.POWER_SMOOTHING_PROFILE_PARAM_PERCENT_TMP_FLOOR
	PowerSmoothingParamRampUpRate         PowerSmoothingParam = nvml.POWER_SMOOTHING_PROFILE_PARAM_RAMP_UP_RATE
	PowerSmoothingParamRampDownRate       PowerSmoothingParam = nvml.POWER_SMOOTHING_PROFILE_PARAM_RAMP_DOWN_RATE
	PowerSmoothingParamRampDownHysteresis PowerSmoothingParam = nvml.POWER_SMOOTHING_PROFILE_PARAM_RAMP_DOWN_HYSTERESIS
)

The preset profile parameters the 580 driver defines.

func (PowerSmoothingParam) ConfigKey added in v0.6.0 

func (p PowerSmoothingParam) ConfigKey() string

ConfigKey is the PowerSmoothingProfileConfig field the parameter is recorded under.

type PowerSmoothingProfileConfig added in v0.6.0 

type PowerSmoothingProfileConfig struct {
	// PercentTMPFloor is the floor as a percentage of the power limit
	// (TMP, total module power), 0-100.
	PercentTMPFloor float64 `json:"percent_tmp_floor,omitzero"`

	RampUpRateMWPerS     float64 `json:"ramp_up_rate_mw_per_s,omitzero"`
	RampDownRateMWPerS   float64 `json:"ramp_down_rate_mw_per_s,omitzero"`
	RampDownHysteresisMS uint32  `json:"ramp_down_hysteresis_ms,omitzero"`
}

PowerSmoothingProfileConfig is one preset profile definition. A preset the config leaves out has every parameter at zero.

type ProcessConfig 

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

ProcessConfig defines a running process

type RemappedRowsConfig 

type RemappedRowsConfig struct {
	Correctable           int                      `json:"correctable,omitzero"`
	Uncorrectable         int                      `json:"uncorrectable,omitzero"`
	Pending               bool                     `json:"pending,omitzero"`
	FailureOccurred       bool                     `json:"failure_occurred,omitzero"`
	AvailabilityHistogram *RowRemapHistogramConfig `json:"availability_histogram,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
)

RemoteKind values classify the remote endpoint of an NVLink. 

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,omitzero"`
	PendingRetirement   bool                  `json:"pending_retirement,omitzero"`
}

RetiredPagesConfig defines retired pages information

type RetirementInfoConfig 

type RetirementInfoConfig struct {
	Count     int      `json:"count,omitzero"`
	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,omitzero"`
	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 RowRemapHistogramConfig added in v0.4.0 

type RowRemapHistogramConfig struct {
	Max     uint32 `json:"max,omitzero"`
	High    uint32 `json:"high,omitzero"`
	Partial uint32 `json:"partial,omitzero"`
	Low     uint32 `json:"low,omitzero"`
	None    uint32 `json:"none,omitzero"`
}

RowRemapHistogramConfig defines how many memory banks fall into each row-remap availability bucket, i.e. how much spare capacity is left to remap future failures. Row remapping is Ampere and later, so leaving this unset makes the mock report the feature as unsupported.

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,omitzero"`

	// DriverBranch names the driver branch nvmlSystemGetDriverBranch reports.
	// Left empty it is derived from DriverVersion (580.65.06 -> r580_00), so
	// only a profile modelling a point-release branch needs to state it.
	DriverBranch string `json:"driver_branch,omitempty"`

	// HIC lists the host interface cards nvmlSystemGetHicVersion reports, which
	// nvidia-smi renders as the `hic_info` block of `nvidia-smi -q -u`. Absent
	// on every modern system: HICs belong to the retired S-class enclosures.
	HIC []HICConfig `json:"hic,omitempty"`
}

SystemConfig contains system-level NVML settings

type SystemEvent added in v0.6.0 

type SystemEvent struct {
	Type  uint64
	GpuID uint32
}

SystemEvent is one driver bind/unbind transition. GpuID carries the PCI-format GPU id NVML puts in nvmlSystemEventData_v1_t.

type ThermalConfig 

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

ThermalConfig defines thermal settings

type ThrottleCountersConfig added in v0.4.0 

type ThrottleCountersConfig struct {
	SWPowerCapUS           uint64 `json:"sw_power_cap_us,omitzero"`
	SyncBoostUS            uint64 `json:"sync_boost_us,omitzero"`
	SWThermalSlowdownUS    uint64 `json:"sw_thermal_slowdown_us,omitzero"`
	HWThermalSlowdownUS    uint64 `json:"hw_thermal_slowdown_us,omitzero"`
	HWPowerBrakeSlowdownUS uint64 `json:"hw_power_brake_slowdown_us,omitzero"`
}

ThrottleCountersConfig is the starting value of each clocks-event counter, in microseconds — the unit nvidia-smi prints them in and the unit a reading off a real tray is copied from. A device accrues further time on top of these while the matching flag above is set, but only within one process, so a throttle state entered at runtime carries no history of its own: the baseline here is what makes an Active flag read as a duration rather than as the age of the calling process. Omitting the block means a GPU that has never been throttled, which reports 0 rather than N/A.

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,omitzero"`
	Memory  uint32 `json:"memory,omitzero"`
	Encoder uint32 `json:"encoder,omitzero"`
	Decoder uint32 `json:"decoder,omitzero"`
	JPEG    uint32 `json:"jpeg,omitzero"`
	OFA     uint32 `json:"ofa,omitzero"`
}

UtilizationConfig defines utilization percentages

type VGPUConfig added in v0.6.0 

type VGPUConfig struct {
	Types     []VGPUTypeConfig     `json:"types,omitempty"`
	Instances []VGPUInstanceConfig `json:"instances,omitempty"`
	Guest     *VGPUGuestConfig     `json:"guest,omitempty"`
}

VGPUConfig is the vGPU block of a virtualized GPU.

type VGPUGuestConfig added in v0.6.0 

type VGPUGuestConfig struct {
	HostDriverVersion string             `json:"host_driver_version"`
	HostDriverBranch  string             `json:"host_driver_branch"`
	License           *VGPULicenseConfig `json:"license,omitempty"`
}

VGPUGuestConfig is what a VM learns about its host from the vGPU: the host driver, through a PCI vendor capability, and the license the guest holds.

type VGPUInstanceConfig added in v0.6.0 

type VGPUInstanceConfig struct {
	Type  string `json:"type"`
	Count int    `json:"count,omitempty"`
}

VGPUInstanceConfig asks for Count running instances of the named type. An omitted count is one instance, as in a MIG layout.

type VGPULicenseConfig added in v0.6.0 

type VGPULicenseConfig struct {
	Product string `json:"product,omitempty"`
	State   string `json:"state,omitempty"`
	Expiry  string `json:"expiry,omitempty"`
}

VGPULicenseConfig is the vGPU software license a guest holds.

func (*VGPULicenseConfig) Licensed added in v0.6.0 

func (l *VGPULicenseConfig) Licensed() bool

Licensed reports whether the guest holds its license. A license block with no state is licensed: declaring a product is the common case.

type VGPUResolution added in v0.6.0 

type VGPUResolution struct {
	Width  uint32 `json:"width"`
	Height uint32 `json:"height"`
}

VGPUResolution is a vGPU type's maximum display resolution.

type VGPUTypeConfig added in v0.6.0 

type VGPUTypeConfig struct {
	ID                   uint32          `json:"id"`
	Name                 string          `json:"name"`
	Class                string          `json:"class,omitempty"`
	FramebufferMiB       uint64          `json:"framebuffer_mib"`
	MaxInstances         uint32          `json:"max_instances"`
	MaxInstancesPerVM    uint32          `json:"max_instances_per_vm,omitempty"`
	License              string          `json:"license,omitempty"`
	NumDisplayHeads      uint32          `json:"num_display_heads,omitempty"`
	Resolution           *VGPUResolution `json:"resolution,omitempty"`
	FrameRateLimit       uint32          `json:"frame_rate_limit,omitempty"`
	GPUInstanceProfileID *uint32         `json:"gpu_instance_profile_id,omitempty"`
	// DeviceID and SubsystemID are the PCI identity the type presents to its
	// guest, encoded as in PCIConfig. Zero takes the board's.
	DeviceID    uint32 `json:"device_id,omitzero"`
	SubsystemID uint32 `json:"subsystem_id,omitzero"`
}

VGPUTypeConfig declares one vGPU type a host GPU supports. Installs name the types themselves: which a board offers depends on the vGPU software release, not on the silicon.

type VgpuInstance added in v0.6.0 

type VgpuInstance struct {
	ID   uint32
	Type VgpuType
	UUID string
	// VMID is the UUID of the VM the instance is assigned to. Every instance
	// gets a VM of its own, which is what max_instances_per_vm 1 implies.
	VMID          string
	ECCMode       nvml.EnableState
	GPUInstanceID uint32
}

VgpuInstance is one running vGPU.

func (VgpuInstance) LicenseInfo added in v0.6.0 

func (VgpuInstance) LicenseInfo() nvml.VgpuLicenseInfo

LicenseInfo reports the instance's license. A running instance is taken to be licensed: an unlicensed guest is the guest-side simulation's business.

func (VgpuInstance) VMDriverVersion added in v0.6.0 

func (VgpuInstance) VMDriverVersion() string

VMDriverVersion is the driver version the guest reports. NVML returns this string until a driver loads in the VM, and no simulated VM ever boots one.

type VgpuType added in v0.6.0 

type VgpuType struct {
	ID                   uint32
	Name                 string
	Class                string
	License              string
	FramebufferBytes     uint64
	DeviceID             uint64
	SubsystemID          uint64
	MaxInstances         uint32
	MaxInstancesPerVM    uint32
	NumDisplayHeads      uint32
	ResolutionWidth      uint32
	ResolutionHeight     uint32
	FrameRateLimit       uint32
	GPUInstanceProfileID uint32
}

VgpuType is one vGPU type as NVML reports it, optional fields resolved.

type VirtualizationConfig 

type VirtualizationConfig struct {
	Mode         string `json:"mode,omitempty"`
	HostVGPUMode string `json:"host_vgpu_mode,omitempty"`
	// VGPU carries the side of the hypervisor Mode selects: types and running
	// instances for a host (host_vgpu), the guest block for the vGPU a VM sees
	// (vgpu).
	VGPU *VGPUConfig `json:"vgpu,omitempty"`
}

VirtualizationConfig defines virtualization settings

func (*VirtualizationConfig) Guest added in v0.6.0 

func (v *VirtualizationConfig) Guest() *VGPUGuestConfig

Guest returns the guest block when the GPU is a vGPU guest, and nil otherwise — including for mode vgpu with no block, which reports the mode and nothing else.

type WorkloadPowerProfileConfig added in v0.5.0 

type WorkloadPowerProfileConfig struct {
	// ID is an NVML_POWER_PROFILE_* index (0-254), which is both the
	// semantic name nvidia-smi renders and the profile's bit position.
	ID uint32 `json:"id"`

	// Priority arbitrates between conflicting requested profiles. Lower
	// wins, matching NVML's "the lower the value, the higher the priority".
	Priority uint32 `json:"priority,omitzero"`

	// Conflicts lists profile ids that cannot be enforced alongside this
	// one.
	Conflicts []uint32 `json:"conflicts,omitempty"`
}

WorkloadPowerProfileConfig is one advertised profile.

type WorkloadPowerProfilesConfig added in v0.5.0 

type WorkloadPowerProfilesConfig struct {
	// Supported lists the profiles the device advertises. An empty list is
	// not the same as an absent WorkloadProfiles: it models a device that
	// supports the feature but exposes no profile.
	Supported []WorkloadPowerProfileConfig `json:"supported,omitempty"`

	// Requested holds the profile ids asked for. Real hardware with nothing
	// requested reports N/A for both the requested and the enforced mask, so
	// this defaults to empty rather than preselecting a profile.
	Requested []uint32 `json:"requested,omitempty"`
}

WorkloadPowerProfilesConfig models the pre-tuned performance/power recipes Blackwell exposes through `nvidia-smi power-profiles`.

type XidErrorConfig added in v0.2.0 

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

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 describes the root-complex / NUMA layout consumed by the
	// pcibus simulator and the engine for NVLink topology, pairwise PCIe
	// levels, and CPU/NUMA affinity. 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.