vfio

Documentation

Overview

Package vfio is the runtime attach interface for VFIO PCI passthrough (GPU, NIC, NVMe). Attach is runtime-only — devices don't persist past VM stop; host IOMMU + vfio-pci binding are the user's job.

Index

• Constants
• Variables
• func NormalizePath(input string) (string, error)
• type Attached
• type Attacher
• type Lister
• type Spec
  • func (s *Spec) NormalizedPath() (string, error)

Constants

const SysfsPCIPrefix = "/sys/bus/pci/devices/"

SysfsPCIPrefix is the canonical host path for a PCI device.

Variables

var (

	// ErrUnsupportedBackend signals the resolved hypervisor backend cannot
	// hot-plug VFIO devices (e.g. Firecracker).
	ErrUnsupportedBackend = errors.New("backend does not support device attach")
)

Functions

func NormalizePath

func NormalizePath(input string) (string, error)

NormalizePath maps {short BDF, full BDF, sysfs path} → canonical /sys/bus/pci/devices/<bdf>; rejects paths outside that root.

Types

type Attached

type Attached struct {
	ID  string `json:"id"`
	BDF string `json:"bdf,omitempty"`
}

Attached is the inspect-time view of one VFIO device from running VM state.

type Attacher

type Attacher interface {
	DeviceAttach(ctx context.Context, vmRef string, spec Spec) (deviceID string, err error)
	DeviceDetach(ctx context.Context, vmRef, id string) error
}

Attacher hot-plugs and removes VFIO PCI passthrough devices.

type Lister

type Lister interface {
	DeviceList(ctx context.Context, vmRef string) ([]Attached, error)
}

Lister enumerates VFIO devices from running VM state.

type Spec

type Spec struct {
	PCI string
	ID  string
}

Spec is one attach request. PCI may be a short BDF, full BDF, or a sysfs path; NormalizePath canonicalizes it.

func (*Spec) NormalizedPath

func (s *Spec) NormalizedPath() (string, error)

NormalizedPath validates the spec and returns the canonical sysfs path; existence is checked at attach time.