Shutting down guests and the hypervisor

Below are instructions for shutting down guests or the hypervisor.

Shutting down or restarting a guest

DANGER

Never use a SIGKILL signal to terminate a qvm process. This is equivalent to killing a driver in the midst of an I/O operation, and may leave the hardware in an unrecoverable state.

A variety of different methods can be used to shut down a guest.

Internal

The guest (more specifically, an application running on the guest OS) can initiate the guest shutdown, just as in a non-virtualized environment. For example, an application in a QNX guest could use the shutdown_system() function to shut itself down or reboot itself, just like in a non-virtualized system. In short, any action that ends up calling the reboot kernel callout will work.

From the command line, use shutdown in a QNX guest, or reboot in a Linux or Android guest.

If the guest shuts itself down or attempts to reboot, the hypervisor ends the qvm process for the VM hosting the guest, and frees all resources used by this process (which includes the resources used by the guest).

To manage your guest shutdowns, you can add an application or script running in the hypervisor host domain to monitor guests and decide what to do with guests and their qvm processes. This application or script should check the guest return codes to see if a guest has made a call to shut itself down or to reboot, and decide what to do with the qvm process in accordance with this information. For instance, if you want the hosting qvm process instance to restart (and restart the guest) after a guest reboot call, you can put the qvm command inside a while loop in the hypervisor host.

External

From your host system terminal, you can use a utility such as slay to slay the qvm process for the VM hosting the guest (see slay in the QNX SDP 7.0 Utilities Reference).

Send a SIGINT or SIGQUIT signal to the hosting qvm process instance to terminate it without notifying the guest. For example: slay -s SIGQUIT qvm.
Send a SIGTERM signal to the qvm process instance, to have it ask the guest nicely to terminate. On x86 platforms, this triggers the ACPI power button notification mechanism, which QNX typically ignores but a Linux guest will notice.
If a second SIGTERM is sent to the qvm process instance before the guest has terminated itself, the qvm process instance will act as though a SIGQUIT was sent and terminate without notifying the guest.

CAUTION:

Whenever possible, use a controlled shutdown from within a guest (shutdown in a QNX guest, or reboot in a Linux or Android guest).

If your guest is terminated in an uncontrolled manner, this guest may behave in an undefined manner on subsequent startups (e.g., it may have a corrupt filesystem).

Watchdog

Guests can also be configured to use a watchdog vdev in their hosting VMs (qvm process instances). If a guest fails to kick its watchdog in time, the watchdog may trigger a SIGQUIT to terminate the hosting qvm process instance immediately. This is what the watchdogs implemented with the reference images do, but it is not the only possible action (see “Watchdogs” in the “Using Your Hypervisor System” chapter).

Shutting down the hypervisor

The following methods can be used to shut down the hypervisor:

If the hypervisor encounters an undefined state, it will move to its Design Safe State (see “Design Safe State” in the “QNX Virtual Environments” chapter).
The hypervisor is a QNX Neutrino OS with virtualization extensions. Thus, all the mechanisms available for shutting down or rebooting a QNX Neutrino OS are available to the hypervisor. These mechanisms are available to applications running in the hypervisor host domain, but not to guests or their applications.