vdev virtio-console

Provide the standard VIRTIO interface for console devices

Synopsis:

vdev virtio-console options

Options:

delayed seconds|forever
Delay opening the host device until it is first referenced by the guest.
If the device isn't found in the host, keep trying to find the device for the number of seconds given 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. If it is set to forever (i.e., delayed forever), never time out and just keep trying to find the device.
hostdev [<|>]host_device_name
hostdev >"|command_string"
The first form means use the host_device_name as the source and/or destination of characters for the vdev.

For a given hostdev option, you can use one of < (input) or > (output) so the host device specified by host_device_name provides input or receives output.

To specify separate input and output devices, you can use multiple hostdev options: 
hostdev <myhostinputdevice
hostdev >myhostoutputdevice
Or, you can use neither < nor > to indicate the same device is used for both input and output: 
hostdev myhostdevice
The second form means redirect the vdev's output to a process created by executing command_string. The command string must be immediately preceded by the pipe character (|) and then surrounded by double quotes, as shown here: 
hostdev >"|/guests/tee /guests/pipe_test.log"

Here the vdev's output is sent as input to the /guests/tee program which takes the pathname of a log file, /guests/pipe_test.log, as an argument. The command you name can do whatever you want; for example, it could perform logging with file size limits. For further explanation, refer to Logging output below.

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.
name device_path
Specify a device path that you can write commands to in order to control the size and number of log files created for storing the vdev's output. For example, you can issue a command to reopen a log file (i.e., truncate it to zero bytes) after you noticed it was getting too big. For information about performing this log rotation, refer to Logging output below.
sched priority
Use the priority specified by priority for pulses indicating that input is available on the host device.

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.

This vdev is useful on systems where console interaction to a guest is slow over a regular console or serial terminal. The 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 has slow output because it interacts a lot 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 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 instance, you should configure a Linux guest to include the virtio-console kernel module, and specify console=hvc0 in the cmdline option in the qvm configuration for the VM.
The vdev offers the following features:
  • VIRTIO_CONSOLE_F_MULTIPORT — currently, this is limited to a single port, and the name of the port is the one given to the vdev instance with the name option.
  • VIRTIO_CONSOLE_F_EMERG_WRITE — the driver can use an emergency write to output a single character without initializing virtqueues or completing feature negotiation. This is handy for providing debugging output early during bootup and for reporting fatal errors (e.g., VIRTIO ring corruption).

Logging output

You can write the vdev output to log files and manage their size and number. There are two ways to do this:
  • Redirect the output to a separate process that manages log files
    You can define the hostdev option to send the vdev output to a separate process. The syntax for doing so is shown in the option's description above. This interface doesn't assume any specific functionality and thus gives you maximum flexibility in generating and managing log files. For example, the other process can:
    • implement a log file rotation scheme (e.g., the Linux utility logrotate could be ported to QNX OS and named in the hostdev command)
    • generate a single log file and truncate it when it exceeds a certain size
    • generate log files and then compress and/or encrypt them as desired
  • Configure the vdev to offer manual user control of log files
    You can define the hostdev option to specify a log file, and the name option to specify the path for receiving commands that manage that file. Suppose you have the following configuration: 
    vdev virtio-console
    hostdev >/guests/virtconsole.log
    name virt_console_name

    The vdev output will then be stored in the log file /guests/virtconsole.log and the vdev can then react to commands sent to a device path that's based on the qvm system's name and that ends with virt_console_name.

    The user can manually control log file rotation using the following method:
    1. Move the current log file to a new name (e.g., mv current-logfile saved-logfile).

      The file continues to accumulate log output even though it has the new name. Note that the new file must be in the same filesystem as the current one.

    2. Send the 0 command to the appropriate device path: 
      echo 0 > /dev/qvm/qnx-guest-1/virt_console_name

      The qvm process closes the original log file and opens a new one with the original name. At this point qvm is using the new file for logging and the user can do what they want with the saved one.

      The access permissions for the device path given in name are defined using a security policy. For more information, refer to the Security Policies chapter of the System Security Guide.

    This design avoids race conditions between the vdev process that writes to the file and another process that truncates the file when it gets too big.

Page updated: