Shutting down guests

There are different methods for shutting down guests in a QNX hypervisor VM.

DANGER:

To avoid killing a driver in the midst of an I/O operation, and possibly leaving the hardware in an unrecoverable state, use a SIGTERM or SIGINT signal to terminate a qvm process.

For instructions on how to shut down the hypervisor, see Shutting down the QNX hypervisor. For information on how to handle a VM termination, see Handling a qvm termination in the QNX Hypervisor: Protection Features chapter.

Internal (controlled) guest shutdown

The guest (more specifically, an application running on the guest OS) can initiate its own shutdown. For example, an application in a QNX guest could use the shutdown_system() function to shut itself down or reboot itself. 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 those used by the guest (see Handling a qvm termination).

The host can't see into the guest, so if the host needs to perform actions before the guest shuts itself down, the guest must explicitly inform the host that it's shutting down. A simple way to do this is to:

  1. 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 Virtual Devices, Networking, and Memory Sharing chapter).
  2. When it shuts down, the guest writes a pre-defined value to a location in this shared memory.
  3. When it reads this value in the shared memory, the hypervisor host sets about performing whatever tasks it needs to complete (e.g., masking interrupts to the guest, quiescing any physical devices) in response to the guest's shutting down. An explanation of quiescing physical devices is given in Quiescing devices during guest shutdown.

If the guest has physical devices allocated to it, the guest should inform any other guests with which it might be sharing these devices that it is shutting down and thus, the devices will no longer be available.

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). If you cannot do so, then an uncontrolled guest shutdown is possible as described here.

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

  • SIGTERM or SIGINT: Send a SIGTERM or SIGINT signal to the qvm process instance to emulate pressing the power button. For example: slay -s SIGTERM qvm. This makes qvm ask the guest nicely to terminate.

    On x86, this triggers the ACPI power button notification mechanism, which will allow the guest to cleanly shut down if it takes notice of it. Linux and Android guests (the latter if set up properly) have ACPI handling in place and will notice, but QNX guests won't. If you send a SIGTERM or SIGINT but the guest doesn't shut down, qvm assumes there's no handling installed in it. Sending a second signal will unconditionally terminate the guest.

    On ARM, there's no standard for power button notification so unless a guest-specific vdev is written, no handling is performed. Thus, sending a SIGTERM or SIGINT immediately terminates the guest with no notification.

  • SIGQUIT: Send a SIGQUIT signal to the hosting qvm process instance to terminate it without notifying the guest regardless of any power-off handling in it. This emulates immediately cutting the power. For example: slay -s SIGQUIT qvm.

If you terminate a VM (qvm process instance), you must put into a quiescent state any hardware devices that were passed through to a guest in the VM. You can do this with a custom vdev. For information about writing custom vdevs, see the Virtual Device Developer's Guide in the QNX Hypervisor GitLab Repository at https://gitlab.com/qnx/hypervisor.

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

Page updated: