Terminating qvm process instances and guests

The method you use in your vdev to terminate a qvm process instance (and, hence, any running guest) depends on the status of the guest.

There are two mechanisms you can use:

qvm_fatal(), if something happened while initializing the VM that will prevent the guest from starting. For example, the host can't provide the VM with enough memory, or the user provided an invalid vdev configuration option.
guest_terminate(), if something happened in the guest that will prevent it from continuing to run. For example, the guest didn't service the watchdog vdev as needed to avoid a reset of the VM.

A vdev can expect a VDEV_CTRL_GUEST_CONFIGURED callback from the qvm process when it has finished configuring the VM for the guest system, and a VDEV_CTRL_GUEST_STARTING callback when it has started the guest (see the earlier Lifecycle of a vdev section). The termination method you use depends on which of these callbacks you've received.

For more information about terminating qvm process instances and guests, see Handling a qvm termination in the User's Guide QNX Hypervisor: Protection Features chapter.

Guest hasn't started: qvm_fatal()

If during VM setup the vdev encounters a condition that requires it to prevent the guest from starting, the vdev should call qvm_fatal() to output an error message and terminate the qvm process.

The following snippet is from the trace vdev described in the next chapter:

case VDEV_CTRL_GUEST_CONFIGURED:
    vdev_logf(QL_QVM_INFO, vdp, "%s: VDEV_CTRL_GUEST_CONFIGURED", __func__);
    /* The VM is now fully configured to support the guest system. */
    bool config_failed = parse_guest_config(cfg_ptr);
    if (config_failed) {
        qvm_fatal(QLS_CNF, "%s: config failed", __func__);
    }

In this example, the parse_guest_config() function is made up and shown for illustrative purposes. The qvm_fatal() function is part of the logging API. Notice that the first argument for this function is QLS_CNF, which specifies that it's a configuration error. The qvm_fatal() function doesn't return; its prototype in qvm/log.h is marked with __attribute__((noreturn)) so that static code analysis tools know this fact. For further details about using qvm_fatal(), see the Virtual Device Developer's API Reference log.h chapter.

Guest has started: guest_terminate()

If the guest has already started, meaning your vdev has received a VDEV_CTRL_GUEST_STARTING callback from the qvm process, then you must use guest_terminate() to terminate the guest as well as the hosting qvm process. For more information, see guest_terminate() in the Virtual Device Developer's API Reference guest.h chapter.

The following code snippet is from the wdog_bite() function called by the watchdog vdevs described in the Advanced Topics chapter:

case WDOG_ACTION_TERMINATE:
    vdev_logf(QL_QVM_ERR, vdp, "%s: terminating", error_str);
    guest_terminate(GTC_WATCHDOG);
    break;

For further details about wdog_bite(), see the Virtual Device Developer's API Reference wdog.h chapter.

Page updated: March 14, 2026