[PATCH] docs: add zpci information to pci-addresses.rst

[Andrea Bolognani]

On Thu, 2020-04-16 at 11:46 +0200, Boris Fiuczynski wrote:
> On 4/15/20 6:38 PM, Andrea Bolognani wrote:
> > The idea behind it was to show users that they shouldn't expect the
> > address in the domain XML to match the one in the guest OS, with a
> > few real-life examples to illustrate the point. So, I don't think
> > the details of how exactly zPCI IDs translate to guest-visible PCI
> > addresses is in scope.
> > 
> > It would be great information to have in some other document, though!
> > Is there something like that in qemu.git, or in the QEMU wiki? Those
> > are the places where I would expect it to live, since it's not really
> > tied to libvirt...
> 
> I disagree because fid is a parameter of the pci address just like 
> domain, bus, slot, function and uid.
> Besides the fact that one of the first sentences in the document is
> "When discussing PCI addresses, it's important to understand the 
> relationship between the addresses that can be seen in the domain XML 
> and those that are visible inside the guest OS."

You're right, the current language is not really explaining the
purpose of the document correctly - it's making it sound like it's
the complete guide to all things PCI addresses, which it's definitely
not intended to be.

What about

  Looking at the configuration for a guest, it would be reasonable
  to expect that each PCI device would show up in the guest OS with
  a PCI address that matches the one present in the corresponding
  ``<address>`` element of the domain XML, but that's not guaranteed
  to happen and will in fact not be the case in all but the simplest
  scenarios.

?

> as a document reader/user of libvirt I would not expect to search around 
> in other documentation for fid if all other parameters are correlated here.
> 
> So how about a short explanatory sentence for fid like:
> "The slot for the PCI device in the guest OS is defined by the fid 
> (function id)."

The document already contains the following sentence:

  [...] the addresses there are generated from the information
  provided via the zpci element (in fact, from the uid).

I'm not sure what "slot" means in the sentence you suggest. It
doesn't seem to be the same as slot in domain:bus:slot.function,
because in the second zPCI example that was removed

  <zpci uid='0x0007' fid='0x00000003'/>

would result in

  0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device

with the fid nowhere to be seen. Can you explain what "slot" means
in this context?

Anyway, we can tweak the existing sentence to read something like

  [...] the addresses there are generated from the information
  provided via the zpci element: the uid is used as PCI domain, and
  the fid is used as [your explanation here].

Does that sound good?

-- 
Andrea Bolognani / Red Hat / Virtualization