[libvirt] [PATCH] docs: Improve PCI topology and hotplug guidelines

[Erik Skultety]

On Thu, Aug 17, 2017 at 02:24:14PM +0200, Andrea Bolognani wrote:
> Address some minor flaws in the original document that
> were pointed out during review.
>
> Signed-off-by: Andrea Bolognani <abologna at redhat.com>
> ---
>  docs/pci-hotplug.html.in | 46 ++++++++++++++++++++++++++++++++--------------
>  1 file changed, 32 insertions(+), 14 deletions(-)
>
> diff --git a/docs/pci-hotplug.html.in b/docs/pci-hotplug.html.in
> index 809e36f5d..a90d47bc3 100644
> --- a/docs/pci-hotplug.html.in
> +++ b/docs/pci-hotplug.html.in
> @@ -13,10 +13,12 @@
>      <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, and 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
> +      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>
> @@ -53,6 +55,14 @@
>        emulated or assigned from the host.
>      </p>
>      <p>
> +      If you have a very specialized use case, such as the appliances

Specialized use case doesn't sound right to my ears, especially because use
case describes and action/situation/process and in doing that it should be very
clear ==> "specific", but I might be wrong of course and you indeed need a
specific set of skills to cope with it :).

> +      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 you needs.

s/you/your

> +    </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
> @@ -73,6 +83,12 @@
>        remaining details automatically.
>      </p>
>      <p>
> +      Note that if you're adding PCI controllers to a guest at the
> +      same time you're also adding PCI devices, some of the

I think you should use either:
    ... to a guest *and* at the same time you're also adding...
or:
    ... at the same time *as* adding PCI devices...

> +      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

^right you are (w/r/t specialized controller).

These were just stylistic nitpicks I noted, as you've addressed the notes from
the previous review in a very clear manner, so no issue there from my
perspective.

ACK

Erik