Shutting down guests

A variety of different methods can be used to shut down a guest in a QNX hypervisor VM.

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.

If you are building a hypervisor system that will be certified for safety, refer to your QNX Hypervisor for Safety 2.0 and QNX OS for Safety 2.1 Safety Manuals for the safety requirements and recommendations concerning watchdogs.

For instructions on how to shut down the hypervisor, see “Shutting down a QNX hypervisor”. For information about how to handle VM terminations (termination of a qvm process instance), see “Handling a qvm termination” in the “QNX Hypervisor for Safety” chapter.

Internal (controlled) guest shutdown

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).

Since the host can't see into the guest, the guest should explicitly inform the hypervisor that it is shutting down. A simple way to do this is to:

Use the shared memory vdev (vdev shmem) to set up a small area of memory shared between the guest and the host (see “Memory sharing” in the “Using a QNX Hypervisor System” chapter).
When it shuts down, the guest writes a pre-defined value to a location in this shared memory.
When it reads this value in the shared memory, the hypervisor host sets about looking after whatever tasks it needs to complete (e.g., mask interrupts to the guest) in response to the guest's shutting down.

External (uncontrolled) guest shutdown

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

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 Utilities Reference).

Send a SIGQUIT signal to the hosting qvm process instance to terminate it without notifying the guest; that is, emulate immediately cutting the power. For example: slay -s SIGQUIT qvm.
Send a SIGTERM or SIGINT 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 or SIGINT signal 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.

If you terminate a VM (qvm process instance), you must look after putting into a quiescent state any hardware devices that were passed-through to a guest in the VM. You can do this with a virtual device (see the QNX Hypervisor for Safety 2.0 Virtual Device Developer's Guide).

CAUTION:

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).

Watchdogs

Guests can 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 a common way of using a watchdog, but it is not the only possible action (see “Watchdogs” in the “QNX Hypervisor for Safety” chapter).

Managing pass-through devices

If the guest that is shutting down has pass-through devices allocated to it, the guest should:

Inform any other guests (or the host) that it is shutting down and that, therefore, the devices will no longer be available (see “Referred sharing” in the “Understanding QNX Virtual Environments” chapter).
Put these pass-through devices in a quiescent state.
Inform the hypervisor host that it is shutting down.