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

[Cornelia Huck]

On Wed, 15 Apr 2020 16:23:46 +0200
Boris Fiuczynski <fiuczy at linux.ibm.com> wrote:

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

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

Yes.

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

Ok, now I dimly remember something like that. Still confusing, but
makes sense.

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

Well, I don't have commit rights O:-)

> Once I understand you confusion above I will provide a patch...

I'd say just go ahead.