[PATCH 2/2] docs: Improve zPCI section in pci-addresses.rst

[Boris Fiuczynski]

On 4/16/20 6:14 PM, Cornelia Huck wrote:
> On Thu, 16 Apr 2020 17:56:18 +0200
> Boris Fiuczynski <fiuczy at linux.ibm.com> wrote:
> 
>> Improving the zPCI example by choosing more distinct values and
>> adding explanation for fid.
>>
>> Signed-off-by: Boris Fiuczynski <fiuczy at linux.ibm.com>
>> ---
>>   docs/pci-addresses.rst | 15 ++++++++-------
>>   1 file changed, 8 insertions(+), 7 deletions(-)
>>
>> diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst
>> index 7c8e9edd73..4492389da5 100644
>> --- a/docs/pci-addresses.rst
>> +++ b/docs/pci-addresses.rst
>> @@ -176,14 +176,14 @@ In the simplest case, the following XML snippet
>>       <model name='pci-bridge'/>
>>       <target chassisNr='1'/>
>>       <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'>
>> -      <zpci uid='0x0002' fid='0x00000001'/>
>> +      <zpci uid='0x0001' fid='0x00000000'/>
> 
> Why this change? The pci-bridge does not show up in the guest anyway.
My assumption was that uid and fid for this would be autogenerated.
Since uid 0x0001 and fid 0x00000000 have been freed up due to the change 
below this would be the autogenerated set.

> 
>>       </address>
>>     </controller>
>>     <interface type='bridge'>
>>       <source bridge='virbr0'/>
>>       <model type='virtio'/>
>>       <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'>
>> -      <zpci uid='0x0001' fid='0x00000000'/>
>> +      <zpci uid='0x0007' fid='0x00000003'/>
>>       </address>
>>     </interface>
>>   
>> @@ -191,21 +191,22 @@ will result in the following in a Linux guest:
>>   
>>   ::
>>   
>> -  0001:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
>> +  0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
>>   
>>   Note that the PCI bridge is not visible in the guest; s390x always has a flat
>> -topology.
>> +topology. Also ``fid`` does not define slot or function of the PCI address.
> 
> I find the sentence regarding 'fid' confusing. Maybe instead move up
> the explanation from below regarding uid and fid?
> 
> "The PCI address in the guest is generated from..."
> 
Lets join your proposal with Andreas and move his rewrite up to here.
Like:
...topology.
The PCI address in the guest is generated from the information provided 
via the ``zpci`` element: more specifically, ``uid`` is used as the PCI 
domain.``fid`` doesn't appear in the PCI address itself, but it will be
used in sysfs (``/sys/bus/pci/slots/$fid/...``).


>>   
>>   Neither are any changes in the PCI address visible in the guest; replacing
> 
> The 'neither' is now a bit confusing; what about
> 
> "Any changes in the PCI address are not visible in the guest..." ?
Agreed.

> 
>>   the PCI address for the ``virtio-net`` device with
>>   
>>   ::
>>   
>> -  <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'>
>> +  <address type='pci' domain='0x0000' bus='0x01' slot='0x06' function='0x4'>
>>   
>>   will result in the exactly same view in the guest, as the addresses there
> 
> If you move the fid/uid stuff up, make this
> 
> "as the fid and uid values in the zpci element remain unchanged." ?
Yes.

> 
>> -are generated from the information provided via the ``zpci`` element (in
>> -fact, from the ``uid``).
>> +are generated from the information provided via the ``zpci`` element:
>> +the ``uid`` is used as PCI domain, and the ``fid`` is used as the PCI devices
> 
> s/devices/device's/
> 
>> +slot in the sysfs.
> 
> s/the sysfs./sysfs (it does not influence the PCI device address.)/
> *
Andreas rewrite makes it clear.

> 
> 
> 
>>   
>>   
>>   Device assignment
> 


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