The Basics: vdev trace

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

emit-trace trace_num

Optional. Write output to the hypervisor host's kernel trace buffer. The mandatory trace_num argument specifies the trace number to use.

Note that the loc option may be set only to mem (see the factory_flags field description in the vdtrace_factory reference).

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