A VM configuration file is a human-readable, plain-text file.
When you start a qvm process to create a VM and run a guest, the qvm process reads the configuration information to the end to know how to assemble and configure the VM.
General rules are:
The rules for options are:
An option may affect contexts in one of the following ways:
See “Contexts” below.
An argument must:
When the qvm process reads through its configuration file (from top to bottom) to assemble the components of the VM it is creating, everything that follows an option that establishes a context is in this option's context. All further options apply to this option, until either a new option that establishes a context is encountered, or the end of file is reached.
For example, in the following snippet each sched option applies to the preceding cpu option:
cpu
sched 8 ram 32m
cpu
sched 6
Since cpu establishes a context, the context changes each time this option is encountered; what follows each cpu entry will either apply to that option, or create a new context.
If an option is repeated in a context, the qvm process uses the last instance of the option in that context. For example:
cpu sched 8 cpu sched 6
creates one vCPU with scheduling priority 8, and one vCPU with scheduling priority 6. However, the following:
cpu sched 8 sched 6 cpu
creates one vCPU with scheduling priority 6 (sched 8 is discarded), and one vCPU with the default scheduling priority (i.e., the scheduling priority at which the qvm process instance was started).
The order of the different options that follow the cpu option isn't significant, though. For example:
cpu sched 8 ram 32m
is equivalent to:
cpu ram 32m sched 8
There are some exceptions to the above rule that option sequence isn't important. These exceptions apply to the following components:
Memory must be allocated before any option specifying a component that will use the memory: the ram and rom options must be specified before any options that refer to the guest memory. For example:
ram 32m load /qnx7.ifs
is valid because the ram 32m has allocated 32 MB, into which the qvm process can load the IFS file. However, the following will fail:
load /qnx7.ifs ram 32m
because no memory has been allocated, so the qvm process has nowhere to load the IFS file.
vdevs for Programmable Interrupt Controllers (PICs) must be specified before any other vdevs that reference them. For example:
vdev ioapic
loc 0xf8000000
intr apic
name myioapic
vdev ser8250
intr myioapic:4
is valid because vdev ioapic is specified before vdev ser8250, which references it. However, the following will fail:
vdev ser8250
intr myioapic:4
vdev ioapic
loc 0xf8000000
intr apic
name myioapicr
because vdev ser8250 references vdev ioapic before this vdev has been specified.
As it reads through its configuration information, a qvm process instance performs textual substitutions when it encounters the following character sequences:
You can use this textual substitution to make your configuration more robust. For example, you can pass a region of memory to the guest without specifying the host address for the memory in the VM configuration, as follows:
Use textual substitution to place the information from the system page asinfo entry called guestmem1 into the qvm configuration:
pass loc 0x10000000,$asinfo_length{guestmem1},rw=$asinfo_start{guestmem1}
With this configuration, no matter where the reserved memory actually ends up in the host, the configuration will work.
Similarly, you can use $env to put parameters in a configuration file. For example, with the following in a qvm configuration file (e.g., myconfig.qvmconf):
vdev ser8250 hostdev $env{HOST_DEV}
you could then set the vdev ser8250 hostdev option to whatever value you enter for HOST_DEV, then start the qvm process instance, as follows:
export HOST_DEV=/dev/ser3 qvm @myconfig.qvmconf
Note that when using $asinfo_start, pass the leaf name only, and not the full path. For example, the following is incorrect:
pass
loc 0x10000000,$asinfo_length{guestmem1},rw=$asinfo_start{/foo/guestmem1}
but the following is correct:
pass
loc 0x10000000,$asinfo_length{guestmem1},rw=$asinfo_start{guestmem1}
For more information about the system page asinfo data structure array, see the “System Page ” chapter in Building Embedded Systems.
The default notations (no prefix needed) for specifying memory addresses and sizes are:
If you prefer to write a memory address or region size with a notation other than the default, you can use a prefix to specify the notation:
You can use size multipliers: “K”, “M”, “G” (or “k”, “m”, “g”) in the address and length arguments; for example: 4K,1k is equivalent to 0x1000,0x400. (Remember: the size multipliers are decimal multipliers, so 4K is 4 x 1024 = 4096, or 0x1000.)