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

[Boris Fiuczynski]

On 4/17/20 11:02 AM, Cornelia Huck wrote:
> On Fri, 17 Apr 2020 10:50:02 +0200
> Boris Fiuczynski <fiuczy at linux.ibm.com> wrote:
> 
>> 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.
> 
> If that makes the XML look saner, no objection.
> 
>>
>>>    
>>>>        </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/...``).
> 
> Sounds good.
> 
> (Also the rest of the changes.)
> 
Before I break the r-b chain as well... Is that your r-b? :)


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