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

Every device exists for the guest in a specific location (or “space”). This space defines its resource type. In the VM configuration, these location entries consist of a resource type identifier followed by a colon. The information that follows the colon depends on the resource type. Supported identifiers and the resource types they identify are:

mem

The location is a guest-physical address (intermediate physical address). The number following the colon gives the physical address as understood by the guest.

io

The location is in the x86 I/O space. The number following is the port number.

pci

The location is a PCI device. It may be followed with two different types of specifier:

pci:vendor_id/device_id[/device_index]
pci:bus_number:device_number[.function_number]

For instance, the following specifies that the vdev is an I/O device on port 4: io:4. For more examples of how these identifiers are used, see the loc option for the pass qvm configuration option in the “VM Configuration Reference” chapter.

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 entry in the VM configuration. This entry has two parts, separated by a colon. They identify, respectively:

the guest device Progammable Interrupt Controller (PIC) name (specified by the vdev name property; see “Common vdev options”)
the PIC input line that is asserted when the device wishes to raise an interrupt

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 feeding interrupts to the LAPIC hardware should simply specify apic (with no colon or number following) for their interrupts.

On ARM platforms, the Generic Interrupt Controller (GIC) hardware is automatically supplied; it's not necessary to specify this vdev. However, you can specify it if you want to change the values for its options (see “vdev gic” in the “Virtual Device Reference” chapter). The default name for guest devices feeding interrupts to the GIC is “gic”, but you can use the vdev's name property to change this.

Examples:

The following creates a virtual I/O APIC device on an x86 platform:

vdev ioapic 
    loc 0xf8000000
    intr apic 
    name myioapic

The following creates a virtual PL011 device on an ARM platform:

vdev pl011 
    loc 0x1c090000 
    intr gic:37

Referencing a vdev FDT node from a user-provided FDT

Since the FDT information describing a vdev is generated by the qvm process at startup, this information can't be included in the FDT you provide for your guest—it isn't available when you create the FDT.

To solve this problem, the hypervisor provides a mechanism that allows you to reference specific FDT nodes in your guest. These FDT nodes are in the FDT that the qvm process generates. To reference such a node from your guest's FDT, do the following:

In the configuration for the VM that will host your guest, use the name property to give your vdev a name; for example:
```
vdev moo_vdev name gary
```
In the FDT for your guest, create a node to identify the vdev by name; for example:
```
vmoo: vmoo@0 {
    qvm,vdev = "gary";
}
```

With this information in your FDT, the qvm process will be able to provide the guest with an FDT that redirects all references to the node with qvm,vdev in your guest's FDT to the corresponding qvm vdev node it generates, then remove the qvm,vdev node.

For more details about FDTs in a QNX hypervisor system, see “ACPI tables and FDTs” in this chapter.

Example: referencing a PIC vdev

The following shows how to reference the node for a PIC in a qvm-generated FDT so that at startup the qvm process can update the guest's FDT:

In the configuration for the VM that will host your guest, name the PIC vdev; for example:
```
vdev gic name gicfoo
```
In the FDT for the guest, create a node to identify this vdev by name; for example:
```
vgic: vgic@0 {
    qvm,vdev = "gicfoo";
}
```

This device node can now be referenced in the guest's FDT; for example in a device node's interrupt-parent property:

some-device-node {
    interrupt-parent = <&vgic>;
};

or its interrupt-map property:

interrupt-map = < 0 0 0 0 &vgic 0 140 0 0 0 0 1 &vgic 0 149 0 >

Note:

The FDT label used for the node containing the qvm,vdev property can be anything.
The value of the qvm,vdev property in the guest's FDT must match the value of the vdev's name property in the VM configuration.

About the gic vdev name (ARM only)

If you don't specify vdev gic in the VM configuration, or if you specify vdev gic but don't specify the name property, the PIC vdev defaults to vdev gic name gic. That is, when you configure interrupts for a vdev, use gic to identify the PIC vdev; for example:

vdev pl011 loc 0x1c090000 intr gic:37 hostdev /dev/ser2

If you specify another name for your PIC (i.e., not gic, but, say, gary), then you must use that name when you specify interrupts for other vdevs; for example:

vdev pl011 loc 0x1c090000 intr gary:37 hostdev /dev/ser2