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

[Boris Fiuczynski]

Sorry about the time travel.
I will try to give up that super power... :(

On 4/14/20 11:06 PM, Boris Fiuczynski wrote:
> 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