Configuration variables

Common variables

The following variables are supported on both ARM and x86 platforms:

counter-offset

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 0xffffffffffffffff

Specify the difference between host and guest timestamp counter values. This difference is constant throughout the VM's lifecycle. The default behavior, which can also be obtained by setting counter-offset to a 64-bit value of all ones (i.e., 0xffffffffffffffff) is to make the counter of the VM start at 0. Setting this variable to 0 makes the host and guest values match. Setting it to another number allows you to both easily match and distinguish between host and guest values.

debug

• Context: vdev – applies to the vdev currently being configured
• Variable type: boolean
• Default: on

Control whether a vdev is included in the VM status info produced by SIGUSR1.

exit-on-halt

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: on (guest exits on WFI or HLT instruction)

Control if a WFI (on ARM) or HLT (on x86) instruction causes a guest exit. Setting exit-on-halt to off increases physical CPU usage by vCPU threads but reduces interrupt latency. When the guest is allowed to execute WFI or HLT instructions, the host can't schedule any other thread on the physical CPUs used by the guest while it's executing those instructions.

fdt-dump-file

• Context: global – applies to the entire qvm process instance
• Variable type: string
• Default: none

Instruct the qvm process instance to write the VM's FDT to the specified file. You can then examine the FDT to better understand any customizations you may need to make to it (see FDTs (ARM) in the Configuration chapter).

If you set this variable and use the dryrun option, you can get the guest's FDT without starting the guest. For example, starting a qvm process instance as follows:

qvm @mainline-guest.qvmconf set fdt-dump-file /tmp/fdt.dtb dryrun

would cause the process instance to write the guest's FDT to /tmp/fdt.dtb, then exit with a message like the following:

FDT saved to '/tmp/fdt.dtb'
Exiting: dryrun completed

Note that the dryrun option causes the qvm process instance to exit before starting the guest (see dryrun in this chapter).

message-block-timeout

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 10000 milliseconds (10 seconds)

Set the maximum allowed time, in milliseconds, that a message from the qvm process may be blocked before the service sends an unblock pulse to the receiving server. For example:

set message-block-timeout 200

configures the qvm process to send an unblock pulse to any server that doesn't respond to a message within 200 milliseconds.

The message-block-timeout variable must be a value from 5 through 10000, or 0 (zero). A 0 makes the timeout infinite (never time out).

Depending on the server's response (or non-response), the qvm service may terminate with an error. You can use server-monitor to handle situations where a server doesn't respond to an unblock pulse (see server-monitor in the QNX OS Utilities Reference).

msi-pass-initial-threads

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 0

Pre-create the specified number of threads for Message Signaled Interrupt (MSI) forwarding. By default, new threads are created for this purpose only when there are no idle MSI forwarding threads that can be used.

slog-buffer

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 4K

Override the default slog buffer size. Setting this variable lets you increase the buffer size to prevent older entries from being dropped to make room for new entries. For example: set slog-buffer 8K increases the buffer size to 8K.

Note that:

• The buffer size must be a multiple of 4K (e.g., 8K, 12K).
• This option must be specified before the logger option in the VM configuration.

smmu-externally-managed

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off (the smmuman service is expected to be running)

Indicate whether IOMMU/SMMU services are externally managed. By default, the qvm process instance expects to use smmuman to ensure that the DMA configuration is safe and secure for pass-through devices. Setting this variable to on tells qvm to trust that the DMA configuration has been taken care some other way.

vdev-message-block-timeout

• Context: vdev – applies to the vdev currently being configured
• Variable type: number
• Default: 10000 milliseconds (10 seconds)

The vdev-message-block-timeout variable behaves exactly like the message-block-timeout variable but applies only to the vdev currently being configured. This means that the variable must be set within a context beginning with a vdev option; for example:

vdev lithium-ion-battery
    set vdev-message-block-timeout 5

ARM variables

The following variables are supported on ARM platforms only:

fdt-cmdline-policy

• Context: global – applies to the entire qvm process instance
• Variable type: string
• Default: overlay

Control how the value from the cmdline option and the value from the user-provided FDT overlay get merged into the /chosen/bootargs property given to the guest. The overlay setting lets the user-provided overlay (if it's present) replace this property. This is the default behavior. Alternatively, prepend prepends the value from the user-provided overlay to the value given in the cmdline option, while append appends the value from the user-provided overlay to the value of this option.

force-erratum-l2-tlb-prefetch

• Context: global – applies to the entire qvm process instance
• Variable type: tristate
• Default: auto

Specify whether to override the autodetection and correction of hardware errata described in:

• SDEN-885749 (Cortex A76) as #1262888
• SDEN-1152370 (Cortex A77) as #1262841

The default behavior (auto) is for qvm to apply these errata only if it auto-detects that it is needed on the hardware expected by the guest OS (i.e., the hardware that the VM is simulating).

You can set this variable also to on to always apply these errata or to off to never apply them.

force-erratum-speculative-at

• Context: global – applies to the entire qvm process instance
• Variable type: tristate
• Default: auto

Specify whether to override the autodetection and correction of hardware errata described in:

• ARM-EPM-048406 (Cortex A53) as #1530924
• SDEN-859338 (Cortex A55) as #1530923
• ARM-EPM-049219 (Cortex A57) as #1319537
• ARM-EPM-012079 (Cortex A72) as #1319367
• SDEN-885749 (Cortex A76) as #1165522

The default behavior (auto) is for qvm to apply these errata only if it auto-detects that it is needed on the hardware expected by the guest OS (i.e., the hardware that the VM is simulating).

You can set this variable also to on to always apply these errata or to off to never apply them.

gic-hwassist

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: on

If gic-hwassist is set to true (default), the qvm process instance will try to use the GIC hardware assistance support. If this variable is set to false, the qvm process instance won't try to use this support. You should disable this setting only when advised to by QNX customer support to help diagnose a problem.

host-paddr-gicd

• Context: global – applies to the entire qvm process instance
• Variable type: address
• Default: the gicd entry in the host's system page asinfo section

Set the host-physical address of the GIC distributor registers. This setting is needed on boards where the startup program does not automatically supply the address via the system page.

Note:

This and the other host-paddr-* options are needed only if the startup program has incomplete or incorrect information in the asinfo section of the system page. They are not needed on a standard platform with a correct startup program.

host-paddr-gich

• Context: global – applies to the entire qvm process instance
• Variable type: string
• Default: the gich[.cpunum] entry in the host's system page asinfo section

Set the host-physical addresses of the GIC hypervisor control registers. The string should be formed as follows:
host_address[/cpu/spacing]{,host_address[/cpu/spacing]}

The string components are:

host_address

The host-physical address of the current physical CPU's GICH registers.

cpu

If present, the number of the physical CPU whose registers are located at host_address.

spacing

If present, the number of bytes to increase the offset to get the address of each subsequent physical CPU's registers.

host-paddr-gicr

• Context: global – applies to the entire qvm process instance
• Variable type: address
• Default: the gicr entry in the host's system page asinfo section

Set the total size needed for the GIC redistributor registers. Normally, qvm determines this size as a multiple of the number of cores on the board. However, some board designs that support varying numbers of cores do not arrange the redistributor registers to form a single contiguous region for all CPUs on the system. For example, a board design that could handle up to 128 cores might organize the redistributors in an array that fits up to 128 entries but the 32-core version could be spread out sparsely across that whole region.

host-paddr-gicv

• Context: global – applies to the entire qvm process instance
• Variable type: address
• Default: the gicv entry in the host's system page asinfo section

Set the host-physical address of the GIC virtual CPU interface registers.

host-ppi-gic-hwassist

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 25

Set the host interrupt number for the GIC hardware assist maintenance interrupt.

Note:

This and the other host-ppi-* options are needed only if your system does not follow the ARM guidelines for assigning PPIs as explained in rule B_PPI_02 from the ARM Base System Architecture 1.1D (DEN0094).

host-ppi-hcnt

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 26

Set the host interrupt number for the hypervisor counter interrupt.

host-ppi-pmu

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 23

Set the host interrupt number for the PMU interrupt.

host-ppi-vcnt

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 27

Set the host interrupt number for the virtual counter hardware.

its-client-config

• Context: global – applies to the entire qvm process instance
• Variable type: string
• Default: none

Define the Interrupt Translation Service (ITS) domains available to the guest. The its-client-config variable is a string that must contain a colon-separated list of ITS domain definitions as follows:
baseloc1,lockloc1[:baseloc2,lockloc2]*

Note:

Currently, only a single domain definition is allowed.

linux-fdt-free

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off (the FDT must be located within a specific region of the guest memory)

Control whether to allow the FDT provided to the guest to be located anywhere in guest memory. By default, the FDT must be located in the memory region within 512M of the OS image as required prior to Linux 4.2.

pointer-authentication

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: on (FEAT_PAUTH is enabled)

Specify whether the ARM extension FEAT_PAUTH is enabled in the guest. Note that for this feature to take effect on a vCPU, all pCPUs on which it may run must support this feature.

psci-supported

• Context: global – applies to the entire qvm process instance
• Variable type: tristate
• Default: auto

Specify whether the host supports the Power State Coordination Interface (PSCI). With the default auto setting, qvm automatically determines whether the host supports PSCI by checking the host's device tree. However, if the host does support PSCI but does not provide an appropriate device tree entry, this option can be set to on to prevent the checking. This option can be set also to off to disable the use of PSCI altogether.

sve-enable

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off (FEAT_SVE is disabled)

Specify whether the ARM extension FEAT_SVE is enabled in the guest. Note that for this feature to take effect on a vCPU, all pCPUs on which it may run must support this feature.

trace-spectre-workaround

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off

Some optimizations to guest exit mechanisms cause some guest spectre errata workaround requests to not appear in a host trace log. Setting trace-spectre-workaround to true disables the optimizations, allowing the omitted guest trace-spectre-workaround requests to appear in the host trace log.

trace-vtimer

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off

Some optimizations to the guest exit mechanisms will cause some guest virtual timer interrupt deliveries to not appear in a host trace log. Setting trace-vtimer to true disables the optimizations, allowing the omitted guest virtual timer interrupt deliveries to appear in the host trace log.

trace-wfe

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off

Some optimizations to the guest exit mechanisms will cause some guest executions of a WFE instruction to not appear in a host trace log. Setting trace-wfe to true disables the optimizations, allowing the omitted guest executions of a WFE instruction to appear in the host trace log.

vmid

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: auto-generated value

Set the VMID for the guest. The value can't be 0. If this variable isn't set, the hypervisor generates a VMID. A vdev can retrieve the value via the qvm_guest_vmid() vdev API function.

x86 variables

The following variables are supported on x86 platforms only:

legacy-free

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: off – don't permit arbitrary memory layout (i.e., require ACPI tables, etc.)

The legacy-free variable can be used to assemble a VM that hosts an x86 guest with an arbitrary memory layout. Most notably, with legacy-free set to on, the VM can be assembled for a guest that doesn't require memory in the BIOS area (where the ACPI and SMBIOS tables are stored).

If you set this variable to on, you should also use the suppress variable to suppress generation of the ACPI system information table for the x86 guest (see suppress in this chapter).

posted-interrupts

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: on

If posted-interrupts is set to on (default), the qvm process instance will try to use the hardware's posted interrupt support, if such support is available. If this variable is set to off, the process instance won't try to use this support.

virtual-interrupts

• Context: global – applies to the entire qvm process instance
• Variable type: boolean
• Default: on

If virtual-interrupts is set to on (default), the qvm process instance will try to use the hardware's virtual interrupt support, if it is available. If this variable is set to off, the process instance won't try to use this support. Note that turning virtual interrupt support off also turns off posted interrupt support.

vmx-abort-interval

• Context: global – applies to the entire qvm process instance
• Variable type: number
• Default: 0 ms (off)

Periodically check each vCPU to ensure the VMX abort indicator has not been set. A non-zero vmx-abort-interval value specifies the interval in milliseconds at which these checks are done. The default setting of zero (0) means these checks are turned off.

Note:

This variable should be used only as requested by QNX Customer Support.