ia64/xen-unstable

changeset 19009:97f8d6453fda

passthough: MSI-INTx translation documentation

Signed-off-by: Qing He <qing.he@intel.com>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Jan 08 11:27:11 2009 +0000 (2009-01-08)
parents 3a92e1a446d9
children 292919f61238
files docs/misc/vtd.txt tools/examples/xmexample.hvm
line diff
     1.1 --- a/docs/misc/vtd.txt	Thu Jan 08 11:26:58 2009 +0000
     1.2 +++ b/docs/misc/vtd.txt	Thu Jan 08 11:27:11 2009 +0000
     1.3 @@ -38,6 +38,30 @@ Enable MSI/MSI-x for assigned devices
     1.4  Add "msi=1" option in kernel line of host grub.
     1.5  
     1.6  
     1.7 +MSI-INTx translation for passthrough devices in HVM
     1.8 +---------------------------------------------------
     1.9 +
    1.10 +If the assigned device uses a physical IRQ that is shared by more than
    1.11 +one device among multiple domains, there may be significant impact on
    1.12 +device performance. Unfortunately, this is quite a common case if the
    1.13 +IO-APIC (INTx) IRQ is used. MSI can avoid this issue, but was only
    1.14 +available if the guest enables it.
    1.15 +
    1.16 +With MSI-INTx translation turned on, Xen enables device MSI if it's
    1.17 +available, regardless of whether the guest uses INTx or MSI. If the
    1.18 +guest uses INTx IRQ, Xen will inject a translated INTx IRQ to guest's
    1.19 +virtual ioapic whenever an MSI message is received. This reduces the
    1.20 +interrupt sharing of the system. If the guest OS enables MSI or MSI-X,
    1.21 +the translation is automatically turned off.
    1.22 +
    1.23 +To enable or disable MSI-INTx translation globally, add "pci_msitranslate"
    1.24 +in the config file:
    1.25 +	pci_msitranslate = 1         (default is 1)
    1.26 +
    1.27 +To override for a specific device:
    1.28 +	pci = [ '01:00.0,msitranslate=0', '03:00.0' ]
    1.29 +
    1.30 +
    1.31  Caveat on Conventional PCI Device Passthrough
    1.32  ---------------------------------------------
    1.33  
    1.34 @@ -80,6 +104,11 @@ 2 virtual PCI slots (6~7) are reserved i
    1.35  
    1.36  	[root@vt-vtd ~]# xm pci-attach HVMDomainVtd 0:2:0.0 7
    1.37  
    1.38 +    To specify options for the device, use -o or --options=. Following command would disable MSI-INTx translation for the device
    1.39 +
    1.40 +	[root@vt-vtd ~]# xm pci-attach -o msitranslate=0 0:2:0.0 7
    1.41 +
    1.42 +
    1.43  VTd hotplug usage model:
    1.44  ------------------------
    1.45  
     2.1 --- a/tools/examples/xmexample.hvm	Thu Jan 08 11:26:58 2009 +0000
     2.2 +++ b/tools/examples/xmexample.hvm	Thu Jan 08 11:27:11 2009 +0000
     2.3 @@ -288,6 +288,39 @@ serial='pty'
     2.4  #  'x' -> we don't care (do not check)
     2.5  #  's' -> the bit must be the same as on the host that started this VM
     2.6  
     2.7 +#-----------------------------------------------------------------------------
     2.8 +#   Configure passthrough PCI{,-X,e} devices:
     2.9 +#
    2.10 +#   pci=[ '[SSSS:]BB:DD.F[,option1[,option2[...]]]', ... ]
    2.11 +#
    2.12 +#   [SSSS]:BB:DD.F  "bus segment:bus:device.function"(1) of the device to
    2.13 +#                   be assigned, bus segment is optional. All fields are
    2.14 +#                   in hexadecimal and no field should be longer than that
    2.15 +#                   as shown in the pattern. Successful assignment may need
    2.16 +#                   certain hardware support and additional configurations
    2.17 +#                   (e.g. VT-d, see docs/misc/vtd.txt for more details).
    2.18 +#
    2.19 +#       (1) bus segment is sometimes also referred to as the PCI "domain",
    2.20 +#           not to be confused with Xen domain.
    2.21 +#
    2.22 +#
    2.23 +#   optionN         per-device options in "key=val" format. Current
    2.24 +#                   available options are:
    2.25 +#                   - msitranslate=0|1
    2.26 +#                      per-device overriden of pci_msitranslate, see below
    2.27 +#
    2.28 +#pci=[ '07:00.0', '07:00.1' ]
    2.29 +
    2.30 +#   MSI-INTx translation for MSI capable devices:
    2.31 +#
    2.32 +#   If it's set, Xen will enable MSI for the device that supports it even
    2.33 +# if the guest don't use MSI. In the case, an IO-APIC type interrupt will
    2.34 +# be injected to the guest every time a corresponding MSI message is
    2.35 +# received.
    2.36 +#   If the guest enables MSI or MSI-X, the translation is automatically
    2.37 +# turned off.
    2.38 +# 
    2.39 +#pci_msitranslate=1
    2.40  
    2.41  #-----------------------------------------------------------------------------
    2.42  #   Configure PVSCSI devices: