Building guests

Updated: October 28, 2024

When you build guests to run in a QNX virtualized environment, you must build them for the appropriate hardware architecture, and configure the VMs in which they will run.

You need to have the build environment and tools that correspond to the hypervisor host and the guests you're building (see “Supported build environments”).

Validating the guests before and after adding them to the hypervisor system

It may be easier to identify and debug problems in an OS that you want to use as a guest before integrating it into in your hypervisor system.

  1. If you're building a QNX Neutrino system that will be used as a guest, follow our instructions for building an OS image given in Building Embedded Systems and copy the image to your target.

    For a non-QNX system, follow the platform-specific instructions for building that image and copy it to your target.

  2. Boot your target board into the image you copied onto it and make sure the image runs as required. In particular, make sure all devices you'll configure as pass-through devices to the guest are functioning properly. Problems with these devices are easier to resolve in a non-virtualized system than in a hypervisor system.
  3. Repeat for each OS you'll run as a guest.

When you're satisfied all these OS images function well in a non-virtualized system, you can add them as guests to your hypervisor system. For a QNX Neutrino guest, you must obtain a hypervisor guest BSP and use it to build a new OS image. Then, you can add this guest along with the non-QNX guests to your hypervisor system image, copy this newly built image to your target, and boot into it.

CAUTION:
Further validation of a guest in the hypervisor environment is needed in any of the following situations:
  • The guest uses para-virtualized devices, which by definition don't exist as hardware.
  • The guest uses vdevs, meaning the configuration for the VM that hosts the guest must be updated to include these vdevs (see “Configuring the VMs” below).
  • The startup driver required for the guest may not work directly on the board; you may have to change the buildfile for the guest to (temporarily) use the appropriate driver for starting it up directly on the board, but a different startup driver will be needed in the hypervisor system.
  • Some devices aren't passed through to the guest. In this case, you need different drivers when you run the hypervisor system so the hypervisor host can manage these devices.

You must ensure all guests function as expected in the hypervisor environment before deploying these guests (and the host) in a production system.

Supported guest formats in images

The hypervisor can launch guests placed on the system as bootable images in the following formats:
  • ELF (including multiboot)
  • Linux zImage

Configuring the VMs

Each guest in a hypervisor system is hosted in a hypervisor qvm process. When it is started, each instance of the qvm process reads its specified configuration file and assembles a VM from the components specified in this file. This VM becomes the virtual environment in which the guest runs.

If you change anything in your guest that accesses hardware (physical or virtual), you need to ensure that the qvm configuration file for the VM that will host the guest is properly configured.

When building a guest to run in a QNX virtualized environment, it is important to remember that each guest must be configured to match the VM in which it will run. This means that it must have the drivers it needs to access devices, whether they are physical or virtual. In the VM, the drivers must be configured to be where the guest expects them to be.

In a QNX OS system, board-specific drivers and other components are brought into the build through BSPs. This is true for a QNX OS that will run in a VM, just as it is for a QNX OS that will run directly on hardware.

For both ARM and x86 hardware platforms, you'll need the BSP for your supported hardware platform to build the hypervisor host domain, and a hypervisor guest BSP to build each guest. These are available for QNX Neutrino 7.1 and QOS 2.2.1 guests. If you add new devices for your guest, you'll probably need to add the appropriate new drivers to the BSPs, and rebuild the guest with them.

What is true for QNX guests is also true for non-QNX guests: the VM must present to the guest the virtual environment the guest OS expects to find (i.e., the hardware components it has been built to use). The only difference is that QNX OSs (including QNX OSs that will run as guests in virtualized environments) use BSPs to bring in the architecture-specific and board-specific components, while other OSs may use other mechanisms to achieve the same end.

For more information, see “Assembling and configuring VMs” in the “Configuration” chapter.