vdev virtio-console

Synopsis:

vdev virtio-console options

Options:

delayed seconds|forever

If specified, delay opening the device in the host until it is first referenced by the guest.

If the device isn't found in the host, continue trying for the number of seconds specified by seconds before timing out (e.g., delayed 5). If seconds is set to 0 (i.e., delayed 0), try only once to find the device on the host. If the argument is set to forever (i.e., delayed forever), never time out, just keep trying to find the device on the host.

hostdev [<|>]host_device_name

Use the host_device_name as the source and/or destination of characters to the device.

You can use one of < (input) or > (output), so the host device specified by host_device_name provides input or receives output. If you specify neither < nor >, the device is used for both.

You can define multiple hostdev options, to specify separate input and output devices:

hostdev <myhostinputdevice
hostdev >myhostoutputdevice

Or, you can specify the same device for both input and output:

hostdev myhostdevice

intr intr

Signal intr for device interrupts. Not required when the vdev appears as a PCI device.

legacy

Provide the VIRTIO legacy interface (0.9.5) rather than the 1.0 or later standard versions.

loc addr

Set the base address of the device registers to addr. Not required if the vdev appears as a PCI device.

sched priority

Use the priority specified by priority for pulses indicating that input is available on the host device.

tx-backpressure

Prevent the vdev from dropping data being transmitted when the system is very heavily loaded. Enabling this option applies backpressure on the guest driver in this situation by forcing it to wait if the vdev can't buffer more data. Note, though, that this option has no effect on the policy used within the guest driver, and the drivers for some guest OSs are known to drop data sometimes and perform long spin waits at other times.

CAUTION:

Some guest OSs will spin-wait for virtio-console data to be sent. When the host system has very high CPU usage, the delay in passing data between the guest and the host can cause the guest OS to spin excessively, further increasing the host CPU load. To protect against this, by default, this option (and hence, the backpressure) is disabled, and the virtio-console vdev relies on buffering to handle transient data. It is still possible that data gets dropped if the combined buffering of the guest driver, the vdev, and the host device, are exceeded.

For a list of options available to all vdevs, see Common vdev options at the beginning of this chapter.

Description:

ARM and x86. The virtio-console vdev provides an interface for console devices. Normally the device appears as a PCI device, but if you specify the loc and intr options, the guest will see it as a memory-mapped I/O device at the specified location.

The virtio-console vdev is useful on systems where console interaction to a guest is slow over a regular console or serial terminal. This vdev is a buffering driver; most often it's used when a guest is interacting with the host over an emulated UART. For example, many ARM boards use the PL011 serial port as a terminal for the Linux kernel's output. Using this vdev to buffer PL011 data reduces emulation overhead.

The virtio-console vdev requires:

• A device to run on. For example, the PL011 serial device is slow and will have slow output because there are many interactions with the virtualized serial port. By using the virtio-console vdev on top of the PL011 device, the console interaction is very fast both on input and output due to the virtio-console vdev's larger and more efficient buffering.
• A virtual driver running in the guest. Linux, Android, and QNX guests need a VIRTIO driver to be running. For example, in a Linux guest, configure the guest to include the virtio-console kernel module, and specify console=hvc0 in the cmdline option in the qvm configuration for the VM.