[PATCH 6/8] docs: Convert 'pci-hotplug' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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>
-&lt;controller type='pci' index='0' model='pcie-root'/&gt;
-&lt;controller type='pci' index='1' model='pcie-root-port'&gt;
-  &lt;model name='pcie-root-port'/&gt;
-  &lt;target chassis='1' port='0x10'/&gt;
-  &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/&gt;
-&lt;/controller&gt;</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>
-&lt;controller type='pci' model='pcie-root'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;
-&lt;controller type='pci' model='pcie-root-port'/&gt;</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>
-&lt;controller type='pci' model='pcie-to-pci-bridge'/&gt;</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>
-&lt;controller type='pci' index='0' model='pci-root'/&gt;</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>
-&lt;controller type='pci' index='0' model='pci-root'&gt;
-  &lt;model name='spapr-pci-host-bridge'/&gt;
-  &lt;target index='0'/&gt;
-&lt;/controller&gt;</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>
-&lt;controller type='pci' model='pci-root'/&gt;
-&lt;controller type='pci' model='pci-root'/&gt;
-&lt;controller type='pci' model='pci-root'/&gt;</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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux