VM configuration syntax
A VM (qvm process) 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 entire configuration information to know how to assemble and configure the VM.
- 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 acpu
option applies to the current context established by thecpu
option, thussched
contributes to the definition of the vCPU specified bycpu
. - 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. - The option establishes a context in which other options can be set;
for example, the
- 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, andload /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 theVM 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.
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.
cpu sched 8 cpu sched 6
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).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 (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:
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:ram 32m load /qnx8.ifs
because no memory has been allocated, so the qvm process has nowhere to load the IFS file.load /qnx8.ifs ram 32m
- 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:
is valid because vdev ioapic is specified before vdev ser8250, which references it. However, the following will fail:vdev ioapic loc 0xf8000000 intr apic name myioapic vdev ser8250 intr myioapic:4
because vdev ser8250 references vdev ioapic before this vdev has been specified.vdev ser8250 intr myioapic:4 vdev ioapic loc 0xf8000000 intr apic name myioapicr
Textual substitutions
- $env{envvar}
- Replace the text string with the value of the envvar environment variable.
- $asinfo_start{asinfo_name}
- Replace the text string with the starting 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:
- 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}
Now, no matter where the reserved memory actually ends up in the host, the configuration will work.
$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
$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
.)
- Other numeric configuration values are specified in decimal.
- We recommend that, to avoid confusion, you specify the prefix when using hexadecimal values.