The Basics: vdev trace

This simple vdev illustrates how to implement basic vdev functionality.

Note: The source code for vdev trace, the guest-app pseudo-driver, and other vdevs and applications discussed in this Developer's Guide are available on GitHub at github.com/qnx.

vdev trace

Show how a vdev works (i.e., the “Hello world!” vdev)

Synopsis:

vdev trace options

Options:

In addition to the common options defined in the qvm process (see “Common vdev options” in the User's Guide), the trace vdev supports the following options:

emit-logger: Optional. Write output to logger (see “Description” below)
emit-trace trace_num: Optional. Writes output to the hypervisor host's kernel trace buffer. If you specify this option, you must also set the trace_num argument with the trace number to use.

Note that the loc option may only be set to mem (see “Defining the vdev in the factory structure” in this chapter, and “Common vdev options” in the User's Guide).

Description:

ARM and x86. This vdev makes available to a guest a 32-bit location in its guest-physical memory. The guest can read from or write to this location; when it does so:

If the vdev's emit-logger option is specified in the VM, vdev trace writes a message to the hosting qvm process instance's logger (see logger in the QNX Hypervisor User's Guide).
If the vdev's emit-trace option is specified in the VM, vdev trace writes the trace event specifed by the emit-trace option's trace_num argument to the hypervisor host (e.g., TraceEvent(_NTO_TRACE_INSERTUSEREVENT,...).

This vdev also creates a thread that increments the value in the 32-bit location every second. When the guest reads from this location it will see that the value at the location has increased.

To use this vdev, you must include it like other vdevs in the build for your hypervisor host; for example, in your host buildfile you might have something like the following:

...
vdev-smmu.so
vdev-trace.so
vdev-8259.so
vdev-hpet.so
...

You must also include the vdev and its configuration in the configuration for the VM where it will be used; for example:

vdev trace loc 0xfa000000
	emit-logger
	emit-trace 12

where vdev trace specifies the vdev, loc 0xfa000000 specifies its guest-physical address, emit-logger instructs the vdev to emit to logger, emit-trace instructs the vdev to emit trace events, and 12 is the number to use for these events.

Note about the loc option

The loc option tells the qvm process where to put the device when it is assembling the VM that will host the guest (see “Common vdev options” in the User's Guide).

Note that, just as with physical devices:

The vdev is assigned a location in physical memory; however, because the vdev is a virtual device, its location is in guest-physical memory (see “Memory” in the User's Guide).
The device driver — in this case the guest-app pseudo-driver — must be told where to find the device (see guest-app.c in the vdev trace example on GitHub).