VM configuration syntax

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

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; for example, the vdev option establishes a context in which a virtual device is defined.
  • 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.

  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/qnx7.ifs instructs the qvm process to copy the contents of /vm/images/qnx7.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 later in this chapter).
• In general, option sequence isn't important. It doesn't matter in which order you define virtual devices, 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 (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. 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 scheduling priority 10 (the default).

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

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 file (see “system” under “Configuring VM components”).

ram

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.

rom

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

PIC vdevs

vdevs for Programmable Interrupt Controllers (PICs) must be specified before any other vdevs that reference them. For example:

vdev 8259 name master
vdev ser8250 intr master:4

is valid because vdev 8259 is specified before vdev ser8250, which references it. However, the following will fail:

vdev ser8250 intr master:4
vdev 8259 name master

because vdev ser8250 references vdev 8259 before this vdev has been specified.

Textual substitutions

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

$env{envvar}

Replace the text string with the value of the envvar environment variable.

$asinfo_start{asinfo_name}

Replace the text string with the start address of the system page asinfo entry specified by asinfo_name.

$asinfo_length{asinfo_name}

Replace the text string with the length of the system page asinfo entry specified by asinfo_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:

1. Have the startup for the hypervisor host allocate the memory and record its location with a system page asinfo entry (e.g., guestmem1).

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

For more information about pass-through, see “Configuring pass-through” in this chapter. For more information about the ser8250 virtual device, see “vdev ser8250” in this chapter.

For more information about the system page asinfo data structure array, see the “System Page ” chapter in Building Embedded Systems.