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

[Boris Fiuczynski]

On 4/16/20 2:21 PM, Andrea Bolognani wrote:
> 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.
> 
> ?
Yes, it does bring the documents intention across better.

> 
>> 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
> I added the sentence "Also fid does not define slot or function of the 
PCI address." following the "Note...topology." sentence.

> with the fid nowhere to be seen. Can you explain what "slot" means
> in this context?
I guess that you now ask to explain it makes it most likely that it 
should be explained here, correct?

The fid (function id) is not used within the PCI address which the guest 
OS generates for the PCI device. Only the uid is used in the PCI address 
to define the PCI domain. PCI bus, slot and function address elements 
are always 0. This might change in the future BUT it would/will still be 
completely unrelated to the PCI attributes bus, slot and function of the 
address element.
The fid is used in the sysfs (/sys/bus/pci/slots/...) to represent the 
PCI card such e.g. you can power on or off the PCI card.
This is what results in guest OS.
root at qemus390x:~# ls /sys/bus/pci/slots/
00000003
root at qemus390x:~# cat /sys/bus/pci/devices/0007\:00\:00.0/function_id
0x00000003

> 
> 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].
[my explanation]
the fid is used as the PCI devices slot in the sysfs.

Does that together with the additional sentence above make more "wacky" 
sense?

> 
> Does that sound good?
> 
Sure.
Since I started editing in the pci-addresses file already, I would try 
to also include these changes if you agree to them.
If you want I can also include your changes in the document introduction.


-- 
Mit freundlichen Grüßen/Kind regards
    Boris Fiuczynski

IBM Deutschland Research & Development GmbH
Vorsitzender des Aufsichtsrats: Gregor Pillen
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294