VM configuration syntax

When you start a qvm process to create a VM and run a guest, the qvm process reads the entire configuration information to know how to assemble and configure the VM.

General rules are:

Everything that follows a number sign (#) in a line is a comment and is ignored, as are blank lines.
Entries (other than comments) in a qvm configuration are either options or arguments.

Rules for options

The rules for options are:

An option may affect contexts in one of the following ways:
- The option establishes a context in which other options can be set; for example, the vdev option establishes a context in which a virtual device is defined through other options.
- The option applies to a context; for example, the sched option following a cpu option applies to the current context established by the cpu option, thus sched contributes to the definition of the vCPU specified by cpu.
- The option neither establishes a context nor applies to a context; for example, the ram option supports arguments setting the location and size of the memory allocated, but it supports no options.
For more details, see Contexts below.
Options that don't apply to a context specify a component to be included in the VM. For example, cpu instructs the qvm process to create a virtual CPU, and load /vm/images/qnx8.ifs instructs it to copy the contents of /vm/images/qnx8.ifs into the guest system address space.
There is no default value for an unspecified option.
Most (but not all) options require one argument (see Rules for arguments below, and the entries for individual options in the VM Configuration Reference chapter).
In general, option sequence isn't important. It doesn't matter in which order you define vdevs, for instance (but see Exceptions below).

Rules for arguments

An argument must:

immediately follow the option to which it applies
be in the same file as the option to which it applies

Contexts

When the qvm process reads through its configuration file to assemble 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. Essentially, a context is a block in the configuration file that groups together related options.

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 either applies to that option or creates 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

Note:

The line breaks are to improve human readability and are ignored by the qvm process when it parses the configuration file.

Exceptions

There are some exceptions to the above rule that option sequence isn't important. These exceptions apply to the following components:

system

If the system option is specified, it must be the first entry in a qvm configuration (see system in the VM Configuration Reference chapter).

ram

Memory must be allocated before any option specifying a component that will use the memory. Thus, the ram and rom options must be specified before any options that refer to the guest memory. For example:

ram 32m
load /qnx8.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 /qnx8.ifs
ram 32m

because no memory has been allocated, so the qvm process has nowhere to load the IFS file.

rom

Same sequencing rule as with ram. Must be specified before any option refers to it.

PIC vdevs

Any 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.

Note:

You should always name your system, then allocate RAM and ROM right at the beginning of your qvm configuration.

Textual substitutions

As it reads through its configuration information, a qvm process instance performs textual substitutions when it encounters the following character sequences:

$env{var}: Replace the text string with the value of the var environment variable.
$asinfo_start{name}: Replace the text string with the starting address of the system page asinfo entry specified by name.
$asinfo_length{name}: Replace the text string with the length of the system page asinfo entry specified by name.

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:

Have the startup for the hypervisor host allocate the memory and record its location with a system page asinfo entry such as guestmem1.
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}
```

Addresses and lengths resulting from the expansion of $asinfo_start{name} and $asinfo_length{name} must obey the same restrictions as if they were manually configured in the VM. That is, the host-physical starting address of the memory allocated by the startup must be aligned to a page boundary, and the length must be a multiple of the page size on the host system. If not, the guest may experience I/O failures.

Similarly, you can use $env to put parameters in a configuration file. Suppose you have the following in a qvm configuration file (e.g., myconfig.qvmconf):

vdev ser8250 hostdev $env{HOST_DEV}

You could then define the HOST_DEV value that the vdev ser8250 hostdev option gets set to, 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.

About notation

The default notations (no prefix needed) for specifying memory addresses and sizes are:

address in memory – hexadecimal
size or length of memory region – decimal

If you prefer to write a memory address or region size with a non-default notation, use a prefix to specify the notation:

decimal – 0d (e.g., 0d1234)
hexadecimal – 0x (e.g., 0x4D2)

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.)

Note:

Other numeric configuration values are specified in decimal.
We recommend that, to avoid confusion, you specify the prefix when using hexadecimal values.