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

[Cornelia Huck]

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?

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

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