vfio

Documentation

Overview

Package vfio is the runtime attach interface for VFIO PCI passthrough devices on a running VM. Typical use cases: GPU, NIC, NVMe.

State semantics: attach is runtime-only. Attached devices are not persisted in the VM record and disappear when the VM stops. Host-side IOMMU enablement and vfio-pci driver binding are the user's responsibility.

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 any of {01:00.0, 0000:01:00.0, /sys/bus/pci/devices/<bdf>} into the canonical sysfs path that CH's vm.add-device expects. Absolute paths must live under /sys/bus/pci/devices/ with a valid BDF suffix — accepting an arbitrary host path would let cocoon hand CH a non-PCI directory.

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 (NormalizePath already covers PCI shape validation, so callers do not need a separate Validate()). Path existence is asserted by the backend right before calling CH; the host file may be removed between CLI parse and the API call.