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
- type Device
- type Network
- type Options
- type P9Directory
- type ReadOnlyDirectory
- 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) 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
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
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 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.
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.
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
}
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) CmdlineQuoted ¶
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 ¶
Expect returns an error if the given string is not found in vEMU's serial output within `DefaultTimeout`.
func (*VM) ExpectRE ¶
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 ¶
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 ¶
ExpectTimeout returns an error if the given string is not found in vEMU's serial output within the given timeout.
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