qemu

Documentation

Overview

Package qemu provides fundamental types for describing options to QEMU. QEMU is the Quick Emulator, a userspace program that manages kernel virtual machines within the Linux kernel.

Specific QEMU options can be found in the subpackages. QEMU supports an enormous number of options. These subpackages supply only a subset of the possible QEMU options. Some options have not been implemented yet, and some options will not be implemented because their use has been deprecated or otherwise discouraged.

PCI Express devices presented to the guest are defined in the qdev package. Each device is identified by a unique qdev.ID, and is backed by a corresponding QEMU device driver supplied by QEMU. Devices are organized into a qdev.Topology that captures the entire PCI Express device tree of the guest.

In order for a guest to operate, it relies on resources contributed by the host, such as disk image files and network taps. Host resources are defined in the qhost package.

Block devices that supply persistent storage are organized by QEMU into node graphs. Node graphs describe the processing path of I/O requests through one or more block device drivers. Block devices are defined in the qhost/blockdev package.

Various guest configuration options that can be used by QEMU are defined in the qguest package.

For convenience, all of the settings necessary to describe a QEMU virtual machine can be captured by the qvm package in a qvm.Definition.

Example

package main

import (
	"fmt"

	"github.com/gentlemanautomaton/machina/qemu/qguest"
	"github.com/gentlemanautomaton/machina/qemu/qhost"
	"github.com/gentlemanautomaton/machina/qemu/qhost/blockdev"
	"github.com/gentlemanautomaton/machina/qemu/qvm"
	"github.com/google/uuid"
)

func main() {
	// Prepare a QEMU virtual machine definition
	var vm qvm.Definition

	// Specify some basic settings for the guest
	vm.Settings = qguest.Settings{
		Identity: qguest.Identity{
			Name: "test-machine",
			ID:   uuid.MustParse("{00000000-0000-0000-0000-000000000001}"),
		},
		Processor: qguest.Processor{
			Sockets: 1,
			Cores:   24,
		},
		Memory: qguest.Memory{
			Allocation: qguest.GB(2),
		},
	}

	// Add a network controller with a network tap on kvmbr0
	{
		tap, err := vm.Resources.AddNetworkTap(
			"kvmbr0",
			qhost.Script("/etc/qemu/if-up.sh"),
			qhost.Script("/etc/qemu/if-down.sh"),
		)
		if err != nil {
			panic(err)
		}

		root, err := vm.Topology.AddRoot()
		if err != nil {
			panic(err)
		}

		if _, err := root.AddVirtioNetwork("00:00:00:00:00:00", tap); err != nil {
			panic(err)
		}
	}

	// Add an OS storage volume as a Virtio SCSI disk backed by a raw format
	// disk image in the home directory
	{
		graph := vm.Resources.BlockDevs()
		name := blockdev.NodeName("test-os")

		// Add a file node to the block device graph
		file, err := blockdev.File{
			Name: name.Child("file"), // Derive a unique node name
			Path: blockdev.FilePath("~/test-os.raw"),
		}.Connect(graph)
		if err != nil {
			panic(err)
		}

		// Add a raw format node to the block device graph that connects
		// to the file node we just created
		disk, err := blockdev.Raw{Name: name}.Connect(file)
		if err != nil {
			panic(err)
		}

		// Add an iothread that will be used by the SCSI Controller
		iothread, err := vm.Resources.AddIOThread()
		if err != nil {
			panic(err)
		}

		// Add a root port for the SCSI controller
		root, err := vm.Topology.AddRoot()
		if err != nil {
			panic(err)
		}

		// Connect the SCSI controller to the root port
		scsi, err := root.AddVirtioSCSI(iothread)
		if err != nil {
			panic(err)
		}

		// Add a SCSI disk to the controller that is backed by the format node
		// we prepared earlier
		if _, err := scsi.AddDisk(disk); err != nil {
			panic(err)
		}
	}

	// Print each option on its own line
	for _, opt := range vm.Options() {
		fmt.Printf("%s \\\n", opt)
	}

}

Output:

-uuid 00000000-0000-0000-0000-000000000001 \
-name test-machine \
-enable-kvm \
-nodefaults \
-nographic \
-machine type=q35 \
-cpu host \
-smp sockets=1,cores=24 \
-m size=2G \
-boot menu=on,reboot-timeout=5000 \
-object iothread,id=iothread.0 \
-blockdev driver=file,node-name=test-os-file,filename=~/test-os.raw \
-blockdev driver=raw,node-name=test-os,file=test-os-file \
-netdev tap,id=net.0,ifname=kvmbr0,script=/etc/qemu/if-up.sh,downscript=/etc/qemu/if-down.sh \
-device ioh3420,id=pcie.1.0,chassis=0,bus=pcie.0,addr=1.0,multifunction=on \
-device virtio-net-pci,bus=pcie.1.0,mac=00:00:00:00:00:00,netdev=net.0 \
-device ioh3420,id=pcie.1.1,chassis=1,bus=pcie.0,addr=1.1 \
-device virtio-scsi-pci,id=scsi,bus=pcie.1.1,iothread=iothread.0,num_queues=4 \
-device scsi-hd,id=scsi.0.0,bus=scsi.0,channel=0,scsi-id=0,lun=0,drive=test-os \

Index

• type Global
  • func (g Global) Option() Option
  • func (g Global) Valid() bool
• type Globals
  • func (globals *Globals) Add(driver, property, value string)
  • func (globals Globals) Options() Options
• type Option
  • func (opt Option) Prefix() string
  • func (opt Option) String() string
• type Options
• type Parameter
• type Parameters

Examples

• Package
• Globals
• Options

Types

type Global

type Global struct {
	Driver   string
	Property string
	Value    string
}

Global describes a global configuration property for a QEMU driver.

func (Global) Option

func (g Global) Option() Option

Option returns the global property as a QEMU option.

func (Global) Valid

func (g Global) Valid() bool

Valid returns true if the global has a driver and property. It does not evaluate the semantic meaning and correctness of the global.

type Globals

type Globals []Global

Globals holds a set of global configuration properties for QEMU drivers.

Example

package main

import (
	"fmt"

	"github.com/gentlemanautomaton/machina/qemu"
)

func main() {
	// Prepare a set of globals
	globals := qemu.Globals{
		{Driver: "kvm-pit", Property: "lost_tick_policy", Value: "discard"},
	}
	globals.Add("cfi.pflash01", "secure", "on")
	globals.Add("qxl-vga", "ram_size", "67108864")

	// Print each option on its own line
	for _, opt := range globals.Options() {
		fmt.Printf("%s \\\n", opt)
	}

}

Output:

-global driver=kvm-pit,property=lost_tick_policy,value=discard \
-global driver=cfi.pflash01,property=secure,value=on \
-global driver=qxl-vga,property=ram_size,value=67108864 \

func (*Globals) Add

func (globals *Globals) Add(driver, property, value string)

Add adds a global configuration property with the given driver, property and value.

If driver or property are empty the global is not added.

func (Globals) Options

func (globals Globals) Options() Options

Options returns a set of QEMU virtual machine options that implement the global driver properties.

type Option

type Option commandoption.Data

Option is an option for a QEMU virtual machine.

For an option to be valid, it must have a type. Parameters are optional.

func (Option) Prefix

func (opt Option) Prefix() string

Prefix returns the option prefix used by QEMU, which is a single dash character "-".

func (Option) String

func (opt Option) String() string

String returns a string representation of the option.

It returns an empty string if the option lacks a type.

type Options

type Options = commandoption.Options[Option]

Options holds a set of configuration options for a QEMU virtual machine.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/gentlemanautomaton/machina/qemu"
)

func main() {
	opts := qemu.Options{
		{Type: "name", Parameters: qemu.Parameters{{Value: "test"}}},
		{Type: "machine", Parameters: qemu.Parameters{{Value: "q35"}}},
		{Type: "m", Parameters: qemu.Parameters{{Name: "size", Value: "2GB"}}},
		{Type: "smp", Parameters: qemu.Parameters{
			{Name: "sockets", Value: "1"},
			{Name: "cores", Value: "4"},
		}},
	}
	fmt.Print(strings.Join(opts.Args(), " "))

}

Output:

-name test -machine q35 -m size=2GB -smp sockets=1,cores=4

type Parameter

type Parameter = commandoption.Parameter

Parameter describes a parameter for a QEMU virtual machine option.

type Parameters

type Parameters = commandoption.Parameters

Parameters hold a set of parameters for a QEMU virtual machine option.