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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Global ¶
Global describes a global configuration property for a QEMU driver.
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 \
type Option ¶
type Option struct {
Type string
Parameters Parameters
}
Option is an option for a QEMU virtual machine.
For an option to be valid, it must have a type. Parameters are optional.
type Options ¶
type 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
func (*Options) Add ¶
Add adds an option with the given type and parameters.
If type is empty the property is not added.
type Parameters ¶
type Parameters []Parameter
Parameters hold a set of parameters for a QEMU virtual machine option.
func (*Parameters) Add ¶
func (params *Parameters) Add(name, value string)
Add adds a named parameter with the give name and value.
If name and value are both empty the property is not added.
func (*Parameters) AddValue ¶
func (params *Parameters) AddValue(value string)
AddValue adds a property with the given value but no name.
If value is empty the property is not added.
func (Parameters) String ¶
func (params Parameters) String() string
String returns a string representation of the properties in the form expected by QEMU options.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package qdev describes PCI Express device topologies of a QEMU guest.
|
Package qdev describes PCI Express device topologies of a QEMU guest. |
|
Package qguest describes non-device properties of a QEMU guest.
|
Package qguest describes non-device properties of a QEMU guest. |
|
Package qhost identifies and describes host resources that are contributed to a QEMU guest.
|
Package qhost identifies and describes host resources that are contributed to a QEMU guest. |
|
blockdev
Package blockdev articulates the QEMU block layer.
|
Package blockdev articulates the QEMU block layer. |
|
chardev
Package chardev describes the QEMU character device layer.
|
Package chardev describes the QEMU character device layer. |
|
tpmdev
Package tpmdev describes real and emulated Trusted Platform Module devices on the host.
|
Package tpmdev describes real and emulated Trusted Platform Module devices on the host. |