Configure pass-through physical devices or specified types of data blobs from the host to a guest
[blob_type] pass [loc options] [intr guest_intr[=vector_number]]
The guest system is allowed pass-through access to the host-physical memory address. The loc option supports the following arguments:
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. This is the default device type. |
| 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 with just the Vendor ID and Device ID: pci:vendor_id/device_id; for example: pass loc pci:0x8086/0x1234 See “Example (graphics device)” for some configuration examples. |
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. If you are using the QHS, you must specify either this argument or n. |
| n | Device doesn't use DMA. If you are using the QHS, you must specify either this argument or d. |
| s | Region can be the source of a DMA request. |
| t | Region can be the target of a DMA request. |
If a device uses DMA, you should use the d attribute, and specify at least the r and w access types. 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 proceed as specified by the safety option in the VM's configuration.
Since in a QHS system you must specify either d or n, you must also always specify other access types such as r and w.
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.
For example, the following sets the pulse priority to 67 for interrupt 89 for the current passthrough device:
pass
sched 67 intr gic:89
Similarly, the following sets the pulse priority to 44 for interrupts for the current passthrough device:
pass
sched 44 loc pci:0:3.0
Note that in this last example no interrupt is specified because for PCI devices interrupts can be implicit (see “Common vdev options” in the “Virtual Device Reference” chapter).
The pass option specifies that one of the following should be passed through from the hypervisor host domain to the 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.
In general, 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 the device driver before the guest can start a 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, you should never pass a DMA device through to more that one guest, and only in exceptional designs should you pass a non-DMA device through to more than one guest.
If you believe that your design requires that a non-DMA device be passed through to more than one guest, contact your QNX representative.
The qvm process recognizes the following data types (blob_type) specified before a pass option:
acpi pass
fdt pass
guest pass
initrd pass
For general information about pass-through devices, see “Pass-through devices” in the “Understanding QNX Virtual Environments” chapter.
If you are implementing a system with QHS, you must explicitly specify the DMA status of every pass-through device you add to your system; that is, you must include either d (DMA device) or n (not DMA device) in the access type following the length argument. For example:
pass loc mem:0x2000,0x1000,rn=0x1000
specifies that the device isn't a DMA device.
If you specify neither d nor n for the access type (or if you specify both), the qvm process instance assembling the VM will turn off the system's safety status indicator, and proceed as specifed by the safety option in the VM's configuration.
A DMA device may be passed through to only one guest. If you configure a VM to give a guest access to a DMA device that has already allocated to another VM, the hypervisor will print an error and move to its (global) DSS (see “Design Safe States” in the “QNX Hypervisor for Safety” chapter).
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).
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).
The following passes through the audio-related devices:
pass pci:0:14.0 pass pci:0:23.0
Since these are PCI devices, the configuration uses BDF numbers rather than memory addresses. The example assumes a board with the specified physical devices at the specified locations.
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:
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
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
In this example we use the 0:2.0 BDF (bus/device/function) location, which Intel has designated for integrated graphics:
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.
The example assumes a board with the specified physical devices at the specified locations.
See also loc above, and vdev pci-dummyin the “Virtual Device Reference” chapter.