Function Safety

Overview of the restrictions that may apply when using the functions in this API

Warning: If you are building a system with QNX Hypervisor for Safety, refer to the QNX Hypervisor for Safety Safety Manual for your QHS release.

Function use: startup or running?

Some functions may only be called during the startup phase, when the qvm process instance is assembling the VM, including the vdevs. Others may only be called after the startup phase has completed, when the system is running.

When the qvm is completing the vdev and VM configuration, your vdev will receive the following callbacks:

VDEV_CTRL_OPTIONS_END
The qvm process has finished parsing your vdev's options. It may not have completed configuring the VM, however: it may still have other vdevs and VM components to configure.
While some vdev API functions that should only be used after startup is complete may be safely called after the VDEV_CTRL_OPTIONS_END callback, many can't be called safely at this point (e.g., vdev_path()). It is best to wait for the VDEV_CTRL_GUEST_CONFIGURED callback before calling any of these functions.
VDEV_CTRL_ASSIGN
All user-specified options have been processed. The vdev must now check if the loc and intr options have been specified; if they haven't been specified, the vdev must specify them for itself.
VDEV_CTRL_GUEST_CONFIGURED
The qvm process has finished configuring the VM for the guest system. It is safe to create threads, and to call functions that should only be used after startup is complete (e.g., vdev_path()).
From this point forward, your code must assume that it is running in a multi-threaded environment.
VDEV_CTRL_GUEST_STARTING
The qvm process is about to start the guest. This callback marks the point at which the qvm process instance is about to change the state of the vCPU thread that will start the guest (see the QNX Hypervisor Virtual Device Developer's Guide)
This callback isn't use for determining if the qvm process has completed the VM for the guest system. Use VDEV_CTRL_GUEST_CONFIGURED.

The first page of most chapters of this API reference include a “Function safety” table that specifies if each function defined in the relevant header file is thread safe, and when each function may be used:

If all functions defined in a header file can be used in the same way (e.g., outpipe.h), then this information is stated and no table is provided, as a table would be superfluous. If a header file defines no functions (e.g., types.h), then no function safety information is provided, as none is needed.

CAUTION:
If your vdev calls the function outside the limits stated in these notes, behavior of the vdev and its VM is undefined.

Thread safety

Details about thread safety and what locks, if any, to use around functions are specified at the start of the chapter where the function is described.

During a vdev's configuration phase, a qvm process instance is single-threaded, so there is no need to lock resources around functions calls.

After the end of the startup phase, during the running phase, you should assume that you are running in a multi-threaded environment, and use locks as appropriate to ensure the integrityof your data (see “Lifecycle of a vdev” in the QNX Hypervisor for Safety 2.0 Virtual Device Developer's Guide).

Blocking vCPU threads

If your vdev makes calls that may block or wait for input, make sure that you create a new thread from which the vdev can make these calls. That is, after vdev initialization is complete and you receive the VDEV_CTRL_GUEST_CONFIGURED callback, do not make these sorts of calls from the thread that initializes the vdev. This is a vCPU thread, and if it blocks the vCPU cannot proceed with other work for the qvm process. Create a new thread or threads from which to make calls that may block or wait for input.

You may create a new thread in your vdev only after your vdev has received the VDEV_CTRL_GUEST_CONFIGURED callback, confirming that the qvm process has finished configuring the VM (see vdev_thread_create()).