topo

package

v1.1.0 Latest Latest Go to latest Published: Jul 14, 2026 License: MIT Imports: 7 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/sunerpy/gpu-tools

Links

Open Source Insights

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)

Constants ¶

This section is empty.

Variables ¶

View Source

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

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

Functions ¶

This section is empty.

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.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL