Configuring guests

When you configure the guest, make sure that the configuration for the guest aligns with the configuration of the VM in which it will run (see “Assembling and configuring VMs” in this chapter), just as you would have to make sure that an OS is configured properly to run on a specific hardware platform.

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 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 start with 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 example, the following specifies that the vdev is an I/O device on port 4: io:4.

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 the 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:

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

On x86 platforms, the 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 GIC hardware is automatically supplied; there is no need 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 option 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 in your guest FDT nodes that are in the FDT that the qvm process generates. To reference a node in the qvm-generated FDT from your guest's FDT, do the following:

1. In the configuration for the VM that will host your guest, use the name option to give your vdev a name; for example:

   vdev moo_vdev name gary

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

1. In the configuration for the VM that will host your guest, name the PIC vdev; for example:

   vdev gic name gicfoo

2. In the FDT for the guest, create a node to identify the PIC 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>

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 option, the PIC vdev defaults to vdev gic name gic. That is, when you configure interrupts for a vdev, use gic to identify the PIC; 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 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