Configuring guests

Guests in a QNX virtualized environment are configured in the same way as they are configured in a non-virtualized environment. For example, for QNX guests, use the buildfile.

CAUTION:

When you configure the guest, make sure that its configuration aligns with the configuration of the VM in which it will run, just as you would have to make sure that an OS is configured properly to run on a specific hardware platform. This means the guest must match the VM in terms of architecture, board-specifics, memory and CPUs, devices, etc. For more information, see Assembling and configuring VMs.

If you are building a QNX guest, make sure to add the virtual attribute to your guest's buildfile, so that it knows the VM architecture on which it will run. For example, for ARM you need:

[virtual=aarch64le,elf ...

and for x86 you need:

[virtual=x86_64 ...

Both ARM and x86 guests require some additional instructions in their buildfiles (see Building guests in the Building a QNX Hypervisor System chapter). For more information about QNX buildfiles in general, see the OS Image Buildfiles chapter in Building Embedded Systems.

Guest resource types

For a guest, every resource exists in a specific location (or space). This space defines the resource type. In the VM configuration, the location entries consist of the common vdev option loc followed by a resource type identifier and other parameters specific to the resource type:

mem:address ...: The location is a guest-physical address (intermediate physical address). The first parameter gives the physical address as understood by the guest.
For a full explanation and examples of all parameters used with this identifier, see the first form of the pass loc option in the VM Configuration Reference chapter.
io:port ...: The location is in the x86 I/O space. The first parameter is the port number.
For an explanation of all parameters used with this identifier, see the first form of the pass loc option.
pci:{pci_vid/pci_did|pci_bus:pci_dev[.pci_func] ...}: The location is a PCI device. The device can be specified either by the vendor ID and device ID, or by the bus, device, and optionally, function number.
For explanations and examples of these two different ways of specifying the PCI device, see the second form and the third form of the pass loc option.

Default resource types

If no resource type identifier is specified in the device configuration, a suitable default is chosen. The most common default resource type is mem:, but the default changes according to the vdev. For example, the default resource type for VIRTIO devices is pci:, though these devices can also be specified as mem: resources. See the descriptions of individual devices for each device's default resource type.

Guest interrupts

A guest interrupt is specified by an intr entry in the VM configuration. Depending on the platform, this entry can have two parts:

the guest device interrupt controller name, which is specified by the vdev name property
the interrupt controller input line that is asserted when the device wishes to raise an interrupt, which is specified by the number given as the part of the intr argument

Information about these two properties is given in Common vdev options.

On x86 platforms, the Local component Advanced Programmable Interrupt Controller (LAPIC) hardware is automatically supplied. There is no need to specify a vdev for it, and guest vdevs that feed interrupts to the LAPIC hardware should simply specify apic for their interrupts; no input line number needs to be stated.

For example, the following creates a virtual I/O APIC device and a ser8250 serial device on an x86 system:

vdev ioapic
    intr apic
    name myioapic
vdev ser8250
    hostdev >-
    intr myioapic:4

On ARM platforms, the Generic Interrupt Controller (GIC) hardware is automatically supplied; it is not necessary to specify this vdev. You can still specify it if you want to change its option values, including the input line that gets asserted (for details, see the vdev gic reference). The default name for guest devices that feed interrupts to the GIC is gic, but you can use the vdev's name property to change this.

The following example creates a virtual PL011 device on an ARM system:

vdev pl011
    loc 0x1c090000 
    intr gic:37
    name mygic

Controlling guest behavior through vCPUs

Many guest OSs auto-detect functionality offered by the underlying physical CPUs (pCPUs). Therefore, you should usually configure a vCPU to run only on pCPUs (cores) of the same type. For details on doing so, see the cpu cluster option. If you want to run a vCPU on different core types, ensure you know which CPU features the guest will use and you restrict the vCPU to a cluster of pCPUs that support these features.

For the vCPU priority, you can set it only when starting the guest; afterwards it cannot be changed. However, it is best practice that the vCPUs in a given VM be configured with the same thread priority.

Also, note that thread priorities within a guest are distinct from those visible to the host scheduler. If this scheduler has a low priority host thread that is ready to run and this thread's priority is higher than the vCPU's priority, it does not matter that inside the guest it is running a high priority guest thread. For further explanation, see the Scheduling section in the Understanding QNX Virtual Environments chapter.

Page updated: March 05, 2025