One internal reference was modified to work properly. Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/meson.build | 2 +- docs/pci-hotplug.html.in | 185 --------------------------------------- docs/pci-hotplug.rst | 146 ++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+), 186 deletions(-) delete mode 100644 docs/pci-hotplug.html.in create mode 100644 docs/pci-hotplug.rst diff --git a/docs/meson.build b/docs/meson.build index 3bdea1407d..cdf78a04b4 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files = [ 'internals', 'java', 'logging', - 'pci-hotplug', 'php', 'python', 'remote', @@ -104,6 +103,7 @@ docs_rst_files = [ 'newreposetup', 'nss', 'pci-addresses', + 'pci-hotplug', 'platforms', 'programming-languages', 'securityprocess', diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in deleted file mode 100644 index d61af1930e..0000000000 --- a/docs/pci-hotplug.html.in +++ /dev/null @@ -1,185 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - <h1>PCI topology and hotplug</h1> - - <ul id="toc"></ul> - - <p> - Perhaps surprisingly, most libvirt guests support only limited PCI - device hotplug out of the box, or even none at all. - </p> - <p> - The reason for this apparent limitation is the fact that each - hotplugged PCI device might require additional PCI controllers to - be added to the guest. Since most PCI controllers can't be - hotplugged, they need to be added before the guest is started; - however, libvirt has no way of knowing in advance how many devices - 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. - </p> - <p> - Ultimately, the user is the only one who knows how much the guest - will need to grow dynamically, so the responsibility of planning - a suitable PCI topology in advance falls on them. - </p> - <p> - This document aims at providing all the information needed to - successfully plan the PCI topology of a guest. Note that the - details can vary a lot between architectures and even machine - types, hence the way it's organized. - </p> - - <h2><a id="x86_64">x86_64 architecture</a></h2> - - <h3><a id="x86_64-q35">q35 machine type</a></h3> - - <p> - This is a PCI Express native machine type. The default PCI topology - looks like - </p> - -<pre> -<controller type='pci' index='0' model='pcie-root'/> -<controller type='pci' index='1' model='pcie-root-port'> - <model name='pcie-root-port'/> - <target chassis='1' port='0x10'/> - <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> -</controller></pre> - - <p> - and supports hotplugging a single PCI Express device, either - emulated or assigned from the host. - </p> - <p> - If you have a very specific use case, such as the appliances - used by <a href="https://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> - Slots on the <code>pcie-root</code> controller do not support - hotplug, so the device will be hotplugged into the - <code>pcie-root-port</code> controller. If you plan to hotplug - more than a single PCI Express device, you should add a suitable - number of <code>pcie-root-port</code> controllers when defining - the guest: for example, add - </p> - -<pre> -<controller type='pci' model='pcie-root'/> -<controller type='pci' model='pcie-root-port'/> -<controller type='pci' model='pcie-root-port'/> -<controller type='pci' model='pcie-root-port'/></pre> - - <p> - if you expect to hotplug up to three PCI Express devices, - either emulated or assigned from the host. That's all the - information you need to provide: libvirt will fill in the - remaining details automatically. Note that you need to add - the <code>pcie-root</code> controller along with the - <code>pcie-root-port</code> controllers or you will get an - error. - </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> - If you expect to hotplug legacy PCI devices, then you will need - specialized controllers, since all those mentioned above are - intended for PCI Express devices only: add - </p> - -<pre> -<controller type='pci' model='pcie-to-pci-bridge'/></pre> - - <p> - and you'll be able to hotplug up to 31 legacy PCI devices, - either emulated or assigned from the host, in the slots - from 0x01 to 0x1f of the <code>pcie-to-pci-bridge</code> controller. - </p> - - <h3><a id="x86_64-i440fx">i440fx (pc) machine type</a></h3> - - <p> - This is a legacy PCI native machine type. The default PCI - topology looks like - </p> - -<pre> -<controller type='pci' index='0' model='pci-root'/></pre> - - <p> - where each of the 31 slots (from 0x01 to 0x1f) on the - <code>pci-root</code> controller is hotplug capable and - can accept a legacy PCI device, either emulated or - assigned from the guest. - </p> - - <h2><a id="ppc64">ppc64 architecture</a></h2> - - <h3><a id="ppc64-pseries">pseries machine type</a></h3> - - <p> - The default PCI topology for the <code>pseries</code> machine - type looks like - </p> - -<pre> -<controller type='pci' index='0' model='pci-root'> - <model name='spapr-pci-host-bridge'/> - <target index='0'/> -</controller></pre> - - <p> - The 31 slots, from 0x01 to 0x1f, on a <code>pci-root</code> - controller are all hotplug capable and, despite the name - suggesting otherwise, starting with QEMU 2.9 all of them - can accept PCI Express devices in addition to legacy PCI - devices; however, libvirt will only place emulated devices - on the default <code>pci-root</code> controller. - </p> - <p> - In order to take advantage of improved error reporting and - recovering capabilities, PCI devices assigned from the - host need to be isolated by placing each on a separate - <code>pci-root</code> controller, which has to be prepared - in advance for hotplug to work: for example, add - </p> - -<pre> -<controller type='pci' model='pci-root'/> -<controller type='pci' model='pci-root'/> -<controller type='pci' model='pci-root'/></pre> - - <p> - if you expect to hotplug up to three PCI devices assigned - from the host. - </p> - - <h2><a id="aarch64">aarch64 architecture</a></h2> - - <h3><a id="aarch64-virt">mach-virt (virt) machine type</a></h3> - - <p> - This machine type mostly behaves the same as the - <a href="#x86_64-q35">q35 machine type</a>, so you can just - refer to that section for information. - </p> - <p> - The only difference worth mentioning is that using legacy - PCI for <code>mach-virt</code> guests is extremely uncommon, - so you'll probably never need to add controllers other than - <code>pcie-root-port</code>. - </p> - - </body> -</html> diff --git a/docs/pci-hotplug.rst b/docs/pci-hotplug.rst new file mode 100644 index 0000000000..bc7fdbbd86 --- /dev/null +++ b/docs/pci-hotplug.rst @@ -0,0 +1,146 @@ +======================== +PCI topology and hotplug +======================== + +.. contents:: + +Perhaps surprisingly, most libvirt guests support only limited PCI device +hotplug out of the box, or even none at all. + +The reason for this apparent limitation is the fact that each hotplugged PCI +device might require additional PCI controllers to be added to the guest. Since +most PCI controllers can't be hotplugged, they need to be added before the guest +is started; however, libvirt has no way of knowing in advance how many devices +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. + +Ultimately, the user is the only one who knows how much the guest will need to +grow dynamically, so the responsibility of planning a suitable PCI topology in +advance falls on them. + +This document aims at providing all the information needed to successfully plan +the PCI topology of a guest. Note that the details can vary a lot between +architectures and even machine types, hence the way it's organized. + +x86_64 architecture +------------------- + +q35 machine type +~~~~~~~~~~~~~~~~ + +This is a PCI Express native machine type. The default PCI topology looks like + +:: + + <controller type='pci' index='0' model='pcie-root'/> + <controller type='pci' index='1' model='pcie-root-port'> + <model name='pcie-root-port'/> + <target chassis='1' port='0x10'/> + <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/> + </controller> + +and supports hotplugging a single PCI Express device, either emulated or +assigned from the host. + +If you have a very specific use case, such as the appliances used by +`libguestfs <https://libguestfs.org/>`__ behind the scenes to access disk +images, and this automatically-added ``pcie-root-port`` controller ends up being +a nuisance, you can prevent libvirt from adding it by manually managing PCI +controllers and addresses according to your needs. + +Slots on the ``pcie-root`` controller do not support hotplug, so the device will +be hotplugged into the ``pcie-root-port`` controller. If you plan to hotplug +more than a single PCI Express device, you should add a suitable number of +``pcie-root-port`` controllers when defining the guest: for example, add + +:: + + <controller type='pci' model='pcie-root'/> + <controller type='pci' model='pcie-root-port'/> + <controller type='pci' model='pcie-root-port'/> + <controller type='pci' model='pcie-root-port'/> + +if you expect to hotplug up to three PCI Express devices, either emulated or +assigned from the host. That's all the information you need to provide: libvirt +will fill in the remaining details automatically. Note that you need to add the +``pcie-root`` controller along with the ``pcie-root-port`` controllers or you +will get an error. + +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. + +If you expect to hotplug legacy PCI devices, then you will need specialized +controllers, since all those mentioned above are intended for PCI Express +devices only: add + +:: + + <controller type='pci' model='pcie-to-pci-bridge'/> + +and you'll be able to hotplug up to 31 legacy PCI devices, either emulated or +assigned from the host, in the slots from 0x01 to 0x1f of the +``pcie-to-pci-bridge`` controller. + +i440fx (pc) machine type +~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a legacy PCI native machine type. The default PCI topology looks like + +:: + + <controller type='pci' index='0' model='pci-root'/> + +where each of the 31 slots (from 0x01 to 0x1f) on the ``pci-root`` controller is +hotplug capable and can accept a legacy PCI device, either emulated or assigned +from the guest. + +ppc64 architecture +------------------ + +pseries machine type +~~~~~~~~~~~~~~~~~~~~ + +The default PCI topology for the ``pseries`` machine type looks like + +:: + + <controller type='pci' index='0' model='pci-root'> + <model name='spapr-pci-host-bridge'/> + <target index='0'/> + </controller> + +The 31 slots, from 0x01 to 0x1f, on a ``pci-root`` controller are all hotplug +capable and, despite the name suggesting otherwise, starting with QEMU 2.9 all +of them can accept PCI Express devices in addition to legacy PCI devices; +however, libvirt will only place emulated devices on the default ``pci-root`` +controller. + +In order to take advantage of improved error reporting and recovering +capabilities, PCI devices assigned from the host need to be isolated by placing +each on a separate ``pci-root`` controller, which has to be prepared in advance +for hotplug to work: for example, add + +:: + + <controller type='pci' model='pci-root'/> + <controller type='pci' model='pci-root'/> + <controller type='pci' model='pci-root'/> + +if you expect to hotplug up to three PCI devices assigned from the host. + +aarch64 architecture +-------------------- + +mach-virt (virt) machine type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This machine type mostly behaves the same as the `q35 machine +type <#q35-machine-type>`__, so you can just refer to that section for +information. + +The only difference worth mentioning is that using legacy PCI for ``mach-virt`` +guests is extremely uncommon, so you'll probably never need to add controllers +other than ``pcie-root-port``. -- 2.35.1
