Debugging a vdev

You can use the same techniques to debug a vdev as you use to debug other code in a QNX OS system.

A vdev is a shared library (*.so file) loaded at runtime by the qvm process instance (i.e., the VM) whose guest requires the vdev. You can therefore attach to that process to investigate the vdev. For example, you can:
  • put breakpoints in your vdev
  • run the qvm process instance in debug mode
  • load symbols in the qvm process instance

Since your vdev necessarily interacts with a guest, you may also need to debug the guest driver (see the User's Guide Monitoring and Troubleshooting chapter). If your vdev is in a VM that hosts a Linux guest, you may need to debug the relevant Linux OS module.

For information about debugging problems with option parsing, see Parsing the vdev options in the The Basics: vdev trace chapter.

For more information about debugging in a QNX OS system, see:

Reporting the vdev status

The VDEV_CTRL_STATUS callback is invoked when a SIGUSR1 or SIGUSR2 signal is sent to a qvm process instance. If you want your vdev to output information about its status, use this callback and the qvm_report() function. The way qvm_report() outputs text status information depends on which signal was sent. For SIGUSR1, the function logs the text at the INFO level; for SIGUSR2, it adds the text to the dump file.

The following snippet is from the ser8250 vdev's vd8250_control() function: 
case VDEV_CTRL_STATUS:
    qvm_report("dlr=0x%x lcr=0x%x ier=0x%x mcr=0x%x",
               state->s_dlr, state->s_lcr, state->s_ier, state->s_mcr);
    break;

For more information, see A guest-host hardware device intermediary (vdev ser8250) in the Advanced Topics chapter, and qvm_report() in the Virtual Device Developer's API Reference.

Logging

You can log messages for a given vdev. The QNX hypervisor provides an API that can be used by any vdev, including one that you write, to log messages consisting of formatted strings.

When configuring the underlying VM, you can use the logger option to control which message types (severity levels) are logged and where they are output (e.g., stderr, stdout), for all vdevs. This mapping of message severity levels to output destinations is defined in the VM configuration (*.qvmconf) file. For more information, see the logger entry in the User's Guide.

You can override the logging for a given vdev, however, by using the log option in the vdev's own configuration. For details on doing so, see the log option entry in the User's Guide.

Here, we give an example of using the vdev_logf() API function. This function is declared in sys/log.h, so you must include this header file in any source files that use it. For a full description of vdev_logf() and the other logging functions, see the Virtual Device Developer's API Reference.

Suppose in our vdev code we want to report that we've entered a particular function and started processing its arguments. We could then use the following call: 
void particular_function(vdev_t vdp) {
    ...
    vdev_logf(QL_QVM_INFO, vdp, "%s: OPTIONS_START", __func__);
    ...
}
Here, we use the constant QL_QVM_INFO as the first argument to indicate a type (severity level) of information. For a list of all constants for indicating severity levels, see the Definitions in log.h entry in the Virtual Device Developer's API Reference.

For the second argument, we use the vdev_t pointer passed into our function that's doing the message reporting. The third argument defines a formatted string with one placeholder for another string value, while the last argument provides the current function name for that other string.

Page updated: