Changeset 36647 in vbox

Timestamp:

Apr 11, 2011 7:48:39 PM (14 years ago)

Author:

vboxsync

Message:

PCI passthrough: initial version of docs

File:

• trunk/doc/manual/en_US/user_AdvancedTopics.xml (modified) (1 diff)

trunk/doc/manual/en_US/user_AdvancedTopics.xml

@@ -537 +537 @@
     command:<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen></para>
   </sect1>
+
+  <sect1 id="pcipassthrough">
+    <title>PCI passthrough</title>
+
+    <para>When running on Linux hosts, with recent enough kernel (at least version 
+      <computeroutput>2.6.31</computeroutput>) experimental host PCI devices 
+      passthrough is available.<footnote>
+        <para>Experimental support for PCI passthrough was introduced with VirtualBox
+        4.1.</para>
+      </footnote> Essentially this feature allows to use physical PCI devices
+      on host directly by the guest, even if host doesn't have drivers for this 
+      particular device.</para>
+
+    <para>To be fully functional, PCI passthrough support in VirtualBox depends upon 
+    IOMMU hardware unit, which is not yet too widely available. To be exact,
+    if device uses bus mastering (i.e. performs DMA to the OS memory on its own), then
+    IOMMU hardware is needed (otherwise such DMA transactions may override wrong physical memory address,
+    as device DMA engine is programmed using device-specific protocol to perform memory transactions).
+    IOMMU functions as translation unit, mapping physical memory access requests from the device,
+    using knowledge of guest physical address to host physical addresses translation rules.</para>
+
+    <para>Intel's solution for IOMMU is marketed as "Intel Virtualization Technology for 
+      Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So please check if your 
+      motherboard datasheet has appropriate technology.
+      Even if your hardware doesn't have IOMMU, certain PCI cards may work
+      (such as serial PCI adapters), but guest will show warning on boot, and 
+      VM execution will terminate, if guest driver will attempt to enable card 
+      bus mastering.</para>
+
+    <para>
+      It's not uncommon, that BIOS/OS disables IOMMU by default, so before any attempt to use it,
+      please make sure that
+      <orderedlist>
+        <listitem>
+            Your motherboard has IOMMU unit.
+        </listitem>
+        <listitem>
+            Your CPU supports IOMMU.
+        </listitem>
+        <listitem>
+            IOMMU is enabled in the BIOS.
+        </listitem>
+        <listitem>
+            Your Linux kernel compiled with IOMMU support (including DMA remapping, see 
+            <computeroutput>CONFIG_DMAR</computeroutput> kernel compilation option).
+        </listitem>
+        <listitem>
+            Your Linux kernel recognizes and uses IOMMU unit (<computeroutput>intel-iommu=on</computeroutput> 
+            boot option could be needed). Search for DMAR in kernel boot log. 
+        </listitem>
+      </orderedlist>      
+    </para>
+  
+    <para>Once you made sure that host kernel supports IOMMU, next step is to select
+      PCI card, and attach it to the guest. To figure out list of available PCI devices,
+      use  <computeroutput>lspci</computeroutput> command. Output will look like this
+      <screen>
+        01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
+        01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
+        02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit Ethernet controller (rev 03)
+        03:00.0 SATA controller: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
+        03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
+        06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)
+      </screen>
+      First column here is a PCI address (in format <computeroutput>bus:device.function</computeroutput>). 
+      This address could be used to identify device for further operations. 
+      For example, to attach PCI network controller on system listed above, 
+      to second PCI bus in the guest, as device 5, function 0, use the following command:
+      <screen>VBoxManage modifyvm "VM name" --attachpci 02:00.0@01:05.0</screen>
+      To detach same device, use 
+      <screen>VBoxManage modifyvm "VM name" --detachpci 02:00.0</screen>
+      Please note, that both host and guest could freely assign different PCI address to 
+      card attached during runtime, so those addresses only apply to address of card at 
+      the moment of attachment (host), and during BIOS PCI init (guest).
+    </para>
+    
+    <para>If virtual machine has PCI device attached, certain limitations apply.
+      <orderedlist>
+         <listitem>
+          Only PCI cards with non-shared interrupts (such as using MSI on host) can be 
+          supported at the moment.
+        </listitem>
+        <listitem>
+          No guest state can be reliably saved/restored (as PCI card internal state could
+          not be retrieved).
+        </listitem>
+        <listitem>
+          Teleportation (live migration) doesn't work (for the same reason).
+        </listitem>
+        <listitem>
+          No lazy physical memory allocation, host preallocates whole RAM on startup
+          (as we cannot catch physical hardware access to physical memory).
+        </listitem>        
+      </orderedlist>      
+    </para>
+       
+  </sect1>
+
 
   <sect1>