External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-02-22 11:22:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improve PCI topology and hotplug guidelines

Browse Source 
Address some minor flaws in the original document that
were pointed out during review.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
This commit is contained in:
Andrea Bolognani 2017-08-17 14:11:56 +02:00
parent 64357c3f93
commit 11d5271ebb
1 changed files with 32 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/pci-hotplug.html.in
View File

@ -13,10 +13,12 @@
<p> <p>
The reason for this apparent limitation is the fact that each The reason for this apparent limitation is the fact that each
hotplugged PCI device might require additional PCI controllers to hotplugged PCI device might require additional PCI controllers to
be added to the guest, and libvirt has no way of knowing in advance be added to the guest. Since most PCI controllers can't be
how many devices will be hotplugged during the guest's lifetime, hotplugged, they need to be added before the guest is started;
thus making it impossible to automatically provide the right amount however, libvirt has no way of knowing in advance how many devices
of PCI controllers: any arbitrary number would end up being too big will be hotplugged during the guest's lifetime, thus making it
impossible to automatically provide the right amount of PCI
controllers: any arbitrary number would end up being too big
for some users, and too small for others. for some users, and too small for others.
</p> </p>
<p> <p>
@ -52,6 +54,14 @@
and supports hotplugging a single PCI Express device, either and supports hotplugging a single PCI Express device, either
emulated or assigned from the host. emulated or assigned from the host.
</p> </p>
<p>
If you have a very specific use case, such as the appliances
used by <a href="http://libguestfs.org/">libguestfs</a> behind
the scenes to access disk images, and this automatically-added
<code>pcie-root-port</code> controller ends up being a nuisance,
you can prevent libvirt from adding it by manually managing PCI
controllers and addresses according to your needs.
</p>
<p> <p>
Slots on the <code>pcie-root</code> controller do not support Slots on the <code>pcie-root</code> controller do not support
hotplug, so the device will be hotplugged into the hotplug, so the device will be hotplugged into the
@ -72,6 +82,12 @@
information you need to provide: libvirt will fill in the information you need to provide: libvirt will fill in the
remaining details automatically. remaining details automatically.
</p> </p>
<p>
Note that if you're adding PCI controllers to a guest and at
the same time you're also adding PCI devices, some of the
controllers will be used for the newly-added devices and won't
be available for hotplug once the guest has been started.
</p>
<p> <p>
If you expect to hotplug legacy PCI devices, then you will need If you expect to hotplug legacy PCI devices, then you will need
specialized controllers, since all those mentioned above are specialized controllers, since all those mentioned above are
@ -84,7 +100,8 @@
<p> <p>
and you'll be able to hotplug up to 31 legacy PCI devices, and you'll be able to hotplug up to 31 legacy PCI devices,
either emulated or assigned from the host. either emulated or assigned from the host, in the slots
from 0x01 to 0x1f of the <code>pci-bridge</code> controller.
</p> </p>
<h3><a name="x86_64-i440fx">i440fx (pc) machine type</a></h3> <h3><a name="x86_64-i440fx">i440fx (pc) machine type</a></h3>
@ -98,9 +115,10 @@
&lt;controller type='pci' index='0' model='pci-root'/&gt;</pre> &lt;controller type='pci' index='0' model='pci-root'/&gt;</pre>
<p> <p>
where each of the 31 slots on the <code>pci-root</code> where each of the 31 slots (from 0x01 to 0x1f) on the
controller is hotplug capable and can accept a legacy PCI <code>pci-root</code> controller is hotplug capable and
device, either emulated or assigned from the guest. can accept a legacy PCI device, either emulated or
assigned from the guest.
</p> </p>
<h2><a name="ppc64">ppc64 architecture</a></h2> <h2><a name="ppc64">ppc64 architecture</a></h2>
@ -119,12 +137,12 @@
&lt;/controller&gt;</pre> &lt;/controller&gt;</pre>
<p> <p>
The 31 slots on a <code>pci-root</code> controller are all The 31 slots, from 0x01 to 0x1f, on a <code>pci-root</code>
hotplug capable and, despite the name suggesting otherwise, controller are all hotplug capable and, despite the name
starting with QEMU 2.9 all of them can accept PCI Express suggesting otherwise, starting with QEMU 2.9 all of them
devices in addition to legacy PCI devices; however, can accept PCI Express devices in addition to legacy PCI
libvirt will only place emulated devices on the default devices; however, libvirt will only place emulated devices
<code>pci-root</code> controller. on the default <code>pci-root</code> controller.
</p> </p>
<p> <p>
In order to take advantage of improved error reporting and In order to take advantage of improved error reporting and