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

[Boris Fiuczynski]

On 4/15/20 12:51 PM, Cornelia Huck wrote:
> Add some information on how pci address work on s390x.
> 
> Signed-off-by: Cornelia Huck <cohuck at redhat.com>
Conny, thanks for catching this "wacky case"... :)
I took the liberty to remove "completely" because there needs to be room 
for pci multifunction support... :D

> ---
>   docs/pci-addresses.rst | 63 ++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 63 insertions(+)
> 
> diff --git a/docs/pci-addresses.rst b/docs/pci-addresses.rst
> index 923783a151b0..9e241a24fcfb 100644
> --- a/docs/pci-addresses.rst
> +++ b/docs/pci-addresses.rst
> @@ -184,3 +184,66 @@ guest OS rather than as ``0001:08:00.1``, which is the address of the
>   device on the host.
>   
>   Of course, all the rules and behaviors described above still apply.
> +
> +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.


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


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


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