topo

Documentation

Index

• Variables
• type Advice
  • func Rate(m *Matrix) []Advice
• type Cell
• type LinkType
• type Matrix
  • func Parse(raw []byte) (*Matrix, error)
• type NICAffinity
• type Rating
• type Result
  • func Collect(ctx context.Context, runner execRunner, smiPath string) (*Result, error)

Variables

var ErrToolNotInstalled = errors.New("nvidia-smi not installed")

ErrToolNotInstalled is returned when nvidia-smi cannot be located on PATH.

Types

type Advice

type Advice struct {
	GPU    string
	NIC    string
	Link   LinkType
	Rating Rating
}

Advice is a single GPU-NIC affinity assessment.

func Rate

func Rate(m *Matrix) []Advice

Rate assesses every GPU-NIC pair, skipping self (X/SELF) and NVLink links. PIX/PXB rate good, PHB/NODE rate warn, and SYS rates bad. Results are ordered by NIC then GPU for determinism.

type Cell

type Cell struct {
	Type  LinkType
	Lanes int
}

Cell is a single entry of the connectivity matrix. Lanes is populated only for NVLINK links (e.g. NV12 -> Lanes 12); it is 0 for every other link type.

type LinkType

type LinkType string

LinkType classifies the interconnect between two endpoints in the topology matrix produced by `nvidia-smi topo -m`.

const (
	LinkNVLink LinkType = "NVLINK"
	LinkPIX    LinkType = "PIX"
	LinkPXB    LinkType = "PXB"
	LinkPHB    LinkType = "PHB"
	LinkNODE   LinkType = "NODE"
	LinkSYS    LinkType = "SYS"
	LinkSelf   LinkType = "SELF"
	LinkX      LinkType = "X"
)

type Matrix

type Matrix struct {
	GPUs  []string
	Cells map[string]map[string]Cell
	NICs  []NICAffinity
}

Matrix is the structured form of the topology matrix: the GPU-to-GPU cell grid plus per-NIC GPU affinity rows.

func Parse

func Parse(raw []byte) (*Matrix, error)

Parse converts raw `nvidia-smi topo -m` output into a Matrix. Columns are located by their header labels (GPU#/NIC#), not by fixed widths; the "CPU Affinity"/"NUMA Affinity" columns and any Legend block are ignored. A missing or unparseable matrix returns an error rather than a partial result.

type NICAffinity

type NICAffinity struct {
	NIC    string
	PerGPU map[string]Cell
}

NICAffinity captures how a single NIC connects to every GPU on the host.

type Rating

type Rating string

Rating summarizes how favorable a GPU-NIC link is.

const (
	RatingGood Rating = "good" // PIX / PXB
	RatingWarn Rating = "warn" // PHB / NODE
	RatingBad  Rating = "bad"  // SYS
)

type Result

type Result struct {
	Matrix Matrix
	Advice []Advice
}

Result bundles the parsed matrix with the derived affinity advice.

func Collect

func Collect(ctx context.Context, runner execRunner, smiPath string) (*Result, error)

Collect resolves nvidia-smi, runs `nvidia-smi topo -m`, and parses the result into a structured Matrix plus affinity advice. When smiPath is empty it resolves nvidia-smi via PATH; a failed lookup wraps ErrToolNotInstalled.