qemu

Documentation

Overview

Package qemu provides a Go API for starting QEMU VMs.

qemu is mainly suitable for running QEMU-based integration tests.

The environment variable `UROOT_QEMU` overrides the path to QEMU and the first few arguments (defaults to "qemu"). For example, I use:

UROOT_QEMU='qemu-system-x86_64 -L . -m 4096 -enable-kvm'

For CI, this environment variable is set in `.circleci/images/integration/Dockerfile`.

Index

• Variables
• type ArbitraryArgs
  • func (aa ArbitraryArgs) Cmdline() []string
  • func (ArbitraryArgs) KArgs() []string
• type Device
• type IDEBlockDevice
  • func (ibd IDEBlockDevice) Cmdline() []string
  • func (IDEBlockDevice) KArgs() []string
• type Network
  • func NewNetwork() *Network
  • func (n *Network) NewVM(nopts ...NetworkOpt) Device
• type NetworkOpt
  • func WithPCAP(outputFile string) NetworkOpt
• type Options
  • func (o *Options) Cmdline() ([]string, error)
  • func (o *Options) Start() (*VM, error)
• type P9Directory
  • func (p P9Directory) Cmdline() []string
  • func (p P9Directory) KArgs() []string
• type ReadOnlyDirectory
  • func (rod ReadOnlyDirectory) Cmdline() []string
  • func (ReadOnlyDirectory) KArgs() []string
• type VM
  • func (v *VM) Close()
  • func (v *VM) Cmdline() []string
  • func (v *VM) CmdlineQuoted() string
  • func (v *VM) Expect(search string) error
  • func (v *VM) ExpectBatch(batch []expect.Batcher, timeout time.Duration) ([]expect.BatchRes, error)
  • func (v *VM) ExpectRE(pattern *regexp.Regexp) (string, error)
  • func (v *VM) ExpectRETimeout(pattern *regexp.Regexp, timeout time.Duration) (string, error)
  • func (v *VM) ExpectTimeout(search string, timeout time.Duration) error
  • func (v *VM) Send(in string)
  • func (v *VM) TimeoutOr() time.Duration
  • func (v *VM) Wait() error
• type VirtioRandom
  • func (VirtioRandom) Cmdline() []string
  • func (VirtioRandom) KArgs() []string

Variables

var DefaultTimeout = 7 * time.Second

DefaultTimeout for `Expect` and `ExpectRE` functions.

var TimeoutMultiplier = 1.0

TimeoutMultiplier increases all timeouts proportionally. Useful when running QEMU on a slow machine.

Types

type ArbitraryArgs

type ArbitraryArgs []string

ArbitraryArgs is a Device that allows users to add arbitrary arguments to the QEMU command line.

func (ArbitraryArgs) Cmdline

func (aa ArbitraryArgs) Cmdline() []string

func (ArbitraryArgs) KArgs

func (ArbitraryArgs) KArgs() []string

type Device

type Device interface {
	// Cmdline returns arguments to append to the QEMU command line for this device.
	Cmdline() []string
	// KArgs returns arguments that must be passed to the kernel for this device, or nil.
	KArgs() []string
}

Device is a QEMU device to expose to a VM.

type IDEBlockDevice

type IDEBlockDevice struct {
	File string
}

IDEBlockDevice emulates an AHCI/IDE block device.

func (IDEBlockDevice) Cmdline

func (ibd IDEBlockDevice) Cmdline() []string

func (IDEBlockDevice) KArgs

func (IDEBlockDevice) KArgs() []string

type Network

type Network struct {
	// contains filtered or unexported fields
}

Network is a Device that can connect multiple QEMU VMs to each other.

Network uses the QEMU socket mechanism to connect multiple VMs with a simple TCP socket.

func NewNetwork

func NewNetwork() *Network

NewNetwork creates a new QEMU network between QEMU VMs.

The network is closed from the world and only between the QEMU VMs.

func (*Network) NewVM

func (n *Network) NewVM(nopts ...NetworkOpt) Device

NewVM returns a Device that can be used with a new QEMU VM.

type NetworkOpt

type NetworkOpt func(netdev string) []string

NetworkOpt returns additional QEMU command-line parameters based on the net device ID.

func WithPCAP

func WithPCAP(outputFile string) NetworkOpt

WithPCAP captures network traffic and saves it to outputFile.

type Options

type Options struct {
	// QEMUPath is the path to the QEMU binary to invoke.
	//
	// If left unspecified, the UROOT_QEMU env var will be used.
	// If the env var is unspecified, "qemu" is the default.
	QEMUPath string

	// Path to the kernel to boot.
	Kernel string

	// Path to the initramfs.
	Initramfs string

	// Extra kernel command-line arguments.
	KernelArgs string

	// Where to send serial output.
	SerialOutput io.WriteCloser

	// Timeout is the expect timeout.
	Timeout time.Duration

	// Devices are devices to expose to the QEMU VM.
	Devices []Device
}

Options are VM start-up parameters.

func (*Options) Cmdline

func (o *Options) Cmdline() ([]string, error)

Cmdline returns the command line arguments used to start QEMU. These arguments are derived from the given QEMU struct.

func (*Options) Start

func (o *Options) Start() (*VM, error)

Start starts a QEMU VM.

type P9Directory

type P9Directory struct {
	// Dir is the directory to expose as read-write 9p filesystem.
	Dir string

	// Boot: if true, indicates this is the root volume. For this to work,
	// kernel args will need to be added - use KArgs() to get the args. There
	// can only be one boot 9pfs at a time.
	Boot bool

	// Tag is an identifier that is used within the VM when mounting an fs,
	// e.g. 'mount -t 9p my-vol-ident mountpoint'. If not specified, a default
	// tag of 'tmpdir' will be used.
	//
	// Ignored if Boot is true, as the tag in that case is special.
	//
	// For non-boot devices, this is also used as the id linking the `-fsdev`
	// and `-device` args together.
	//
	// Because the tag must be unique for each dir, if multiple non-boot
	// P9Directory's are used, tag may be omitted for no more than one.
	Tag string

	// Arch is the architecture under test. This is used to determine the
	// QEMU command line args.
	Arch string
}

P9Directory is a Device that exposes a directory as a Plan9 (9p) read-write filesystem in the VM.

func (P9Directory) Cmdline

func (p P9Directory) Cmdline() []string

func (P9Directory) KArgs

func (p P9Directory) KArgs() []string

type ReadOnlyDirectory

type ReadOnlyDirectory struct {
	// Dir is the directory to expose as a read-only vfat partition.
	Dir string
}

ReadOnlyDirectory is a Device that exposes a directory as a /dev/sda1 readonly vfat partition in the VM.

func (ReadOnlyDirectory) Cmdline

func (rod ReadOnlyDirectory) Cmdline() []string

func (ReadOnlyDirectory) KArgs

func (ReadOnlyDirectory) KArgs() []string

type VM

type VM struct {
	Options *Options
	// contains filtered or unexported fields
}

VM is a running QEMU virtual machine.

func (*VM) Close

func (v *VM) Close()

Close stops QEMU.

func (*VM) Cmdline

func (v *VM) Cmdline() []string

Cmdline is the command-line the VM was started with.

func (*VM) CmdlineQuoted

func (v *VM) CmdlineQuoted() string

CmdlineQuoted quotes any of QEMU's command line arguments containing a space so it is easy to copy-n-paste into a shell for debugging.

func (*VM) Expect

func (v *VM) Expect(search string) error

Expect returns an error if the given string is not found in vEMU's serial output within `DefaultTimeout`.

func (*VM) ExpectBatch

func (v *VM) ExpectBatch(batch []expect.Batcher, timeout time.Duration) ([]expect.BatchRes, error)

ExpectBatch matches many regular expressions.

func (*VM) ExpectRE

func (v *VM) ExpectRE(pattern *regexp.Regexp) (string, error)

ExpectRE returns an error if the given regular expression is not found in vEMU's serial output within `DefaultTimeout`. The matched string is returned.

func (*VM) ExpectRETimeout

func (v *VM) ExpectRETimeout(pattern *regexp.Regexp, timeout time.Duration) (string, error)

ExpectRETimeout returns an error if the given regular expression is not found in vEMU's serial output within the given timeout. The matched string is returned.

func (*VM) ExpectTimeout

func (v *VM) ExpectTimeout(search string, timeout time.Duration) error

ExpectTimeout returns an error if the given string is not found in vEMU's serial output within the given timeout.

func (*VM) Send

func (v *VM) Send(in string)

Send sends a string to QEMU's serial.

func (*VM) TimeoutOr

func (v *VM) TimeoutOr() time.Duration

func (*VM) Wait

func (v *VM) Wait() error

Wait waits for the VM to exit.

type VirtioRandom

type VirtioRandom struct{}

VirtioRandom is a Device that exposes a PCI random number generator to the QEMU VM.

func (VirtioRandom) Cmdline

func (VirtioRandom) Cmdline() []string

func (VirtioRandom) KArgs

func (VirtioRandom) KArgs() []string