[libvirt] [PATCH] docs: Add "PCI topology and hotplug" guidelines

[Andrea Bolognani]

On Tue, 2017-08-08 at 10:06 -0400, Laine Stump wrote:
> > +      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
> > +      for some users, and too small for others.
> 
> Of course we all know this, but you haven't said here that PCI
> controllers in general cannot themselves be hotplugged (although the new
> pcie-pci-bridge *will* be hotpluggable, as long as the OS supports that).

That's a good point, I'll mention it.

> > +    <h3><a name="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>
> 
> Didn't we include some trick in there (requested for libguestfs
> appliances) that allows creating a config that has no pcie-root-ports?

Yeah, we had something like that but I can't recall the
specifics at the moment. I'll look it up and add a note
about it.

> > +      <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-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.
> > +    </p>
> 
> Maybe a note here pointing out that if you add root-ports and new
> endpoint devices at the same time, the endpoint devices will
> automatically be attached to the manually added root-ports, so if you're
> trying to end up with spares, you'll need to manually add enough for the
> endpoints, plus the number of spares you want (you won't need to address
> any of the controllers or endpoints though).

Sure.

> > +    <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='dmi-to-pci-bridge'/>
> > +<controller type='pci' model='pci-bridge'/></pre>
> > +
> > +    <p>
> > +      and you'll be able to hotplug up to 31 legacy PCI devices,
> > +      either emulated or assigned from the host.
> > +    </p>
> 
> Maybe mention that it's slot 1 - 31 because slot 0 is reserved.

Not sure that's necessarily in scope for the document, since
in general you'll let libvirt pick the slot for you.

That said, adding it would hardly make a difference when it
comes to document size, so why not I guess :)

> > +    <p>
> > +      The default PCI topology for the <code>pseries</code> machine
> > +      type looks like
> > +    </p>
> > +
> > +<pre>
> > +<controller type='pci' index='0' model='pcie-root'>
> 
> You mean pci-root, right? (I always get these mixed up for PPC, since I
> don't actually use it).

Of course I did, and in fact I got it right right afterwards.
Nice catch :)

> There's of course always more that can be written, but this is a good
> and useful start, so ACK (with the few typos fixed).

Thanks, I've pushed it. I'll address the improvements you
suggested next week.

-- 
Andrea Bolognani / Red Hat / Virtualization