Configuring pass-through

pass

The pass option specifies that one of the following should be passed through from the hypervisor host domain to the guest:

a physical device, such as a PCI audio device
a data blob, such as an initial RAM disk (initrd) for a Linux guest

Until the next pass, vdev, or reserve option is encountered in the configuration, all intr and loc options that follow a pass option specify interrupts and locations for the pass-through device or component.

DANGER

Only one resident of a virtualized system is permitted access to a pass-through device at any one time. If the host owns a device that a guest requires as a pass-through device, the host must terminate its driver for the device before the guest can start its own driver for the device in its virtual environment.

Similarly, if one guest owns a device as a pass-through device, it must terminate this device driver in its virtualized space before another guest can use the device in its space.

In short, never configure the same pass-through device for more than a single guest.

For general information about pass-through devices, see “Pass-through devices” in the “QNX Virtual Environments” chapter.

Syntax:

[blob_type] pass [loc options] [intr guest_intr[=vector_number]]

Options:

blob_type

If blob_type is specified, then all the locations specified by the loc options that follow (until the next context) provide data of the type specified by blob_type to the guest that will be hosted in the VM being configured.

If blob_type precedes a load option, the qvm process copies the contents of the specified file into the guest system address space (see “load” in this chapter).

intr guest_intr[=vector_number]

The guest_intr option is associated with a host vector number, either vector_number if this value is specified, or the value specified by the hostvector option for the PIC identified by guest_intr.

When the host system delivers an interrupt on the host vector, guest_intr is delivered into the guest system.

The intr option is permitted if blob_type is specified, but it is meaningless, and therefore ignored.

loc location_spec[,length][,(+|-|r|w|x|c|e|m|d|n|s|t)*]|[=host_address]

The guest system is allowed pass-through access to the host-physical memory address. The loc option supports the following arguments:

location_spec:

The device type and information required to locate it. The table below presents supported device types, and the location information each type requires:

Device	Location
`io:`	Location in the x86 I/O space. This location is a port number. For example: io:4 specifies an x86 I/O device on port 4. The `host_address` argument is not used.
`mem:`	Guest-physical address of the pass-through (the address in memory as seen by the guest). For example: pass loc mem:0x2000,r=0x1000 specifies a read-only location at guest-physical address of `0x2000` and a host-physical address (address seen by the host) of `0x1000`.
`pci:`	The BDF (bus/device/function) where the pass-through PCI device should appear in the guest. `host_address` refers to the host device (vendor ID, device ID) being passed through. For example: pass loc pci:0:12.0=pci:0x8086/0x1234 passes a device with vendor ID `0x8086` and device ID `0x1234` to the guest at bus `0`, device `12`, and function `0` (multi-function). At present, you may choose the device and function numbers in the guest, but the bus number must be `0`. Per the PCI specification, some multi-function device must implement function `0`. If you want to make your PCI devices enumerable with non-zero function numbers, you can use the vdev-pci-dummy instance as a place-holder at function `0`. The `length` argument and the flags are not used. You can also specify PCI devices by Vendor ID and Device ID: `pci:vendor_id/device_id.` See “Example (graphics device)” for some configuration example configuration.

Device

Location

io:

Location in the x86 I/O space. This location is a port number. For example:

io:4

specifies an x86 I/O device on port 4.

The host_address argument is not used.

mem:

Guest-physical address of the pass-through (the address in memory as seen by the guest). For example:

pass loc mem:0x2000,r=0x1000

specifies a read-only location at guest-physical address of 0x2000 and a host-physical address (address seen by the host) of 0x1000.

pci:

The BDF (bus/device/function) where the pass-through PCI device should appear in the guest. host_address refers to the host device (vendor ID, device ID) being passed through. For example:

pass loc pci:0:12.0=pci:0x8086/0x1234

passes a device with vendor ID 0x8086 and device ID 0x1234 to the guest at bus 0, device 12, and function 0 (multi-function).

At present, you may choose the device and function numbers in the guest, but the bus number must be 0.

Per the PCI specification, some multi-function device must implement function 0. If you want to make your PCI devices enumerable with non-zero function numbers, you can use the vdev-pci-dummy instance as a place-holder at function 0.

The length argument and the flags are not used.

You can also specify PCI devices by Vendor ID and Device ID: pci:vendor_id/device_id.

See “Example (graphics device)” for some configuration example configuration.

length

The number of bytes allocated.

access type

The access type specifies the types of access permitted to the guest. This argument must follow the length argument, and may be a combination of the following:

Argument	Description
`+`	Attributes following are added to the region (this is the initial state).
`-`	Attributes following are removed from the region.
`r`	Read
`w`	Write
`x`	Execute
`c`	Cachable
`e`	Report exception
`m`	Usable as system memory (implicitly specifies `"+rwxcst`).
`d`	Device uses DMA.
`n`	Device doesn't use DMA.
`s`	Region can be the source of a DMA request.
`t`	Region can be the target of a DMA request.

If no access types are specified, rw is assumed.

Note: If a device uses DMA, you can use the d attribute so that if smmuman isn't running, the qvm process instance for which the pass-through device is intended will refuse to include the device in its VM configuration, and refuse to start.

host_address

The physical address of the device on the system (i.e., as seen by the hypervisor host). For some types of location (e.g., mem:), you can use location_spec to provide the guest with an address different from the host-physical address of the device on the system; the device is at location A, but the guest sees it at location B.

Note: Not all device types (e.g., IO devices) can be relocated to different locations between the guest and the host.

The qvm process recognizes the following data types (blob_type) specified before a pass option:

Type	Notes
acpi	Only available for x86. Any loc options following will be interpreted as providing additional ACPI tables to the guest system.
data	Recognized, but not relevant for pass-through.
fdt	Any loc options following will be interpreted as providing an FDT binary blob to the guest system. For information about FDTs, see www.devicetree.org
guest	Any loc options following will be interpreted as providing a guest OS boot image to the guest system.
initrd	Any loc options following will be interpreted as providing an initial RAM disk (initrd) image to the Linux guest system.
raw	Recognized, but not relevant for pass-through.

Example (Linux RAM disk image)

The following provides an initrd RAM disk image to the Linux system from host system memory:

initrd pass loc 0xB1234000,0x4000000,rc=0xB7654000

The above creates a RAM disk of 0x4000000 bytes located in the host-physical memory at address 0xB1234000, accessible by the guest at address 0xB7654000 in guest-physical memory. This region is cacheable (c) and read-only (r).

Note:

It is your responsibility to locate the data in the guest system in accordance with the guest OS's rules.

You may prefer to use the load option to pass a Linux initrd RAM disk to a guest domain. For example: initrd load ./myinitrd.gz (see “load” in this chapter).

Example (audio device):

The following passes through the audio-related devices on the Gordon Ridge MRB:

pass pci:0:14.0 pass pci:0:23.0

Since these are PCI devices, the configuration uses BDF numbers rather than memory addresses.

Example (graphics device)

Assuming that you have a screen driver and the other components you need to run graphics on the board, the following could be used to pass through a graphics device on the Gordon Ridge MRB:

Modify your VM configuration file to create a PCI pass-through device:
```
pass loc pci:0:2.0=pci:0:2.0 
vdev pci-dummy 
    clone pci:0:31.0
```
Start the guest with the new VM configuration.
From your desktop host, start QNX Screen in the guest, using the -c option to point screen to the DRM manager:
```
screen -c /usr/lib/graphics/intel-drm/graphics.conf
```

About this example configuration

In this example we use the 0:2.0 BDF (bus/device/function) location, which Intel has designated for integrated graphics:

The value to the left of the equals sign passes the host BDF through to the guest.
The value to the right of the equals sign ensures that the device will appear at the specified location on the guest's PCI bus.

We specify the BDF value in both places to ensure that the qvm process instance hosting the guest presents the same BDF location (0:2.0) to the guest, in case code in the guest assumes this Intel-designated BDF.

The dummy vdev is not strictly required. However, the device driver usually uses this vdev to identify the display adapter, so using the dummy vdev allows us to expose the correct vendor and device IDs without providing any further (and unneeded) functionality.

See also loc above, and “vdev pci-dummy” under “Configuring vdevs” in this chapter.

Using FDT information when configuring pass-through devices on ARM platforms

In a hypervisor system, devices available to a guests are specified in the configuration for its VM (i.e., in the the configuration for the hosting qvm process instance).

On ARM platforms, some OSs (e.g., Linux) may also require an FDT with information about devices that are passed through to them. In this case, you must pass an FDT describing the pass-through devices up to the guest:

Start with the FDT supplied with your hardware platform.
If the FDT isn't available in human-readable format, use a dtc utility to convert the binary FDT into a *.dts human-readable file.
Edit the human-readable FDT file, removing all entries except the entries describing the devices you will pass through to the guest.
Use your dtc utility to create a new FDT binary file (*.dtb) from your edited file.
In the configuration for the VM that will host the guest that needs the FDT information, use the fdt load option to pass the new FDT binary file to the guest when it starts (see “blob_type” above).

A dtc utility is available from https://git.kernel.org/cgit/utils/dtc/dtc.git; a Device Tree Compiler Manual can be found at web.mit.edu/freebsd/head/contrib/dtc/Documentation/manual.txt.