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

[Boris Fiuczynski]

On 4/15/20 3:42 PM, Cornelia Huck wrote:
> On Tue, 14 Apr 2020 23:06:47 +0200
> Boris Fiuczynski <fiuczy at linux.ibm.com> wrote:
> 
>> On 4/15/20 12:51 PM, Cornelia Huck wrote:
> 
>>> +zPCI addresses
>>> +==============
>>> +
>>> +For s390x machines, PCI addresses are handled yet differently. No
>>> +topology information is relayed in the PCI addresses; instead, the
>>> +``fid`` and ``uid`` elements of the ``zpci`` device convey information.
>> Should it be mentioned that qemu uses the pci address internally to plug
>> the device into its pci bus since the pci address as far as I know must
>> still be properly provided or generated.
> 
> Not sure how much is autogenerated; however, as this document talks
> about how pci addresses in the xml translate to pci addresses in the
> guest, I think we can simply ignore it?
ok. I just wanted to explain why the pci address part still exists and 
why libvirt also will autogenerate all other required bridges.

> 
>>
>>
>>> +In the simplest case, the following XML snippet
>>> +
>>> +::
>>> +
>>> +      <controller type='pci' index='0' model='pci-root'/>
>>> +      <controller type='pci' index='1' model='pci-bridge'>
>>> +        <model name='pci-bridge'/>
>>> +        <target chassisNr='1'/>
>>> +        <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'>
>>> +          <zpci uid='0x0002' fid='0x00000001'/>
>>> +        </address>
>>> +      </controller>
>>> +      <interface type='bridge'>
>>> +        <mac address='02:ca:fe:fa:ce:04'/>
>>> +        <source bridge='virbr0'/>
>>> +        <model type='virtio'/>
>>> +        <address type='pci' domain='0x0000' bus='0x01' slot='0x01' function='0x0'>
>>> +          <zpci uid='0x0001' fid='0x00000000'/>
>>> +        </address>
>>> +      </interface>
>>> +
>>> +will result in the following in a Linux guest::
>>> +
>>> +  0001: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.
>>> +
>>> +Neither are any changes in the PCI address visible in the guest; replacing
>>> +the PCI address for the virtio-net device with
>>> +
>>> +::
>>> +
>>> +  <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'>
>>> +
>>> +will result in the exactly same view in the guest, as the addresses there
>>> +are generated from the information provided via the ``zpci`` element (in
>>> +fact, from the ``uid``).
>>> +
>> This explains that the uid is used by the guest to define the pci domain
>> of the guest device.
>> How about an addition for the fid? Something like:
>>
>> The function id 'fid' defines the slot address of the pci card in the
>> guest. It can be observed in the guest at /sys/bus/pci/slots. In the
>> example given above the card would be at /sys/bus/pci/slots/00000000.
> 
> Hm, is it intentional that this does not show up in the actual pci
> address? But maybe I'm confused.
Are you referring to the slot of the pci address?

If yes, the pci slot does not provided the required address space for 
the function id. Also we once said that the pci bus in qemu would be 
like the pci bus of the CEC and the firmware does provide a a function 
id for every pci function. The zpci fid does one allow to do the same.

> 
>>
>>
>>> +Therefore, replacing the virtio-net device definition with the following XML
>>> +snippet
>>> +
>>> +::
>>> +
>>> +      <interface type='bridge'>
>>> +        <mac address='02:ca:fe:fa:ce:04'/>
>>> +        <source bridge='virbr0'/>
>>> +        <model type='virtio'/>
>>> +        <address type='pci' domain='0x0000' bus='0x01' slot='0x07' function='0x3'>
>>> +          <zpci uid='0x0007' fid='0x00000003'/>
>>> +        </address>
>>> +      </interface>
>>> +
>>> +will yield the following result in a Linux guest::
>>> +
>>> +  0007:00:00.0 Ethernet controller: Red Hat, Inc. Virtio network device
>>>    
>> and the card would be at /sys/bus/pci/slots/00000003.
> 
> Do you want to explain the fid/slot stuff in a patch on top? Despite
> your attempts at time travel, this patch has already been pushed :) 
It seems to be a very pushy time... :( no matter how many breaks are 
produced... ;)  11 minutes from patch production time to commit time. 
Why even send it for review? :D
Once I understand you confusion above I will provide a patch...


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