Configuring vdevs

Note:

Guest OSs expect certain vdevs to be present in their VM, just as OSs running on a non-virtualized system expect physical devices to be present on the board.

Similarly, just as in a non-virtualized system the device driver in an OS must match the hardware device on the physical board, in a virtualized system the device driver in the guest must match the vdev.

The QNX Hypervisor supports vdevs that enable the sharing of audio and graphics physical devices. For more information, please contact your QNX representative.

Implicit vdevs

An implicit vdev is a vdev that is in the qvm process code, so it is present even if you don't specify it. You need to specify this vdev only if you don't want to use the default values for its options. Implicit vdevs are marked as such in the descriptions below.

Syntax

All virtual devices specified in a qvm configuration are preceded by the vdev option, which identifies the component as a virtual device. Its mandatory vdev_type argument specifies the device type. The syntax for the vdev option is:

vdev vdev_type

For example, the following creates for the current VM a vdev that emulates an Intel 8254 timer chip:

vdev timer8254
	intr myioapic:0

Common vdev options

The options described below may apply to more than one type of vdev. If the option is described in the vdev description, refer to that description:

hostvector vector_number: Applies only to Programmable Interrupt Controller (PIC) vdevs. This option sets the associated host vector number of the first line of the current vdev. This number is used by InterruptAttach() and InterruptAttachEvent() (see the C Library Reference). The PIC input lines that follow are sequentially assigned to host vector numbers.; This option is needed only if any of the PIC guest interrupts will be marked as pass-through. If hostvector isn't specified, its value defaults to the previous PIC device's hostvector number, plus this previous devices' number of lines. If this is the first PIC specified, hostvector defaults to 0 (zero).
intr guest_intr: The guest interrupt of the current virtual device is set to guest_intr, in two parts, separated by a colon (e.g., intr gic:40).; For PCI devices that use an interrupt, if you don't set a number for guest_intr, this number is automatically assigned. For non-PCI devices (e.g., MMIO devices), you must set this option.; For more information, see “Guest interrupts” in this chapter.
loc location_spec: The current virtual device has its location in the guest-physical address set to location_spec. For non-PCI devices (e.g., MMIO devices), you must set this option.
name name: An optional name used by the virtual device (vdev) for further configuration. Each vdev may have its own name option. Currently this option is relevant only for peer vdevs, such as virtio-net, and for PIC devices. For certain PIC devices, the name may be referenced in guest_intr specifications to say that the device is connected to a given PIC input line.; See the sample *.qvmconf files for details on how the name option relates to specific PIC hardware. See “vdev virtio-net” below for more information about using the name option when configuring peers in a network.

Note:

The qvm configuration parsing and validation allows colons (“:”) in the vdev name option, because they may be used with some vdevs, such as virtio-net. However, this character is not supported for PIC vdevs (e.g., vdev gic, vdev ioapic). If you use a colon in a PIC device name, you will get an error when you attempt to refer to it in the configuration for another vdev (e.g., in an intr option).

vdev 8259

x86 only. Emulates minimal functionality of an Intel 8259 programmable interrupt controller (PIC). It can't be used as a virtual PIC device, but its presence is required for guest OSs to be able to boot.

Option:

loc: The base address of the registers (default space is io:).

vdev gic

ARM only. Emulate an ARM standard Generic Interrupt Controller (GICv2). Implicit.

Since the gic vdev is an implicit vdev, you need to add configuration information for it only if you want to change the default behavior, or add information to be used in the event that the information is not available from the board, or incorrect.

Options:

gicc guest_address

Provide the guest-physical address of the virtual GIC's CPU registers.

host-gicd host_address

Provide the host-physical address of the GIC distributor registers, in the event that the gicd entry in the host's system page asinfo section is missing or incorrect.

host-gich host_address[/cpu/spacing]{,host_address[/cpu/spacing]}

Provide the host-physical address of the GIC hypervisor control registers, in the event that the gich[.cpunum] entry in the host's system page asinfo section is missing or incorrect.

If the /cpu/spacing information is present, the entry provides a direct map address to the physical CPU specified by cpu. If the /cpu/spacing information isn't present, the entry provides the common base address that allows each physical CPU to access its corresponding GICH register set.

host_address: The host-physical address of the current physical CPU's GICH registers.
cpu: If present, the number of the physical CPU whose registers are located at the address specified by host_address.
spacing: If present, the number of bytes to increase the offset to get the address of each subsequent physical CPU's registers.

See “Example GICv2 configuration” below.

host-gicr host_address

GICv3 and more recent only. Provide the host-physical address of the GIC redistributor registers, in the event that the gicr entry in the host's system page asinfo section is missing or incorrect.

host-gicv host_address

Provide the host-physical address of the GIC virtual CPU registers, in the event that the gicv entry in the host's system page asinfo section is missing or incorrect.

loc address

Provide the guest-physical address of the GIC distributor registers.

msi address, base_intr,num_intrs

Create a Message Signaled Interrupt (MSI) device frame at the physical address specified by address.

The base_intr argument specifies the first interrupt number the frame allows, and num_intrs specifies the number of interrupts allowed. Thus, the highest interrupt allowed is base_intr + num_intrs - 1.

If none of gicc, gicd, or loc is specified, the qvm process assumes the ARM foundation model addresses: gicc=0x2f002000, gicd=0x2f001000 (GICv2).

If some addresses are specified but others missing, the qvm process places the gicc registers after the gicd registers (GICv2).

For more information about the system page asinfo (Address Space Information) section, see “asinfo” in the “System Page” chapter in Building Embedded Systems.

Example GICv2 configuration

The following is the configuration for a vdev gic for a Renesas R-Car H3 board GICv2:

vdev gic
    host-gicv 0xf1060000
    host-gich 0xf1040000,0xf1050000/0/0x200

where host-gicv 0xf1060000 specifies the host-physical address of the GIC virtual CPU registers, and host-gich specifies the location of the hypervisor control (GICH) registers:

host-gich 0xf1040000,0xf1050000/0/0x200 – the host-physical address of the GICH registers that the hardware's virtualization assistance allocates to the current physical CPU
host-gich 0xf1040000,0xf1050000/0/0x200 – the host-physical address of physical CPU 0's GICH registers
host-gich 0xf1040000,0xf1050000/0/0x200 – the CPU number whose GICH registers are at 0xf1050000, in this case CPU 0
host-gich 0xf1040000,0xf1050000/0/0x200 – the spacing between the physical CPU registers. With CPU 0 at 0xf1050000 and a spacing of 0x200 as in this example, the host-physical address to access the registers for physical CPU 1 is 0xf1050200, the address to access the registers for physical CPU 2 is 0xf1050400, and so on.

Other boards might use different values. Check your board manufacturer's documentation.

vdev hpet

x86 only. Provides a High-Precision Event Timer (HPET) device to the guest.

This device is exposed to the guest through an ACPI device. If this device is provided in the VM (qvm process instance), the guest may use HPET services. For example, for a QNX Neutrino 7.0 guest, the startup-apic in a boot image will search for and use the virtualized HPET timer if it exists.

Currently, only the first HPET vdev is exposed, and there is no way for the guest to discover the address of any additional HPET vdev.

This vdev supports up to 32 timers. The guest can't change the IRQ assignment of each timer, but MSI is supported.

Options:

frequency value

Use the given frequency instead of the default 14318180 Hz.

Currently, the virtual device uses an integer divisor to match with the hypervisor's internal counter, which will introduce a skew.

intr intr_def[,intr_def[,intr_def[,...]]]

Define timers and assign interrupt lines to them. For complex reasons and to support legacy operations, a Linux guest will expect the first timer to be on IRQ 0, and a QNX guest will expect it to be on IRQ 2. The second timer should be set to IRQ 8 in both cases, and any additional timer can use any other interrupt.

If you specify multiple interrupts (timers), you can:

Specify the intr option once, followed by multiple definitions; for example:
```
vdev hpet intr ioapic:2,ioapic:6
```
Specify an new intr option for each definition; for example:
```
vdev hpet intr ioapic:2 intr ioapic:6
```

Mix the two forms; for example:

vdev hpet intr ioapic:2,ioapic:6 intr ioapic:10

legacy-free

Clear the “legacy” bit (LEG_RT_CA) in the main ID register. Specifically, clearing or not clearing the bit determines where Timer0 interrupts may be routed.

If you specify this option, the guest can't make any assumptions about routing of Timer0 and Timer1.

If you don't specify this option, the guest can assume that Timer0 will be routed to IRQ2 and Timer1 to IRQ8. Note the following, however:

Not specifying the legacy-free option doesn't enforce the assumed routing (Timer0 to IRQ2, Timer1 to IRQ8). You must ensure that your configuration specifies the correct routing.
A Linux guest will always assume that Timer0 is routed to IRQ0, because this is usually the case. Though this routing warrants a redirection entry in the Multiple APIC Description Table from ACPI, Linux ignores the absence of this redirection entry.
The above means that if you don't specify the legacy-free option, the first two intr instances in the hpet vdev configuration should be as follows, for QNX:
```
vdev hpet intr ioapic_name:2,ioapic_name:8
```
and for Linux:
```
vdev hpet intr ioapic_name:0,ioapic_name:8
```

loc

The base address of the HPET registers.

vdev ioapic

x86 only. Emulate an Intel I/O APIC programmable interrupt controller.

Options:

hostvector vector: Associate the first guest interrupt of the I/O APIC with the host interrupt number specified by vector; associate the second guest interrupt with vector +1, etc.; If a guest interrupt is marked as a pass-through target and no host vector is explicitly provided, this association provides the host interrupt vector number to use for the guest interrupt.
intr apic: Downstream interrupt to raise.
loc addr: Base address of the device registers.
name name: Name to use for upstream interrupts referencing this PIC.

vdev mc146818

x86 only. Emulates the Motorola 146818 real time clock chip.

Options:

loc: The base address of the device registers (default space is io:).
reg register_number,value: Set the NVRAM register_number register to value.

vdev pci-dummy

x86 only. Provides a read-only, inactive PCI device. Such a device may be needed to expose a specific pair of PCI identifiers to help the guest identify a hardware platform.

The following registers are considered: Vendor_ID, Device_ID, Revision_ID, Class_Code[0], Class_Code[1], Class_Code[2], Header_Type, Sub_Vendor_ID, Sub_System_ID.

Options:

clone host PCI device

Use the specified PCI device as a template for the virtual device, and copy the values of the named registers from the host into what the guest will see.

reg offset/size=value

Set a specific configuration space register. For example:

vdev pci-dummy 0/4=0xFFFF

sets the configuration space register at offset 0 and size 4 (bytes) to 0xFFFF.

Permitted sizes are 1, 2, 4 and 8 bytes.

reg name=value

Equivalent to the reg offset/size option above, but uses one of the known names (e.g., Vendor_ID). The size is implied by the name, so you don't have to specify it.

vdev pci-host-bridge

Creates a PCI host bridge device. Implicit.

Option:

ecam address: Set the location of the PCI ECAM space to addr. If not specified, the qvm process instance will automatically choose a location, and inform the guest via ACPI or FDT.

vdev pckeyboard

x86 only. Minimal emulation of an IBM PC keyboard controller: just enough to let QNX reboot.

Option:

loc: The base address of the device registers (default space is io:).

vdev pl011

ARM only. Emulates a PL011 serial device.

Option:

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 (e.g., delayed 0), try only once to find the device on the host. If the argument is set to “forever” (e.g., delayed forever), never time out (i.e., 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.; Use < (input) or > (output) to specify if the host device specified by host_device_name provides input or receives output, as you would in a shell.

vdev progress

ARM and x86. Whenever the guest system references the address (guest-physical address) specified by this device's loc option (see “loc” under “Common vdev options” above), the hypervisor outputs a report to whatever destination is specified by the logger option's info filter (see logger above).

Options:

full: Generate a full register dump on each reference.
loc addr: Report when the guest reads or writes the guest-physical address specified by addr.
smc instr: ARM only. Generate a report whenever the guest executes an SMC instruction with the immediate value specified by instr.
cpuid instr: x86 only. Generate a report whenever the guest executes a CPUID instruction with the EAX equal to the value specifed by instr.

vdev ser8250

ARM and x86. Emulates the Intel 8250 UART.

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 (e.g., delayed 0), try only once to find the device on the host. If the argument is set to “forever” (e.g., delayed forever), never time out (i.e., 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.; Use < (input) or > (output) to specify if the host device specified by host_device_name provides input and/or receives output, as you would in a shell.
intr intr: Signal intr for device interrupts.
loc addr: The base address of the device registers to addr. Default space is io:.
sched priority: Set the priority specified by priority for pulses indicating that input is available.

vdev shmem

ARM and x86. Provides an inter-guest system shared memory device. Normally this device appears as a PCI device, but if the loc and intr options are specified, the guest will see it as a memory-mapped I/O (MMIO) device at the specified location.

Options:

allow fnpattern: Allow the guest to create or attach to any shared memory region whose name matches the pattern specified by fnpattern.; You can repeat this option multiple times to specify whatever name patterns you need to manage the guest's access to shared memory regions.
create name,size: Pre-create a shared memory object named name of size bytes.; You can repeat the create option multiple times to pre-create multiple shared memory regions.
deny fnpattern: Deny the guest access to any shared memory region whose name matches the pattern specified by fnpattern.; You can repeat this option multiple times to specify whatever name patterns you need to manage the guest's access to shared memory regions.
intr intr: If the loc option is specified, you must also specify the value of intr; this sets the guest interrupt that is generated when another guest sends a notification of an update to shared memory.
loc addr: The base address of the factory page for the vdev. If addr isn't specified, the vdev appears as a PCI device, and the qvm process automatically assigns the factory page location and adds this location to the PCI BAR register.; If you specify this option, you must also specify the intr option (see above).
sched priority: Use the priority specified by priority for pulses indicating that input is available.

Restrictions list

You can use the allow and deny options to establish a list of shared memory regions the guest may and may not access.

The fnpattern argument for these options can use wildcards, with the same syntax as shell file name expansion. For example, specifying allow test* will allow the guest to create or attach to any shared memory region whose name begins with test. Similarly, deny live* will forbid the guest access to any shared memory region whose name begins with live.

If you use the allow option, the configuration will include an implicit deny* check at the end of the restrictions list. The guest will be denied access to all shared memory regions not specified by allow options. For example:

vdev shmem
	allow test*
	allow pluto

allows the guest to create or attach to any shared memory region whose name begins with test, as well as to the shared memory region called pluto. The guest is denied access to all other shared memory regions.

Conversely:

vdev shmem
	deny live*
	deny pluto

denies the guest access to any shared memory region whose name begins with live, as well as to the shared memory called pluto. The guest is allowed to attach to any other shared memory region, however.

Finally, you can use the allow and deny options together to specify exactly which shared memory regions a guest may or may not access. For example:

vdev shmem
	deny pluto
	allow pluto*

denies the guest access to a shared memory region called pluto, but allows it to connect to other shared memory regions whose names begin with pluto (e.g., plutoplanet).

Note: If you use the command line to enter vdev shmem configuration information that includes allow or deny options with wildcard entries for fnpattern, use the “\” escape character before the asterisk to get the instruction through the shell (e.g., vdev shmem allow test\*).

For more information about using the shared memory vdev, see “Memory sharing” in the “Using Your Hypervisor System” chapter.

vdev timer8254

x86 only. Emulates the Intel 8254 timer chip.

Options:

frequency input_freq_in_hz: Set the input frequency to the device, in hertz.
intr intr: Set the interrupt generated when a timer expires to intr.
loc addr: Set the base address of the device registers to addr (default space is io:).

vdev virtio-blk

ARM and x86. Provides the standard VirtIO interface for block devices. Normally this 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.

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 (e.g., delayed 0), try only once to find the device on the host. If the argument is set to “forever” (e.g., delayed forever), never time out (i.e., keep trying to find the device on the host).
hostdev [<]host_filename: Provides the name of the host file to use for the contents of the device.; A “<” symbol in front of host_filename indicates that device contents will be enforced as read-only (e.g., hostdev </dev/hd0 will make /dev/hd0 read-only to the guest). The default (no <) is read/write access.
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 standard version.
loc addr: Set the base address of the device registers to addr. Not required if the vdev appears as a PCI device.

vdev virtio-console

ARM and x86. Provides the standard VirtIO 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 can be very useful on systems where console interaction to a guest is slow over a regular console or serial terminal. The virtio-console vdev is a buffering driver; most often it is used when a guest is interacting with the host over an emulated UART. For example, many embedded ARM boards will use the PL011 serial port as a terminal for output from Linux kernel.

The virtio-console vdev requires:

A device to run on. For example, for ARM systems, the virtio-console vdev is usually used for buffering the PL011 serial device.

The PL011 is slow and will have slow output becausue 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. Both Linux 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.

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 (e.g., delayed 0), try only once to find the device on the host. If the argument is set to “forever” (e.g., delayed forever), never time out (i.e., 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.; Use < (input) or > (output) to specify if the host device specified by host_device_name provides input or receives output, as you would in a shell.
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 standard version.
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.

vdev virtio-net

Provides the standard VirtIO interface for network 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.

Options:

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 standard version.
loc addr: Set the base address of the device registers to addr. If this option isn't specified, the vdev appears as a PCI device.
mac mac_address: Use the mac_address as the Ethernet address for the virtual device in the guest.
name name: Set this side of a peer-to-peer networking connection to name.
peer path: Directly connect to the peer device path (usually of the form /dev/qvm/vm/vnet). In this case, specifying mac and name is highly recommended.; For the name, use the name (system_name) of the system with the peered device (see the “system” component).
peerfeats mask: VirtIO Network feature bits that should be assumed to be supported by the peer, since it is impossible to do proper negotiation (see below).
tapdev host_device_name: Use the host_device_name as the source and/or destination of network packets to the device.

Using the peerfeats option

Feature bits are used to specify the features that are exposed to a peer in a network. They can be defined for each individual virtio-net interface (i.e., each peer connection can have its own feature set).

Peerfeats defines the maximum set of features that will be negotiated between the two TCP stacks connected as peers. The peerfeats bits are specified in Virtual I/O Device (VIRTIO) Version 1.0, Section 5.1.3 (see the document repository at oasis-open.org). This maximum set of bits is currently set at 0x7fc3. The current QNX Neutrino OS TCP stack provided with QNX SDP 7.0 supports a subset of the maximum set. This subset is 0x19c3, or:

0001 1001 1100 0011

with the least-significant bit (bit zero) on the right.

Of particular interest are the bits that support checksumming and Transmit Segmentation Offload (TSO); both these features are supported in the QNX TCP stack (see the table below).

The default peerfeats value for a peer interface is 0x0000.

When you configure the interfaces to connect guests as peers, you should limit the feature bits to the features supported by the guests. For example, if you are configuring two QNX Neutrino OS 7.0 guests to connect as peers, you should specify 0x19c3 as the value for the peerfeats option's mask in the VM configuration for each guest.

When using the peerfeats option:

If you know the peerfeats of both the near-end and the far-end peer interfaces, specify it with the peerfeats option in the VM configurations for each guest.
If you don't know the capabilities supported by both peers, you can set the peerfeats mask to 0x7fc3 and let the connected TCP stacks negotiate the features they will use (check the documentation for your Linux, QNX Neutrino, or other OS for details).
If you are configuring a peer connection to a QNX io-pkt-* bridge, you must set the peerfeats option to 0x0000 (zero) to disable all features.

This is required so that the host bridge does not incorrectly discard or delay packets.

The recommended feature set is:

Bit	Name	Feature
7	VIRTIO_NET_F_GUEST_TSO4	Driver can receive TSOv4.
8	VIRTIO_NET_F_GUEST_TSO6	Driver can receive TSOv6.
11	VIRTIO_NET_F_HOST_TSO4	Device can receive TSOv4.
12	VIRTIO_NET_F_HOST_TSO6	Device can receive TSOv6.

For more information about using the virtio-net vdev, see “Networking” in the “Using Your Hypervisor System” chapter.

vdev wdt-ib700

x86 only. Emulates the watchdog found on the IB700 board to provide a watchdog for guests running on x86 platforms.

Options:

loc addr: The base address of the registers in guest-physical memory (default space is io:). The value specified for addr must be the same as the value specified for the guest wdtkick's -a option.; If this option isn't specified, the configuration assumes the default address: 0x441.

For more information about watchdogs in a QNX Hypervisor system, see “Watchdogs” in the “Using Your Hypervisor System” chapter.

vdev wdt-sp805

ARM only. Emulates an SP805 watchdog to provide a watchdog for guests running on ARM platforms.

Options:

loc addr: The base address of the registers in guest-physical memory. This value must be the same as the value specified for the guest wdtkick's -a option.; If this option isn't specified, the configuration assumes the default address: 0x1C0F0000.
frequency hz: The clock-cycle frequency that corresponds to the effective watchdog frequency as described in the SP805 specifications. This value is used to calculate the watchdog timeout. It is specified here in hertz (Hz).; If this option isn't specified, the configuration assumes the default: 25000000 (25 MHz).

Note:

Emulating the hardware SP805 watchdog device's behavior, the emulated SP805 watchdog device counts down twice before it triggers a SIGQUIT to terminate the hosting qvm process instance. Thus, if your watchdog period is set to three seconds, the effective watchdog clock period (when the SIGQUIT will be triggered) is six seconds.

For more information about how an SP805 watchdog calculates the effective watchdog clock period, see the SP805 specifications.

For more information about watchdogs in a QNX Hypervisor system, see “Watchdogs” in the “Using Your Hypervisor System” chapter.