hypervisor

type BootConfig struct {
	KernelPath string
	KernelArgs string
	InitrdPath string
}

type CPUAffinity struct {
	VCPU     int
	HostCPUs []int
}

type CPUConfig struct {
	Count    int
	MaxCount int
	Topology *CPUTopology
	Affinity []CPUAffinity
}

type CPUTopology struct {
	ThreadsPerCore int
	CoresPerDie    int
	DiesPerPackage int
	Packages       int
}

type Capabilities struct {
	// SupportsSnapshot reports whether SnapshotVM and Starter.RestoreVM work.
	SupportsSnapshot bool

	// SupportsHotplugMemory reports whether ResizeVMMemory works.
	SupportsHotplugMemory bool

	// SupportsHotplugCPU reports whether ResizeVMCPU works.
	SupportsHotplugCPU bool

	// SupportsCPUAffinity reports whether vCPUs can be pinned to host CPUs.
	SupportsCPUAffinity bool

	// SupportsPause reports whether PauseVM and ResumeVM work.
	SupportsPause bool

	// SupportsVsock reports whether the guest can have a vsock device.
	SupportsVsock bool

	// SupportsGPUPassthrough reports whether host PCI devices, GPUs among
	// them, can be passed through to the guest.
	SupportsGPUPassthrough bool

	// SupportsDiskRateLimit reports whether a disk's reads and writes can
	// be rate limited.
	SupportsDiskRateLimit bool
}

type ConsoleConfig struct {
	// Path is the file the console's output is appended to.
	Path string
}

type DiskConfig struct {
	Path     string
	ReadOnly bool

	// RateLimitBytesPerSecond and RateLimitIOPS limit the bytes and the
	// operations per second the disk is read and written at, together. Zero
	// is unlimited.
	RateLimitBytesPerSecond int64
	RateLimitIOPS           int64
}

type FilesystemConfig struct {
	Tag    string
	Socket string
}

type GPUConfig struct {
	// Profile is the vGPU profile's name, such as nvidia-35.
	Profile string

	// MediatedDeviceUUID is the mediated device's UUID.
	MediatedDeviceUUID string
}

type Hypervisor interface {
	// DestroyVM immediately and forcefully destroys the guest without sending
	// any ACPI signal. Use ShutdownVM for a graceful guest shutdown instead.
	DestroyVM(ctx context.Context) error

	// ShutdownVM sends an ACPI power-off signal to the guest OS, allowing it
	// to shut down gracefully. The VMM process remains running afterwards.
	ShutdownVM(ctx context.Context) error

	// Shutdown stops the VMM process itself.
	Shutdown(ctx context.Context) error

	// VMInfo returns the VM's state and memory.
	VMInfo(ctx context.Context) (*VMInfo, error)

	// PauseVM halts the vCPUs; ResumeVM continues them.
	PauseVM(ctx context.Context) error
	ResumeVM(ctx context.Context) error

	// SnapshotVM writes the VM's state, its memory included, into the
	// directory destPath. The VM must be paused. Writing a large guest's
	// memory can take minutes: ctx should have a deadline to suit. It fails
	// with ErrRestoringMemory if the VM was restored moments ago and its
	// memory is still being restored.
	SnapshotVM(ctx context.Context, destPath string) error

	// ResizeVMMemory sets the guest's memory, from the memory it booted with
	// up to that and MemoryConfig.HotplugBytes, in steps of
	// MemoryResizeStep; another size is refused with
	// errdefs.ErrInvalidArgument, before anything changes. Where the
	// hypervisor can tell, it returns once the guest has taken or given up
	// the memory, or ctx is done.
	ResizeVMMemory(ctx context.Context, bytes int64) error

	// ResizeVMCPU sets the guest's vCPUs, up to CPUConfig.MaxCount.
	ResizeVMCPU(ctx context.Context, count int) error
}

type MemoryConfig struct {
	SizeBytes int64

	// HotplugBytes is how much more memory ResizeVMMemory can give the
	// guest. Zero sets none aside.
	HotplugBytes int64
}

type NetworkInterfaceConfig struct {
	TAPDevice string
	MAC       string
	IP        string
	Netmask   string
	MTU       int
}

type PCIDeviceConfig struct {
	Path string
}

type RestoreSpec struct {
	// Console is where the guest's serial console is written.
	Console ConsoleConfig

	// TAPDevice is the host's end of the guest's network interface, in place
	// of the one it was snapshotted with, which another VM may have.
	TAPDevice string
}

type Starter interface {
	// Version returns the hypervisor binary version string (e.g. "v53.0.0").
	Version() string

	// DefaultKernelArgs returns the kernel arguments this hypervisor needs
	// the guest booted with, such as its console device and what a panic
	// does. They are used when the instance sets no kernel arguments of its
	// own.
	DefaultKernelArgs() string

	// PowerOffEndsVM reports whether a guest powering off ends the VMM. If
	// not, the guest resets instead, which DefaultKernelArgs makes end it.
	PowerOffEndsVM() bool

	// StartVM launches a VMM and boots the virtual machine with the given
	// configuration. The returned process is the VMM; the caller owns it from
	// then on.
	StartVM(ctx context.Context, socketPath string, spec VMSpec) (vmm *process.Process, hypervisor Hypervisor, err error)

	// RestoreVM launches a VMM and restores the VM from the snapshot
	// SnapshotVM wrote into the directory snapshotPath, leaving it paused,
	// with what spec gives it in place of what the snapshot holds. As with
	// SnapshotVM, ctx should have a deadline that suits the guest's memory.
	//
	// It may return before all of the guest's memory is restored. The VMM
	// keeps the snapshot's memory file open and restores from it while the
	// guest runs, so the file may be deleted, but must not be changed.
	RestoreVM(
		ctx context.Context, socketPath string, snapshotPath string, spec RestoreSpec,
	) (vmm *process.Process, hypervisor Hypervisor, err error)

	// Connect returns a Hypervisor for a VMM already serving its API on
	// socketPath, such as one started before the daemon restarted.
	Connect(socketPath string) (Hypervisor, error)

	// Capabilities reports which of the optional operations the hypervisor
	// supports on this host.
	Capabilities() Capabilities
}

type Type string

type VMInfo struct {
	State       VMState `json:"state"`
	MemoryBytes *int64  `json:"memory_bytes,omitempty"`
}

type VMSpec struct {
	Boot   BootConfig
	CPU    CPUConfig
	Memory MemoryConfig
	Disks  []DiskConfig
	// Filesystems are host directories shared over virtio-fs.
	Filesystems       []FilesystemConfig
	PCIDevices        []PCIDeviceConfig
	NetworkInterfaces []NetworkInterfaceConfig
	Console           ConsoleConfig
	Vsock             *VsockConfig
	GPU               *GPUConfig
}

type VMState string

type VsockConfig struct {
	CID uint32

	// SocketPath is the Unix socket the VMM proxies the device through.
	SocketPath string
}